001 /*
002 * Copyright 2008-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package griffon.core;
017
018 import javax.annotation.Nonnull;
019 import javax.annotation.Nullable;
020 import java.util.Set;
021
022 /**
023 * @author Andres Almiray
024 * @since 2.2.0
025 */
026 public interface Context {
027 /**
028 * Searches for the key in this context and its hierarchy.
029 *
030 * @param key the key to search
031 * @return true if the context (or its parent) contains the given key, false otherwise
032 * @since 2.4.0
033 */
034 boolean containsKey(@Nonnull String key);
035
036 /**
037 * Searches for the key in this context only.
038 *
039 * @param key the key to search
040 * @return true if the context contains the given key, false otherwise
041 */
042 boolean hasKey(@Nonnull String key);
043
044 /**
045 * Removes a key from this context. Does not affect the context's hierarchy.
046 *
047 * @param key the key to be removed
048 * @return the value associated with the key or <tt>null</tt> if there wasn't any value.
049 */
050 @Nullable
051 Object remove(@Nonnull String key);
052
053 /**
054 * Removes a key from this context. Does not affect the context's hierarchy.
055 * Blindly casts the returned value.
056 *
057 * @param key the key to be removed
058 * @return the value associated with the key or <tt>null</tt> if there wasn't any value.
059 * @since 2.5.0
060 */
061 @Nullable
062 <T> T removeAs(@Nonnull String key);
063
064 /**
065 * Removes a key from this context. Does not affect the context's hierarchy. The value is
066 * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
067 *
068 * @param key the key to be removed
069 * @param type the type to be returned
070 * @return the value associated with the key or <tt>null</tt> if there wasn't any value.
071 * @since 2.5.0
072 */
073 @Nullable
074 <T> T removeConverted(@Nonnull String key, @Nonnull Class<T> type);
075
076 /**
077 * Sets a key/value pair on this context. If the context has a parent and if the
078 * key matches a parent key then the value will shadow the parent's, that is, the parent
079 * value will not be overwritten.
080 *
081 * @param key the key to be registered
082 * @param value the value to save
083 */
084 void put(@Nonnull String key, @Nullable Object value);
085
086 /**
087 * Sets a key/value pair on this context. If the context has a parent and if the
088 * key matches a parent key then the value will shadow the parent's, that is, the parent
089 * value will not be overwritten.
090 * Convenience method to use in Groovy aware environments.
091 *
092 * @param key the key to be registered
093 * @param value the value to save
094 */
095 void putAt(@Nonnull String key, @Nullable Object value);
096
097 /**
098 * Returns the value associated with the given key. This operation will traverse
099 * up the context hierarchy until it finds a key.
100 *
101 * @param key the key to search
102 * @return the value associated with the key or <tt>null<</tt> if not found.
103 */
104 @Nullable
105 Object get(@Nonnull String key);
106
107 /**
108 * Returns the value associated with the given key. This operation will traverse
109 * up the context hierarchy until it finds a key.
110 *
111 * @param key the key to search
112 * @param defaultValue the value to be returned if the key was not found
113 * @param <T> the type of the value
114 * @return returns the value associated with the key, <tt>defaultValue</tt> if the key was not found
115 */
116 @Nullable
117 <T> T get(@Nonnull String key, @Nullable T defaultValue);
118
119 /**
120 * Returns the value associated with the given key. This operation will traverse
121 * up the context hierarchy until it finds a key.
122 * Convenience method to use in Groovy aware environments.
123 *
124 * @param key the key to search
125 * @return the value associated with the key or <tt>null<</tt> if not found.
126 */
127 @Nullable
128 Object getAt(@Nonnull String key);
129
130 /**
131 * Returns the value associated with the given key. This operation will traverse
132 * up the context hierarchy until it finds a key.
133 *
134 * @param key the key to search
135 * @param defaultValue the value to be returned if the key was not found
136 * @param <T> the type of the value
137 * @return returns the value associated with the key, <tt>defaultValue</tt> if the key was not found
138 */
139 @Nullable
140 <T> T getAt(@Nonnull String key, @Nullable T defaultValue);
141
142 /**
143 * Destroys this context. Once destroyed a context should not be used anymore.
144 */
145 void destroy();
146
147 /**
148 * Returns the parent {@code Context} if it exists.
149 *
150 * @since 2.4.0
151 */
152 @Nullable
153 Context getParentContext();
154
155 /**
156 * Returns a {@link Set} view of the keys contained in this context.
157 *
158 * @return a set view of the keys contained in this map
159 * @since 2.4.0
160 */
161 @Nonnull
162 Set<String> keySet();
163
164 /**
165 * Finds a value associated with the given key. The value is
166 * converted to a <tt>boolean</tt> if found.
167 *
168 * @param key the key to search
169 * @since 2.5.0
170 */
171 boolean getAsBoolean(@Nonnull String key);
172
173 /**
174 * Finds a value associated with the given key. The value is
175 * converted to a <tt>boolean</tt> if found. If not found then the
176 * supplied <tt>defaultValue</tt> will be returned.
177 *
178 * @param key the key to search
179 * @param defaultValue the value to be returned if the key is not found
180 * @since 2.5.0
181 */
182 boolean getAsBoolean(@Nonnull String key, boolean defaultValue);
183
184 /**
185 * Finds a value associated with the given key. The value is
186 * converted to an <tt>int</tt> if found.
187 *
188 * @param key the key to search
189 * @since 2.5.0
190 */
191 int getAsInt(@Nonnull String key);
192
193 /**
194 * Finds a value associated with the given key. The value is
195 * converted to an <tt>int</tt> if found. If not found then the
196 * supplied <tt>defaultValue</tt> will be returned.
197 *
198 * @param key the key to search
199 * @param defaultValue the value to be returned if the key is not found
200 * @since 2.5.0
201 */
202 int getAsInt(@Nonnull String key, int defaultValue);
203
204 /**
205 * Finds a value associated with the given key. The value is
206 * converted to a <tt>long</tt> if found.
207 *
208 * @param key the key to search
209 * @since 2.5.0
210 */
211 long getAsLong(@Nonnull String key);
212
213 /**
214 * Finds a value associated with the given key. The value is
215 * converted to a <tt>long</tt> if found. If not found then the
216 * supplied <tt>defaultValue</tt> will be returned.
217 *
218 * @param key the key to search
219 * @param defaultValue the value to be returned if the key is not found
220 * @since 2.5.0
221 */
222 long getAsLong(@Nonnull String key, long defaultValue);
223
224 /**
225 * Finds a value associated with the given key. The value is
226 * converted to a <tt>float</tt> if found.
227 *
228 * @param key the key to search
229 * @since 2.5.0
230 */
231 float getAsFloat(@Nonnull String key);
232
233 /**
234 * Finds a value associated with the given key. The value is
235 * converted to a <tt>float</tt> if found. If not found then the
236 * supplied <tt>defaultValue</tt> will be returned.
237 *
238 * @param key the key to search
239 * @param defaultValue the value to be returned if the key is not found
240 * @since 2.5.0
241 */
242 float getAsFloat(@Nonnull String key, float defaultValue);
243
244 /**
245 * Finds a value associated with the given key. The value is
246 * converted to a <tt>double</tt> if found.
247 *
248 * @param key the key to search
249 * @since 2.5.0
250 */
251 double getAsDouble(@Nonnull String key);
252
253 /**
254 * Finds a value associated with the given key. The value is
255 * converted to a <tt>double</tt> if found. If not found then the
256 * supplied <tt>defaultValue</tt> will be returned.
257 *
258 * @param key the key to search
259 * @param defaultValue the value to be returned if the key is not found
260 * @since 2.5.0
261 */
262 double getAsDouble(@Nonnull String key, double defaultValue);
263
264 /**
265 * Finds a value associated with the given key. The value is
266 * converted to a <tt>String</tt> if found.
267 *
268 * @param key the key to search
269 * @since 2.5.0
270 */
271 @Nullable
272 String getAsString(@Nonnull String key);
273
274 /**
275 * Finds a value associated with the given key. The value is
276 * converted to a <tt>String</tt> if found. If not found then the
277 * supplied <tt>defaultValue</tt> will be returned.
278 *
279 * @param key the key to search
280 * @param defaultValue the value to be returned if the key is not found
281 * @since 2.5.0
282 */
283 @Nullable
284 String getAsString(@Nonnull String key, @Nullable String defaultValue);
285
286 /**
287 * /**
288 * Finds a value associated with the given key. The value is
289 * blindly cast to type <tt>T</tt> if found.
290 *
291 * @param key the key to search
292 * @since 2.5.0
293 */
294 @Nullable
295 <T> T getAs(@Nonnull String key);
296
297 /**
298 * Finds a value associated with the given key. The value is
299 * blindly cast to type <tt>T</tt> if found. If not found then the
300 * supplied <tt>defaultValue</tt> will be returned.
301 *
302 * @param key the key to search
303 * @param defaultValue the value to be returned if the key is not found
304 * @since 2.5.0
305 */
306 @Nullable
307 <T> T getAs(@Nonnull String key, @Nullable T defaultValue);
308
309 /**
310 * /**
311 * Finds a value associated with the given key. The value is
312 * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
313 *
314 * @param key the key to search
315 * @param type the type to be returned
316 * @since 2.5.0
317 */
318 @Nullable
319 <T> T getConverted(@Nonnull String key, @Nonnull Class<T> type);
320
321 /**
322 * Finds a value associated with the given key. The value is
323 * converted to type <tt>T</tt> if found using a {@code PropertyEditor}.
324 * If not found then the supplied <tt>defaultValue</tt> will be returned.
325 *
326 * @param key the key to search
327 * @param type the type to be returned
328 * @param defaultValue the value to be returned if the key is not found
329 * @since 2.5.0
330 */
331 @Nullable
332 <T> T getConverted(@Nonnull String key, @Nonnull Class<T> type, @Nullable T defaultValue);
333
334 /**
335 * Inject properties and members annotated with {@code griffon.inject.Contextual}.
336 *
337 * @param instance the instance on which contextual members will be injected.
338 * @param <T> the type of the instance
339 * @return the instance on which contextual members where injected.
340 */
341 @Nonnull
342 <T> T injectMembers(@Nonnull T instance);
343 }
|