Context.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.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 }