Configuration.java
001 /*
002  * SPDX-License-Identifier: Apache-2.0
003  *
004  * Copyright 2008-2017 the original author or authors.
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 package griffon.core;
019 
020 import javax.annotation.Nonnull;
021 import javax.annotation.Nullable;
022 import java.util.Map;
023 import java.util.Properties;
024 import java.util.ResourceBundle;
025 
026 /**
027  @author Andres Almiray
028  @since 2.0.0
029  */
030 public interface Configuration {
031     /**
032      * Searches for the key in this configuration.
033      *
034      @param key the key to search
035      @return true if the context (or its parent) contains the given key, false otherwise
036      */
037     boolean containsKey(@Nonnull String key);
038 
039     @Nonnull
040     Map<String, Object> asFlatMap();
041 
042     @Nonnull
043     ResourceBundle asResourceBundle();
044 
045     @Nonnull
046     Properties asProperties();
047 
048     /**
049      * Returns the value associated with the given key.
050      *
051      @param key the key to search
052      @return the value associated with the key or <tt>null<</tt> if not found.
053      */
054     @Nullable
055     Object get(@Nonnull String key);
056 
057     /**
058      * Returns the value associated with the given key.
059      *
060      @param key          the key to search
061      @param defaultValue the value to be returned if the key was not found
062      @param <T>          the type of the value
063      @return returns the value associated with the key, <tt>defaultValue</tt> if the key was not found
064      */
065     @Nullable
066     <T> T get(@Nonnull String key, @Nullable T defaultValue);
067 
068     /**
069      * Returns the value associated with the given key.
070      * Convenience method to use in Groovy aware environments.
071      *
072      @param key the key to search
073      @return the value associated with the key or <tt>null<</tt> if not found.
074      */
075     @Nullable
076     Object getAt(@Nonnull String key);
077 
078     /**
079      * Returns the value associated with the given key.
080      *
081      @param key          the key to search
082      @param defaultValue the value to be returned if the key was not found
083      @param <T>          the type of the value
084      @return returns the value associated with the key, <tt>defaultValue</tt> if the key was not found
085      */
086     @Nullable
087     <T> T getAt(@Nonnull String key, @Nullable T defaultValue);
088 
089     /**
090      * Finds a value associated with the given key. The value is
091      * converted to a <tt>boolean</tt> if found.
092      *
093      @param key the key to search
094      */
095     boolean getAsBoolean(@Nonnull String key);
096 
097     /**
098      * Finds a value associated with the given key. The value is
099      * converted to a <tt>boolean</tt> if found. If not found then the
100      * supplied <tt>defaultValue</tt> will be returned.
101      *
102      @param key          the key to search
103      @param defaultValue the value to be returned if the key is not found
104      */
105     boolean getAsBoolean(@Nonnull String key, boolean defaultValue);
106 
107     /**
108      * Finds a value associated with the given key. The value is
109      * converted to an <tt>int</tt> if found.
110      *
111      @param key the key to search
112      */
113     int getAsInt(@Nonnull String key);
114 
115     /**
116      * Finds a value associated with the given key. The value is
117      * converted to an <tt>int</tt> if found. If not found then the
118      * supplied <tt>defaultValue</tt> will be returned.
119      *
120      @param key          the key to search
121      @param defaultValue the value to be returned if the key is not found
122      */
123     int getAsInt(@Nonnull String key, int defaultValue);
124 
125     /**
126      * Finds a value associated with the given key. The value is
127      * converted to a <tt>long</tt> if found.
128      *
129      @param key the key to search
130      */
131     long getAsLong(@Nonnull String key);
132 
133     /**
134      * Finds a value associated with the given key. The value is
135      * converted to a <tt>long</tt> if found. If not found then the
136      * supplied <tt>defaultValue</tt> will be returned.
137      *
138      @param key          the key to search
139      @param defaultValue the value to be returned if the key is not found
140      */
141     long getAsLong(@Nonnull String key, long defaultValue);
142 
143     /**
144      * Finds a value associated with the given key. The value is
145      * converted to a <tt>float</tt> if found.
146      *
147      @param key the key to search
148      */
149     float getAsFloat(@Nonnull String key);
150 
151     /**
152      * Finds a value associated with the given key. The value is
153      * converted to a <tt>float</tt> if found. If not found then the
154      * supplied <tt>defaultValue</tt> will be returned.
155      *
156      @param key          the key to search
157      @param defaultValue the value to be returned if the key is not found
158      */
159     float getAsFloat(@Nonnull String key, float defaultValue);
160 
161     /**
162      * Finds a value associated with the given key. The value is
163      * converted to a <tt>double</tt> if found.
164      *
165      @param key the key to search
166      */
167     double getAsDouble(@Nonnull String key);
168 
169     /**
170      * Finds a value associated with the given key. The value is
171      * converted to a <tt>double</tt> if found. If not found then the
172      * supplied <tt>defaultValue</tt> will be returned.
173      *
174      @param key          the key to search
175      @param defaultValue the value to be returned if the key is not found
176      */
177     double getAsDouble(@Nonnull String key, double defaultValue);
178 
179     /**
180      * Finds a value associated with the given key. The value is
181      * converted to a <tt>String</tt> if found.
182      *
183      @param key the key to search
184      */
185     @Nullable
186     String getAsString(@Nonnull String key);
187 
188     /**
189      * Finds a value associated with the given key. The value is
190      * converted to a <tt>String</tt> if found. If not found then the
191      * supplied <tt>defaultValue</tt> will be returned.
192      *
193      @param key          the key to search
194      @param defaultValue the value to be returned if the key is not found
195      */
196     @Nullable
197     String getAsString(@Nonnull String key, @Nullable String defaultValue);
198 
199     /**
200      * /**
201      * Finds a value associated with the given key. The value is
202      * blindly cast to type <tt>T</tt> if found.
203      *
204      @param key the key to search
205      @since 2.5.0
206      */
207     @Nullable
208     <T> T getAs(@Nonnull String key);
209 
210     /**
211      * Finds a value associated with the given key. The value is
212      * blindly cast to type <tt>T</tt> if found. If not found then the
213      * supplied <tt>defaultValue</tt> will be returned.
214      *
215      @param key          the key to search
216      @param defaultValue the value to be returned if the key is not found
217      @since 2.5.0
218      */
219     @Nullable
220     <T> T getAs(@Nonnull String key, @Nullable T defaultValue);
221 
222     /**
223      * Finds a value associated with the given key. The value is
224      * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
225      *
226      @param key  the key to search
227      @param type the type to be returned
228      @since 2.5.0
229      */
230     @Nullable
231     <T> T getConverted(@Nonnull String key, @Nonnull Class<T> type);
232 
233     /**
234      * Finds a value associated with the given key. The value is
235      * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
236      *
237      @param key  the key to search
238      @param type the type to be returned
239      @param format format used to convert the value
240      @since 2.11.0
241      */
242     @Nullable
243     <T> T getConverted(@Nonnull String key, @Nonnull Class<T> type, @Nonnull String format);
244 
245     /**
246      * Finds a value associated with the given key. The value is
247      * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
248      * If not found then the supplied <tt>defaultValue</tt> will be returned.
249      *
250      @param key          the key to search
251      @param type         the type to be returned
252      @param defaultValue the value to be returned if the key is not found
253      @since 2.5.0
254      */
255     @Nullable
256     <T> T getConverted(@Nonnull String key, @Nonnull Class<T> type, @Nullable T defaultValue);
257 
258     /**
259      * Finds a value associated with the given key. The value is
260      * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
261      * If not found then the supplied <tt>defaultValue</tt> will be returned.
262      *
263      @param key          the key to search
264      @param type         the type to be returned
265      @param format format used to convert the value
266      @param defaultValue the value to be returned if the key is not found
267      @since 2.11.0
268      */
269     @Nullable
270     <T> T getConverted(@Nonnull String key, @Nonnull Class<T> type, @Nonnull String format, @Nullable T defaultValue);
271 }