1 /*
2 * Copyright 2002-2015 the original author or authors.
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
17 package org.springframework.beans.factory;
18
19 import org.springframework.beans.BeansException;
20
21 /**
22 * The root interface for accessing a Spring bean container.
23 * This is the basic client view of a bean container;
24 * further interfaces such as {@link ListableBeanFactory} and
25 * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
26 * are available for specific purposes.
27 *
28 * <p>This interface is implemented by objects that hold a number of bean definitions,
29 * each uniquely identified by a String name. Depending on the bean definition,
30 * the factory will return either an independent instance of a contained object
31 * (the Prototype design pattern), or a single shared instance (a superior
32 * alternative to the Singleton design pattern, in which the instance is a
33 * singleton in the scope of the factory). Which type of instance will be returned
34 * depends on the bean factory configuration: the API is the same. Since Spring
35 * 2.0, further scopes are available depending on the concrete application
36 * context (e.g. "request" and "session" scopes in a web environment).
37 *
38 * <p>The point of this approach is that the BeanFactory is a central registry
39 * of application components, and centralizes configuration of application
40 * components (no more do individual objects need to read properties files,
41 * for example). See chapters 4 and 11 of "Expert One-on-One J2EE Design and
42 * Development" for a discussion of the benefits of this approach.
43 *
44 * <p>Note that it is generally better to rely on Dependency Injection
45 * ("push" configuration) to configure application objects through setters
46 * or constructors, rather than use any form of "pull" configuration like a
47 * BeanFactory lookup. Spring's Dependency Injection functionality is
48 * implemented using this BeanFactory interface and its subinterfaces.
49 *
50 * <p>Normally a BeanFactory will load bean definitions stored in a configuration
51 * source (such as an XML document), and use the {@code org.springframework.beans}
52 * package to configure the beans. However, an implementation could simply return
53 * Java objects it creates as necessary directly in Java code. There are no
54 * constraints on how the definitions could be stored: LDAP, RDBMS, XML,
55 * properties file, etc. Implementations are encouraged to support references
56 * amongst beans (Dependency Injection).
57 *
58 * <p>In contrast to the methods in {@link ListableBeanFactory}, all of the
59 * operations in this interface will also check parent factories if this is a
60 * {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance,
61 * the immediate parent factory will be asked. Beans in this factory instance
62 * are supposed to override beans of the same name in any parent factory.
63 *
64 * <p>Bean factory implementations should support the standard bean lifecycle interfaces
65 * as far as possible. The full set of initialization methods and their standard order is:<br>
66 * 1. BeanNameAware's {@code setBeanName}<br>
67 * 2. BeanClassLoaderAware's {@code setBeanClassLoader}<br>
68 * 3. BeanFactoryAware's {@code setBeanFactory}<br>
69 * 4. ResourceLoaderAware's {@code setResourceLoader}
70 * (only applicable when running in an application context)<br>
71 * 5. ApplicationEventPublisherAware's {@code setApplicationEventPublisher}
72 * (only applicable when running in an application context)<br>
73 * 6. MessageSourceAware's {@code setMessageSource}
74 * (only applicable when running in an application context)<br>
75 * 7. ApplicationContextAware's {@code setApplicationContext}
76 * (only applicable when running in an application context)<br>
77 * 8. ServletContextAware's {@code setServletContext}
78 * (only applicable when running in a web application context)<br>
79 * 9. {@code postProcessBeforeInitialization} methods of BeanPostProcessors<br>
80 * 10. InitializingBean's {@code afterPropertiesSet}<br>
81 * 11. a custom init-method definition<br>
82 * 12. {@code postProcessAfterInitialization} methods of BeanPostProcessors
83 *
84 * <p>On shutdown of a bean factory, the following lifecycle methods apply:<br>
85 * 1. DisposableBean's {@code destroy}<br>
86 * 2. a custom destroy-method definition
87 *
88 * @author Rod Johnson
89 * @author Juergen Hoeller
90 * @author Chris Beams
91 * @since 13 April 2001
92 * @see BeanNameAware#setBeanName
93 * @see BeanClassLoaderAware#setBeanClassLoader
94 * @see BeanFactoryAware#setBeanFactory
95 * @see org.springframework.context.ResourceLoaderAware#setResourceLoader
96 * @see org.springframework.context.ApplicationEventPublisherAware#setApplicationEventPublisher
97 * @see org.springframework.context.MessageSourceAware#setMessageSource
98 * @see org.springframework.context.ApplicationContextAware#setApplicationContext
99 * @see org.springframework.web.context.ServletContextAware#setServletContext
100 * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessBeforeInitialization
101 * @see InitializingBean#afterPropertiesSet
102 * @see org.springframework.beans.factory.support.RootBeanDefinition#getInitMethodName
103 * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessAfterInitialization
104 * @see DisposableBean#destroy
105 * @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName
106 */
107 public interface BeanFactory {
108
109 /**
110 * Used to dereference a {@link FactoryBean} instance and distinguish it from
111 * beans <i>created</i> by the FactoryBean. For example, if the bean named
112 * {@code myJndiObject} is a FactoryBean, getting {@code &myJndiObject}
113 * will return the factory, not the instance returned by the factory.
114 */
115 String FACTORY_BEAN_PREFIX = "&";
116
117
118 /**
119 * Return an instance, which may be shared or independent, of the specified bean.
120 * <p>This method allows a Spring BeanFactory to be used as a replacement for the
121 * Singleton or Prototype design pattern. Callers may retain references to
122 * returned objects in the case of Singleton beans.
123 * <p>Translates aliases back to the corresponding canonical bean name.
124 * Will ask the parent factory if the bean cannot be found in this factory instance.
125 * @param name the name of the bean to retrieve
126 * @return an instance of the bean
127 * @throws NoSuchBeanDefinitionException if there is no bean definition
128 * with the specified name
129 * @throws BeansException if the bean could not be obtained
130 */
131 Object getBean(String name) throws BeansException;
132
133 /**
134 * Return an instance, which may be shared or independent, of the specified bean.
135 * <p>Behaves the same as {@link #getBean(String)}, but provides a measure of type
136 * safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the
137 * required type. This means that ClassCastException can't be thrown on casting
138 * the result correctly, as can happen with {@link #getBean(String)}.
139 * <p>Translates aliases back to the corresponding canonical bean name.
140 * Will ask the parent factory if the bean cannot be found in this factory instance.
141 * @param name the name of the bean to retrieve
142 * @param requiredType type the bean must match. Can be an interface or superclass
143 * of the actual class, or {@code null} for any match. For example, if the value
144 * is {@code Object.class}, this method will succeed whatever the class of the
145 * returned instance.
146 * @return an instance of the bean
147 * @throws NoSuchBeanDefinitionException if there is no such bean definition
148 * @throws BeanNotOfRequiredTypeException if the bean is not of the required type
149 * @throws BeansException if the bean could not be created
150 */
151 <T> T getBean(String name, Class<T> requiredType) throws BeansException;
152
153 /**
154 * Return the bean instance that uniquely matches the given object type, if any.
155 * @param requiredType type the bean must match; can be an interface or superclass.
156 * {@code null} is disallowed.
157 * <p>This method goes into {@link ListableBeanFactory} by-type lookup territory
158 * but may also be translated into a conventional by-name lookup based on the name
159 * of the given type. For more extensive retrieval operations across sets of beans,
160 * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}.
161 * @return an instance of the single bean matching the required type
162 * @throws NoSuchBeanDefinitionException if no bean of the given type was found
163 * @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found
164 * @since 3.0
165 * @see ListableBeanFactory
166 */
167 <T> T getBean(Class<T> requiredType) throws BeansException;
168
169 /**
170 * Return an instance, which may be shared or independent, of the specified bean.
171 * <p>Allows for specifying explicit constructor arguments / factory method arguments,
172 * overriding the specified default arguments (if any) in the bean definition.
173 * @param name the name of the bean to retrieve
174 * @param args arguments to use when creating a bean instance using explicit arguments
175 * (only applied when creating a new instance as opposed to retrieving an existing one)
176 * @return an instance of the bean
177 * @throws NoSuchBeanDefinitionException if there is no such bean definition
178 * @throws BeanDefinitionStoreException if arguments have been given but
179 * the affected bean isn't a prototype
180 * @throws BeansException if the bean could not be created
181 * @since 2.5
182 */
183 Object getBean(String name, Object... args) throws BeansException;
184
185 /**
186 * Return an instance, which may be shared or independent, of the specified bean.
187 * <p>Allows for specifying explicit constructor arguments / factory method arguments,
188 * overriding the specified default arguments (if any) in the bean definition.
189 * @param requiredType type the bean must match; can be an interface or superclass.
190 * {@code null} is disallowed.
191 * <p>This method goes into {@link ListableBeanFactory} by-type lookup territory
192 * but may also be translated into a conventional by-name lookup based on the name
193 * of the given type. For more extensive retrieval operations across sets of beans,
194 * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}.
195 * @param args arguments to use when creating a bean instance using explicit arguments
196 * (only applied when creating a new instance as opposed to retrieving an existing one)
197 * @return an instance of the bean
198 * @throws NoSuchBeanDefinitionException if there is no such bean definition
199 * @throws BeanDefinitionStoreException if arguments have been given but
200 * the affected bean isn't a prototype
201 * @throws BeansException if the bean could not be created
202 * @since 4.1
203 */
204 <T> T getBean(Class<T> requiredType, Object... args) throws BeansException;
205
206
207 /**
208 * Does this bean factory contain a bean definition or externally registered singleton
209 * instance with the given name?
210 * <p>If the given name is an alias, it will be translated back to the corresponding
211 * canonical bean name.
212 * <p>If this factory is hierarchical, will ask any parent factory if the bean cannot
213 * be found in this factory instance.
214 * <p>If a bean definition or singleton instance matching the given name is found,
215 * this method will return {@code true} whether the named bean definition is concrete
216 * or abstract, lazy or eager, in scope or not. Therefore, note that a {@code true}
217 * return value from this method does not necessarily indicate that {@link #getBean}
218 * will be able to obtain an instance for the same name.
219 * @param name the name of the bean to query
220 * @return whether a bean with the given name is present
221 */
222 boolean containsBean(String name);
223
224 /**
225 * Is this bean a shared singleton? That is, will {@link #getBean} always
226 * return the same instance?
227 * <p>Note: This method returning {@code false} does not clearly indicate
228 * independent instances. It indicates non-singleton instances, which may correspond
229 * to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly
230 * check for independent instances.
231 * <p>Translates aliases back to the corresponding canonical bean name.
232 * Will ask the parent factory if the bean cannot be found in this factory instance.
233 * @param name the name of the bean to query
234 * @return whether this bean corresponds to a singleton instance
235 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
236 * @see #getBean
237 * @see #isPrototype
238 */
239 boolean isSingleton(String name) throws NoSuchBeanDefinitionException;
240
241 /**
242 * Is this bean a prototype? That is, will {@link #getBean} always return
243 * independent instances?
244 * <p>Note: This method returning {@code false} does not clearly indicate
245 * a singleton object. It indicates non-independent instances, which may correspond
246 * to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly
247 * check for a shared singleton instance.
248 * <p>Translates aliases back to the corresponding canonical bean name.
249 * Will ask the parent factory if the bean cannot be found in this factory instance.
250 * @param name the name of the bean to query
251 * @return whether this bean will always deliver independent instances
252 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
253 * @since 2.0.3
254 * @see #getBean
255 * @see #isSingleton
256 */
257 boolean isPrototype(String name) throws NoSuchBeanDefinitionException;
258
259 /**
260 * Check whether the bean with the given name matches the specified type.
261 * More specifically, check whether a {@link #getBean} call for the given name
262 * would return an object that is assignable to the specified target type.
263 * <p>Translates aliases back to the corresponding canonical bean name.
264 * Will ask the parent factory if the bean cannot be found in this factory instance.
265 * @param name the name of the bean to query
266 * @param targetType the type to match against
267 * @return {@code true} if the bean type matches,
268 * {@code false} if it doesn't match or cannot be determined yet
269 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
270 * @since 2.0.1
271 * @see #getBean
272 * @see #getType
273 */
274 boolean isTypeMatch(String name, Class<?> targetType) throws NoSuchBeanDefinitionException;
275
276 /**
277 * Determine the type of the bean with the given name. More specifically,
278 * determine the type of object that {@link #getBean} would return for the given name.
279 * <p>For a {@link FactoryBean}, return the type of object that the FactoryBean creates,
280 * as exposed by {@link FactoryBean#getObjectType()}.
281 * <p>Translates aliases back to the corresponding canonical bean name.
282 * Will ask the parent factory if the bean cannot be found in this factory instance.
283 * @param name the name of the bean to query
284 * @return the type of the bean, or {@code null} if not determinable
285 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
286 * @since 1.1.2
287 * @see #getBean
288 * @see #isTypeMatch
289 */
290 Class<?> getType(String name) throws NoSuchBeanDefinitionException;
291
292 /**
293 * Return the aliases for the given bean name, if any.
294 * All of those aliases point to the same bean when used in a {@link #getBean} call.
295 * <p>If the given name is an alias, the corresponding original bean name
296 * and other aliases (if any) will be returned, with the original bean name
297 * being the first element in the array.
298 * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
299 * @param name the bean name to check for aliases
300 * @return the aliases, or an empty array if none
301 * @see #getBean
302 */
303 String[] getAliases(String name);
304
305 }