1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.di;
17
18 import java.util.Set;
19
20 /**
21 * <p>
22 * Definition of an interface that allows access to the beans managed by the
23 * dependency injection framework.
24 * </p>
25 * <p>
26 * This interface serves as the top-level entry point into the dependency
27 * injection framework. It allows querying beans from a specified
28 * <code>{@link BeanStore}</code> or a default <code>BeanStore</code> by
29 * name or by type. Listing the available beans is also possible.
30 * </p>
31 * <p>
32 * When objects are dynamically created, class loader issues have to be taken
33 * into account. A <code>BeanContext</code> allows the registration of class
34 * loaders by name. In the configuration, it can then be specified, which bean
35 * is to be created using which class loader. For the context class loader there
36 * is a special constant.
37 * </p>
38 *
39 * @author Oliver Heger
40 * @version $Id: BeanContext.java 205 2012-01-29 18:29:57Z oheger $
41 */
42 public interface BeanContext
43 {
44 /**
45 * Returns the bean with the specified name from the default
46 * <code>BeanStore</code>.
47 *
48 * @param name the name of the bean to be retrieved
49 * @return the bean with this name
50 * @throws InjectionException if the bean cannot be resolved or its creation
51 * or initialization causes an error
52 */
53 Object getBean(String name);
54
55 /**
56 * Returns the bean with the specified name from the given
57 * <code>BeanStore</code>. This method can be used if a child bean store
58 * of the default bean store is to be accessed.
59 *
60 * @param name the name of the bean to be retrieved
61 * @param store the <code>BeanStore</code> to query
62 * @return the bean with this name
63 * @throws InjectionException if the bean cannot be resolved or its creation
64 * or initialization causes an error
65 * @throws IllegalArgumentException if the passed in bean store is <b>null</b>
66 */
67 Object getBean(String name, BeanStore store);
68
69 /**
70 * Returns the bean with the specified class from the default
71 * <code>BeanStore</code>. An implementation of this method has to
72 * iterate over the beans defined in the bean store to find out, whether the
73 * specified class is assignable from their class. Then the first fitting
74 * bean will be returned. So it is for instance possible to query for an
75 * interface and find a bean that is a concrete implementation of this
76 * interface. If there are multiple bean definitions that are compatible
77 * with this class, it is up to a concrete implementation of this interface
78 * to choose one. Defining beans based on a class (or interface) allows to
79 * abstract from the concrete naming of beans and focuses more on the beans'
80 * semantics.
81 *
82 * @param <T> the type of the bean to be fetched
83 * @param beanCls the class of the bean to be fetched
84 * @return the bean with this class
85 * @throws InjectionException if the bean cannot be resolved or its creation
86 * or initialization causes an error
87 */
88 <T> T getBean(Class<T> beanCls);
89
90 /**
91 * Returns the bean with the specified class from the given
92 * <code>BeanStore</code>. Works like the overloaded method, but operates
93 * on the given bean store.
94 *
95 * @param <T> the type of the bean to be fetched
96 * @param beanCls the class of the bean to be fetched
97 * @param store the <code>BeanStore</code> to use
98 * @return the bean with this class
99 * @throws InjectionException if the bean cannot be resolved or its creation
100 * or initialization causes an error
101 * @throws IllegalArgumentException if the passed in bean store is <b>null</b>
102 */
103 <T> T getBean(Class<T> beanCls, BeanStore store);
104
105 /**
106 * Returns a set with the names of all beans defined in the default
107 * <code>BeanStore</code>.
108 *
109 * @return a set with the names of the defined beans
110 */
111 Set<String> beanNames();
112
113 /**
114 * Returns a set with the names of all beans defined in the given
115 * <code>BeanStore</code>. This list will also contain beans that are
116 * defined in one of the bean store's parents.
117 *
118 * @param store the bean store (must not be <b>null</b>)
119 * @return a set with the names of the defined beans
120 * @throws IllegalArgumentException if the passed in bean store is <b>null</b>
121 */
122 Set<String> beanNames(BeanStore store);
123
124 /**
125 * Returns a set with the classes of all beans defined in the default
126 * <code>BeanStore</code> (or one of its parents).
127 *
128 * @return a set with the classes of the defined beans
129 */
130 Set<Class<?>> beanClasses();
131
132 /**
133 * Returns a set with the classes of all beans defined in the given
134 * <code>BeanStore</code>. This list will also contain beans that are
135 * defined in one of the bean store's parents.
136 *
137 * @param store the bean store (must not be <b>null</b>)
138 * @return a set with the classes of the defined beans
139 * @throws IllegalArgumentException if the passed in bean store is <b>null</b>
140 */
141 Set<Class<?>> beanClasses(BeanStore store);
142
143 /**
144 * Checks whether the default <code>BeanStore</code> contains a bean with
145 * the given name. If necessary the bean store's parents will also be
146 * searched.
147 *
148 * @param name the name of the searched bean
149 * @return a flag whether this bean can be found
150 */
151 boolean containsBean(String name);
152
153 /**
154 * Checks whether the specified <code>BeanStore</code> contains a bean
155 * with the given name. If necessary the bean store's parents will also be
156 * searched.
157 *
158 * @param name the name of the searched bean
159 * @param store the bean store
160 * @return a flag whether this bean can be found
161 */
162 boolean containsBean(String name, BeanStore store);
163
164 /**
165 * Checks whether the default <code>BeanStore</code> contains a bean with
166 * the given class. If necessary the bean store's parents will also be
167 * searched.
168 *
169 * @param beanClass the class of the searched bean
170 * @return a flag whether this bean can be found
171 */
172 boolean containsBean(Class<?> beanClass);
173
174 /**
175 * Checks whether the specified <code>BeanStore</code> contains a bean
176 * with the given class. If necessary the bean store's parents will also be
177 * searched.
178 *
179 * @param beanClass the class of the searched bean
180 * @param store the bean store
181 * @return a flag whether this bean can be found
182 */
183 boolean containsBean(Class<?> beanClass, BeanStore store);
184
185 /**
186 * Returns the default bean store.
187 *
188 * @return the default bean store
189 */
190 BeanStore getDefaultBeanStore();
191
192 /**
193 * Sets the default bean store. This bean store is used as starting point
194 * for all lookup-operations if no specific bean store is specified.
195 *
196 * @param store the new default bean store
197 */
198 void setDefaultBeanStore(BeanStore store);
199
200 /**
201 * Returns the name of the bean that is managed by the specified {@code
202 * BeanProvider}, starting search with the default {@code BeanStore}.
203 *
204 * @param beanProvider the {@code BeanProvider}
205 * @return the name, under which this {@code BeanProvider} is registered in
206 * one of the accessible bean stores or <b>null</b> if it cannot be
207 * resolved
208 * @see #beanNameFor(BeanProvider, BeanStore)
209 */
210 String beanNameFor(BeanProvider beanProvider);
211
212 /**
213 * Returns the name of the bean that is managed by the specified {@code
214 * BeanProvider}, starting search in the specified {@code BeanStore}. This
215 * method can be used for performing a "reverse lookup": when a bean
216 * provider is known, but the corresponding bean name is searched. A use
217 * case would be the processing of a {@link BeanCreationEvent}. The event
218 * object contains the {@code BeanProvider} that created the bean, but the
219 * name of this bean is not part of the event.
220 *
221 * @param beanProvider the {@code BeanProvider}
222 * @param store the {@code BeanStore}
223 * @return the name, under which this {@code BeanProvider} is registered in
224 * one of the accessible bean stores or <b>null</b> if it cannot be
225 * resolved
226 */
227 String beanNameFor(BeanProvider beanProvider, BeanStore store);
228
229 /**
230 * Adds a new {@code BeanCreationListener} to this context. This listener
231 * will receive notifications about newly created beans.
232 *
233 * @param l the listener to be added (must not be <b>null</b>)
234 * @throws IllegalArgumentException if the listener is <b>null</b>
235 */
236 void addBeanCreationListener(BeanCreationListener l);
237
238 /**
239 * Removes the specified {@code BeanCreationListener} from this context. If
240 * the listener is not registered, this method has no effect.
241 *
242 * @param l the listener to remove
243 */
244 void removeBeanCreationListener(BeanCreationListener l);
245
246 /**
247 * Closes this bean context. This method should be called when the context
248 * is no more needed. An implementation can free resources or perform other
249 * clean up. Note that the {@link BeanStore} associated with this context is
250 * not closed by this method (this is because a {@code BeanStore} could be
251 * shared by multiple contexts, and there is not necessary a 1:1
252 * relationship between a {@code BeanStore} and a {@code BeanContext}).
253 */
254 void close();
255
256 /**
257 * Returns the {@code ClassLoaderProvider} used by this context.
258 *
259 * @return the {@code ClassLoaderProvider}
260 */
261 ClassLoaderProvider getClassLoaderProvider();
262
263 /**
264 * Sets the {@code ClassLoaderProvider} to be used by this context. This
265 * object is needed when classes have to be loaded through reflection.
266 *
267 * @param clp the {@code ClassLoaderProvider}
268 */
269 void setClassLoaderProvider(ClassLoaderProvider clp);
270 }