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