1 /*
2 * Copyright 2002-2013 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.config;
18
19 import java.util.Set;
20
21 import org.springframework.beans.BeansException;
22 import org.springframework.beans.TypeConverter;
23 import org.springframework.beans.factory.BeanFactory;
24
25 /**
26 * Extension of the {@link org.springframework.beans.factory.BeanFactory}
27 * interface to be implemented by bean factories that are capable of
28 * autowiring, provided that they want to expose this functionality for
29 * existing bean instances.
30 *
31 * <p>This subinterface of BeanFactory is not meant to be used in normal
32 * application code: stick to {@link org.springframework.beans.factory.BeanFactory}
33 * or {@link org.springframework.beans.factory.ListableBeanFactory} for
34 * typical use cases.
35 *
36 * <p>Integration code for other frameworks can leverage this interface to
37 * wire and populate existing bean instances that Spring does not control
38 * the lifecycle of. This is particularly useful for WebWork Actions and
39 * Tapestry Page objects, for example.
40 *
41 * <p>Note that this interface is not implemented by
42 * {@link org.springframework.context.ApplicationContext} facades,
43 * as it is hardly ever used by application code. That said, it is available
44 * from an application context too, accessible through ApplicationContext's
45 * {@link org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()}
46 * method.
47 *
48 * <p>You may also implement the {@link org.springframework.beans.factory.BeanFactoryAware}
49 * interface, which exposes the internal BeanFactory even when running in an
50 * ApplicationContext, to get access to an AutowireCapableBeanFactory:
51 * simply cast the passed-in BeanFactory to AutowireCapableBeanFactory.
52 *
53 * @author Juergen Hoeller
54 * @since 04.12.2003
55 * @see org.springframework.beans.factory.BeanFactoryAware
56 * @see org.springframework.beans.factory.config.ConfigurableListableBeanFactory
57 * @see org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()
58 */
59 public interface AutowireCapableBeanFactory extends BeanFactory {
60
61 /**
62 * Constant that indicates no externally defined autowiring. Note that
63 * BeanFactoryAware etc and annotation-driven injection will still be applied.
64 * @see #createBean
65 * @see #autowire
66 * @see #autowireBeanProperties
67 */
68 int AUTOWIRE_NO = 0;
69
70 /**
71 * Constant that indicates autowiring bean properties by name
72 * (applying to all bean property setters).
73 * @see #createBean
74 * @see #autowire
75 * @see #autowireBeanProperties
76 */
77 int AUTOWIRE_BY_NAME = 1;
78
79 /**
80 * Constant that indicates autowiring bean properties by type
81 * (applying to all bean property setters).
82 * @see #createBean
83 * @see #autowire
84 * @see #autowireBeanProperties
85 */
86 int AUTOWIRE_BY_TYPE = 2;
87
88 /**
89 * Constant that indicates autowiring the greediest constructor that
90 * can be satisfied (involves resolving the appropriate constructor).
91 * @see #createBean
92 * @see #autowire
93 */
94 int AUTOWIRE_CONSTRUCTOR = 3;
95
96 /**
97 * Constant that indicates determining an appropriate autowire strategy
98 * through introspection of the bean class.
99 * @see #createBean
100 * @see #autowire
101 * @deprecated as of Spring 3.0: If you are using mixed autowiring strategies,
102 * prefer annotation-based autowiring for clearer demarcation of autowiring needs.
103 */
104 @Deprecated
105 int AUTOWIRE_AUTODETECT = 4;
106
107
108 //-------------------------------------------------------------------------
109 // Typical methods for creating and populating external bean instances
110 //-------------------------------------------------------------------------
111
112 /**
113 * Fully create a new bean instance of the given class.
114 * <p>Performs full initialization of the bean, including all applicable
115 * {@link BeanPostProcessor BeanPostProcessors}.
116 * <p>Note: This is intended for creating a fresh instance, populating annotated
117 * fields and methods as well as applying all standard bean initialiation callbacks.
118 * It does <i>not</> imply traditional by-name or by-type autowiring of properties;
119 * use {@link #createBean(Class, int, boolean)} for that purposes.
120 * @param beanClass the class of the bean to create
121 * @return the new bean instance
122 * @throws BeansException if instantiation or wiring failed
123 */
124 <T> T createBean(Class<T> beanClass) throws BeansException;
125
126 /**
127 * Populate the given bean instance through applying after-instantiation callbacks
128 * and bean property post-processing (e.g. for annotation-driven injection).
129 * <p>Note: This is essentially intended for (re-)populating annotated fields and
130 * methods, either for new instances or for deserialized instances. It does
131 * <i>not</i> imply traditional by-name or by-type autowiring of properties;
132 * use {@link #autowireBeanProperties} for that purposes.
133 * @param existingBean the existing bean instance
134 * @throws BeansException if wiring failed
135 */
136 void autowireBean(Object existingBean) throws BeansException;
137
138 /**
139 * Configure the given raw bean: autowiring bean properties, applying
140 * bean property values, applying factory callbacks such as {@code setBeanName}
141 * and {@code setBeanFactory}, and also applying all bean post processors
142 * (including ones which might wrap the given raw bean).
143 * <p>This is effectively a superset of what {@link #initializeBean} provides,
144 * fully applying the configuration specified by the corresponding bean definition.
145 * <b>Note: This method requires a bean definition for the given name!</b>
146 * @param existingBean the existing bean instance
147 * @param beanName the name of the bean, to be passed to it if necessary
148 * (a bean definition of that name has to be available)
149 * @return the bean instance to use, either the original or a wrapped one
150 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
151 * if there is no bean definition with the given name
152 * @throws BeansException if the initialization failed
153 * @see #initializeBean
154 */
155 Object configureBean(Object existingBean, String beanName) throws BeansException;
156
157 /**
158 * Resolve the specified dependency against the beans defined in this factory.
159 * @param descriptor the descriptor for the dependency
160 * @param beanName the name of the bean which declares the present dependency
161 * @return the resolved object, or {@code null} if none found
162 * @throws BeansException in dependency resolution failed
163 */
164 Object resolveDependency(DependencyDescriptor descriptor, String beanName) throws BeansException;
165
166
167 //-------------------------------------------------------------------------
168 // Specialized methods for fine-grained control over the bean lifecycle
169 //-------------------------------------------------------------------------
170
171 /**
172 * Fully create a new bean instance of the given class with the specified
173 * autowire strategy. All constants defined in this interface are supported here.
174 * <p>Performs full initialization of the bean, including all applicable
175 * {@link BeanPostProcessor BeanPostProcessors}. This is effectively a superset
176 * of what {@link #autowire} provides, adding {@link #initializeBean} behavior.
177 * @param beanClass the class of the bean to create
178 * @param autowireMode by name or type, using the constants in this interface
179 * @param dependencyCheck whether to perform a dependency check for objects
180 * (not applicable to autowiring a constructor, thus ignored there)
181 * @return the new bean instance
182 * @throws BeansException if instantiation or wiring failed
183 * @see #AUTOWIRE_NO
184 * @see #AUTOWIRE_BY_NAME
185 * @see #AUTOWIRE_BY_TYPE
186 * @see #AUTOWIRE_CONSTRUCTOR
187 */
188 Object createBean(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException;
189
190 /**
191 * Instantiate a new bean instance of the given class with the specified autowire
192 * strategy. All constants defined in this interface are supported here.
193 * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply
194 * before-instantiation callbacks (e.g. for annotation-driven injection).
195 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}
196 * callbacks or perform any further initialization of the bean. This interface
197 * offers distinct, fine-grained operations for those purposes, for example
198 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}
199 * callbacks are applied, if applicable to the construction of the instance.
200 * @param beanClass the class of the bean to instantiate
201 * @param autowireMode by name or type, using the constants in this interface
202 * @param dependencyCheck whether to perform a dependency check for object
203 * references in the bean instance (not applicable to autowiring a constructor,
204 * thus ignored there)
205 * @return the new bean instance
206 * @throws BeansException if instantiation or wiring failed
207 * @see #AUTOWIRE_NO
208 * @see #AUTOWIRE_BY_NAME
209 * @see #AUTOWIRE_BY_TYPE
210 * @see #AUTOWIRE_CONSTRUCTOR
211 * @see #AUTOWIRE_AUTODETECT
212 * @see #initializeBean
213 * @see #applyBeanPostProcessorsBeforeInitialization
214 * @see #applyBeanPostProcessorsAfterInitialization
215 */
216 Object autowire(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException;
217
218 /**
219 * Autowire the bean properties of the given bean instance by name or type.
220 * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply
221 * after-instantiation callbacks (e.g. for annotation-driven injection).
222 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}
223 * callbacks or perform any further initialization of the bean. This interface
224 * offers distinct, fine-grained operations for those purposes, for example
225 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}
226 * callbacks are applied, if applicable to the configuration of the instance.
227 * @param existingBean the existing bean instance
228 * @param autowireMode by name or type, using the constants in this interface
229 * @param dependencyCheck whether to perform a dependency check for object
230 * references in the bean instance
231 * @throws BeansException if wiring failed
232 * @see #AUTOWIRE_BY_NAME
233 * @see #AUTOWIRE_BY_TYPE
234 * @see #AUTOWIRE_NO
235 */
236 void autowireBeanProperties(Object existingBean, int autowireMode, boolean dependencyCheck)
237 throws BeansException;
238
239 /**
240 * Apply the property values of the bean definition with the given name to
241 * the given bean instance. The bean definition can either define a fully
242 * self-contained bean, reusing its property values, or just property values
243 * meant to be used for existing bean instances.
244 * <p>This method does <i>not</i> autowire bean properties; it just applies
245 * explicitly defined property values. Use the {@link #autowireBeanProperties}
246 * method to autowire an existing bean instance.
247 * <b>Note: This method requires a bean definition for the given name!</b>
248 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}
249 * callbacks or perform any further initialization of the bean. This interface
250 * offers distinct, fine-grained operations for those purposes, for example
251 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}
252 * callbacks are applied, if applicable to the configuration of the instance.
253 * @param existingBean the existing bean instance
254 * @param beanName the name of the bean definition in the bean factory
255 * (a bean definition of that name has to be available)
256 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
257 * if there is no bean definition with the given name
258 * @throws BeansException if applying the property values failed
259 * @see #autowireBeanProperties
260 */
261 void applyBeanPropertyValues(Object existingBean, String beanName) throws BeansException;
262
263 /**
264 * Initialize the given raw bean, applying factory callbacks
265 * such as {@code setBeanName} and {@code setBeanFactory},
266 * also applying all bean post processors (including ones which
267 * might wrap the given raw bean).
268 * <p>Note that no bean definition of the given name has to exist
269 * in the bean factory. The passed-in bean name will simply be used
270 * for callbacks but not checked against the registered bean definitions.
271 * @param existingBean the existing bean instance
272 * @param beanName the name of the bean, to be passed to it if necessary
273 * (only passed to {@link BeanPostProcessor BeanPostProcessors})
274 * @return the bean instance to use, either the original or a wrapped one
275 * @throws BeansException if the initialization failed
276 */
277 Object initializeBean(Object existingBean, String beanName) throws BeansException;
278
279 /**
280 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean
281 * instance, invoking their {@code postProcessBeforeInitialization} methods.
282 * The returned bean instance may be a wrapper around the original.
283 * @param existingBean the new bean instance
284 * @param beanName the name of the bean
285 * @return the bean instance to use, either the original or a wrapped one
286 * @throws BeansException if any post-processing failed
287 * @see BeanPostProcessor#postProcessBeforeInitialization
288 */
289 Object applyBeanPostProcessorsBeforeInitialization(Object existingBean, String beanName)
290 throws BeansException;
291
292 /**
293 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean
294 * instance, invoking their {@code postProcessAfterInitialization} methods.
295 * The returned bean instance may be a wrapper around the original.
296 * @param existingBean the new bean instance
297 * @param beanName the name of the bean
298 * @return the bean instance to use, either the original or a wrapped one
299 * @throws BeansException if any post-processing failed
300 * @see BeanPostProcessor#postProcessAfterInitialization
301 */
302 Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName)
303 throws BeansException;
304
305 /**
306 * Destroy the given bean instance (typically coming from {@link #createBean}),
307 * applying the {@link org.springframework.beans.factory.DisposableBean} contract as well as
308 * registered {@link DestructionAwareBeanPostProcessor DestructionAwareBeanPostProcessors}.
309 * <p>Any exception that arises during destruction should be caught
310 * and logged instead of propagated to the caller of this method.
311 * @param existingBean the bean instance to destroy
312 */
313 void destroyBean(Object existingBean);
314
315 /**
316 * Resolve the specified dependency against the beans defined in this factory.
317 * @param descriptor the descriptor for the dependency
318 * @param beanName the name of the bean which declares the present dependency
319 * @param autowiredBeanNames a Set that all names of autowired beans (used for
320 * resolving the present dependency) are supposed to be added to
321 * @param typeConverter the TypeConverter to use for populating arrays and
322 * collections
323 * @return the resolved object, or {@code null} if none found
324 * @throws BeansException in dependency resolution failed
325 */
326 Object resolveDependency(DependencyDescriptor descriptor, String beanName,
327 Set<String> autowiredBeanNames, TypeConverter typeConverter) throws BeansException;
328
329 }