001/* 002 * Copyright 2002-2019 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.beans.factory.config; 018 019import java.util.Set; 020 021import org.springframework.beans.BeansException; 022import org.springframework.beans.TypeConverter; 023import org.springframework.beans.factory.BeanFactory; 024import org.springframework.beans.factory.NoSuchBeanDefinitionException; 025import org.springframework.beans.factory.NoUniqueBeanDefinitionException; 026import org.springframework.lang.Nullable; 027 028/** 029 * Extension of the {@link org.springframework.beans.factory.BeanFactory} 030 * interface to be implemented by bean factories that are capable of 031 * autowiring, provided that they want to expose this functionality for 032 * existing bean instances. 033 * 034 * <p>This subinterface of BeanFactory is not meant to be used in normal 035 * application code: stick to {@link org.springframework.beans.factory.BeanFactory} 036 * or {@link org.springframework.beans.factory.ListableBeanFactory} for 037 * typical use cases. 038 * 039 * <p>Integration code for other frameworks can leverage this interface to 040 * wire and populate existing bean instances that Spring does not control 041 * the lifecycle of. This is particularly useful for WebWork Actions and 042 * Tapestry Page objects, for example. 043 * 044 * <p>Note that this interface is not implemented by 045 * {@link org.springframework.context.ApplicationContext} facades, 046 * as it is hardly ever used by application code. That said, it is available 047 * from an application context too, accessible through ApplicationContext's 048 * {@link org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()} 049 * method. 050 * 051 * <p>You may also implement the {@link org.springframework.beans.factory.BeanFactoryAware} 052 * interface, which exposes the internal BeanFactory even when running in an 053 * ApplicationContext, to get access to an AutowireCapableBeanFactory: 054 * simply cast the passed-in BeanFactory to AutowireCapableBeanFactory. 055 * 056 * @author Juergen Hoeller 057 * @since 04.12.2003 058 * @see org.springframework.beans.factory.BeanFactoryAware 059 * @see org.springframework.beans.factory.config.ConfigurableListableBeanFactory 060 * @see org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory() 061 */ 062public interface AutowireCapableBeanFactory extends BeanFactory { 063 064 /** 065 * Constant that indicates no externally defined autowiring. Note that 066 * BeanFactoryAware etc and annotation-driven injection will still be applied. 067 * @see #createBean 068 * @see #autowire 069 * @see #autowireBeanProperties 070 */ 071 int AUTOWIRE_NO = 0; 072 073 /** 074 * Constant that indicates autowiring bean properties by name 075 * (applying to all bean property setters). 076 * @see #createBean 077 * @see #autowire 078 * @see #autowireBeanProperties 079 */ 080 int AUTOWIRE_BY_NAME = 1; 081 082 /** 083 * Constant that indicates autowiring bean properties by type 084 * (applying to all bean property setters). 085 * @see #createBean 086 * @see #autowire 087 * @see #autowireBeanProperties 088 */ 089 int AUTOWIRE_BY_TYPE = 2; 090 091 /** 092 * Constant that indicates autowiring the greediest constructor that 093 * can be satisfied (involves resolving the appropriate constructor). 094 * @see #createBean 095 * @see #autowire 096 */ 097 int AUTOWIRE_CONSTRUCTOR = 3; 098 099 /** 100 * Constant that indicates determining an appropriate autowire strategy 101 * through introspection of the bean class. 102 * @see #createBean 103 * @see #autowire 104 * @deprecated as of Spring 3.0: If you are using mixed autowiring strategies, 105 * prefer annotation-based autowiring for clearer demarcation of autowiring needs. 106 */ 107 @Deprecated 108 int AUTOWIRE_AUTODETECT = 4; 109 110 /** 111 * Suffix for the "original instance" convention when initializing an existing 112 * bean instance: to be appended to the fully-qualified bean class name, 113 * e.g. "com.mypackage.MyClass.ORIGINAL", in order to enforce the given instance 114 * to be returned, i.e. no proxies etc. 115 * @since 5.1 116 * @see #initializeBean(Object, String) 117 * @see #applyBeanPostProcessorsBeforeInitialization(Object, String) 118 * @see #applyBeanPostProcessorsAfterInitialization(Object, String) 119 */ 120 String ORIGINAL_INSTANCE_SUFFIX = ".ORIGINAL"; 121 122 123 //------------------------------------------------------------------------- 124 // Typical methods for creating and populating external bean instances 125 //------------------------------------------------------------------------- 126 127 /** 128 * Fully create a new bean instance of the given class. 129 * <p>Performs full initialization of the bean, including all applicable 130 * {@link BeanPostProcessor BeanPostProcessors}. 131 * <p>Note: This is intended for creating a fresh instance, populating annotated 132 * fields and methods as well as applying all standard bean initialization callbacks. 133 * It does <i>not</i> imply traditional by-name or by-type autowiring of properties; 134 * use {@link #createBean(Class, int, boolean)} for those purposes. 135 * @param beanClass the class of the bean to create 136 * @return the new bean instance 137 * @throws BeansException if instantiation or wiring failed 138 */ 139 <T> T createBean(Class<T> beanClass) throws BeansException; 140 141 /** 142 * Populate the given bean instance through applying after-instantiation callbacks 143 * and bean property post-processing (e.g. for annotation-driven injection). 144 * <p>Note: This is essentially intended for (re-)populating annotated fields and 145 * methods, either for new instances or for deserialized instances. It does 146 * <i>not</i> imply traditional by-name or by-type autowiring of properties; 147 * use {@link #autowireBeanProperties} for those purposes. 148 * @param existingBean the existing bean instance 149 * @throws BeansException if wiring failed 150 */ 151 void autowireBean(Object existingBean) throws BeansException; 152 153 /** 154 * Configure the given raw bean: autowiring bean properties, applying 155 * bean property values, applying factory callbacks such as {@code setBeanName} 156 * and {@code setBeanFactory}, and also applying all bean post processors 157 * (including ones which might wrap the given raw bean). 158 * <p>This is effectively a superset of what {@link #initializeBean} provides, 159 * fully applying the configuration specified by the corresponding bean definition. 160 * <b>Note: This method requires a bean definition for the given name!</b> 161 * @param existingBean the existing bean instance 162 * @param beanName the name of the bean, to be passed to it if necessary 163 * (a bean definition of that name has to be available) 164 * @return the bean instance to use, either the original or a wrapped one 165 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException 166 * if there is no bean definition with the given name 167 * @throws BeansException if the initialization failed 168 * @see #initializeBean 169 */ 170 Object configureBean(Object existingBean, String beanName) throws BeansException; 171 172 173 //------------------------------------------------------------------------- 174 // Specialized methods for fine-grained control over the bean lifecycle 175 //------------------------------------------------------------------------- 176 177 /** 178 * Fully create a new bean instance of the given class with the specified 179 * autowire strategy. All constants defined in this interface are supported here. 180 * <p>Performs full initialization of the bean, including all applicable 181 * {@link BeanPostProcessor BeanPostProcessors}. This is effectively a superset 182 * of what {@link #autowire} provides, adding {@link #initializeBean} behavior. 183 * @param beanClass the class of the bean to create 184 * @param autowireMode by name or type, using the constants in this interface 185 * @param dependencyCheck whether to perform a dependency check for objects 186 * (not applicable to autowiring a constructor, thus ignored there) 187 * @return the new bean instance 188 * @throws BeansException if instantiation or wiring failed 189 * @see #AUTOWIRE_NO 190 * @see #AUTOWIRE_BY_NAME 191 * @see #AUTOWIRE_BY_TYPE 192 * @see #AUTOWIRE_CONSTRUCTOR 193 */ 194 Object createBean(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException; 195 196 /** 197 * Instantiate a new bean instance of the given class with the specified autowire 198 * strategy. All constants defined in this interface are supported here. 199 * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply 200 * before-instantiation callbacks (e.g. for annotation-driven injection). 201 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors} 202 * callbacks or perform any further initialization of the bean. This interface 203 * offers distinct, fine-grained operations for those purposes, for example 204 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor} 205 * callbacks are applied, if applicable to the construction of the instance. 206 * @param beanClass the class of the bean to instantiate 207 * @param autowireMode by name or type, using the constants in this interface 208 * @param dependencyCheck whether to perform a dependency check for object 209 * references in the bean instance (not applicable to autowiring a constructor, 210 * thus ignored there) 211 * @return the new bean instance 212 * @throws BeansException if instantiation or wiring failed 213 * @see #AUTOWIRE_NO 214 * @see #AUTOWIRE_BY_NAME 215 * @see #AUTOWIRE_BY_TYPE 216 * @see #AUTOWIRE_CONSTRUCTOR 217 * @see #AUTOWIRE_AUTODETECT 218 * @see #initializeBean 219 * @see #applyBeanPostProcessorsBeforeInitialization 220 * @see #applyBeanPostProcessorsAfterInitialization 221 */ 222 Object autowire(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException; 223 224 /** 225 * Autowire the bean properties of the given bean instance by name or type. 226 * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply 227 * after-instantiation callbacks (e.g. for annotation-driven injection). 228 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors} 229 * callbacks or perform any further initialization of the bean. This interface 230 * offers distinct, fine-grained operations for those purposes, for example 231 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor} 232 * callbacks are applied, if applicable to the configuration of the instance. 233 * @param existingBean the existing bean instance 234 * @param autowireMode by name or type, using the constants in this interface 235 * @param dependencyCheck whether to perform a dependency check for object 236 * references in the bean instance 237 * @throws BeansException if wiring failed 238 * @see #AUTOWIRE_BY_NAME 239 * @see #AUTOWIRE_BY_TYPE 240 * @see #AUTOWIRE_NO 241 */ 242 void autowireBeanProperties(Object existingBean, int autowireMode, boolean dependencyCheck) 243 throws BeansException; 244 245 /** 246 * Apply the property values of the bean definition with the given name to 247 * the given bean instance. The bean definition can either define a fully 248 * self-contained bean, reusing its property values, or just property values 249 * meant to be used for existing bean instances. 250 * <p>This method does <i>not</i> autowire bean properties; it just applies 251 * explicitly defined property values. Use the {@link #autowireBeanProperties} 252 * method to autowire an existing bean instance. 253 * <b>Note: This method requires a bean definition for the given name!</b> 254 * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors} 255 * callbacks or perform any further initialization of the bean. This interface 256 * offers distinct, fine-grained operations for those purposes, for example 257 * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor} 258 * callbacks are applied, if applicable to the configuration of the instance. 259 * @param existingBean the existing bean instance 260 * @param beanName the name of the bean definition in the bean factory 261 * (a bean definition of that name has to be available) 262 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException 263 * if there is no bean definition with the given name 264 * @throws BeansException if applying the property values failed 265 * @see #autowireBeanProperties 266 */ 267 void applyBeanPropertyValues(Object existingBean, String beanName) throws BeansException; 268 269 /** 270 * Initialize the given raw bean, applying factory callbacks 271 * such as {@code setBeanName} and {@code setBeanFactory}, 272 * also applying all bean post processors (including ones which 273 * might wrap the given raw bean). 274 * <p>Note that no bean definition of the given name has to exist 275 * in the bean factory. The passed-in bean name will simply be used 276 * for callbacks but not checked against the registered bean definitions. 277 * @param existingBean the existing bean instance 278 * @param beanName the name of the bean, to be passed to it if necessary 279 * (only passed to {@link BeanPostProcessor BeanPostProcessors}; 280 * can follow the {@link #ORIGINAL_INSTANCE_SUFFIX} convention in order to 281 * enforce the given instance to be returned, i.e. no proxies etc) 282 * @return the bean instance to use, either the original or a wrapped one 283 * @throws BeansException if the initialization failed 284 * @see #ORIGINAL_INSTANCE_SUFFIX 285 */ 286 Object initializeBean(Object existingBean, String beanName) throws BeansException; 287 288 /** 289 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean 290 * instance, invoking their {@code postProcessBeforeInitialization} methods. 291 * The returned bean instance may be a wrapper around the original. 292 * @param existingBean the existing bean instance 293 * @param beanName the name of the bean, to be passed to it if necessary 294 * (only passed to {@link BeanPostProcessor BeanPostProcessors}; 295 * can follow the {@link #ORIGINAL_INSTANCE_SUFFIX} convention in order to 296 * enforce the given instance to be returned, i.e. no proxies etc) 297 * @return the bean instance to use, either the original or a wrapped one 298 * @throws BeansException if any post-processing failed 299 * @see BeanPostProcessor#postProcessBeforeInitialization 300 * @see #ORIGINAL_INSTANCE_SUFFIX 301 */ 302 Object applyBeanPostProcessorsBeforeInitialization(Object existingBean, String beanName) 303 throws BeansException; 304 305 /** 306 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean 307 * instance, invoking their {@code postProcessAfterInitialization} methods. 308 * The returned bean instance may be a wrapper around the original. 309 * @param existingBean the existing bean instance 310 * @param beanName the name of the bean, to be passed to it if necessary 311 * (only passed to {@link BeanPostProcessor BeanPostProcessors}; 312 * can follow the {@link #ORIGINAL_INSTANCE_SUFFIX} convention in order to 313 * enforce the given instance to be returned, i.e. no proxies etc) 314 * @return the bean instance to use, either the original or a wrapped one 315 * @throws BeansException if any post-processing failed 316 * @see BeanPostProcessor#postProcessAfterInitialization 317 * @see #ORIGINAL_INSTANCE_SUFFIX 318 */ 319 Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName) 320 throws BeansException; 321 322 /** 323 * Destroy the given bean instance (typically coming from {@link #createBean}), 324 * applying the {@link org.springframework.beans.factory.DisposableBean} contract as well as 325 * registered {@link DestructionAwareBeanPostProcessor DestructionAwareBeanPostProcessors}. 326 * <p>Any exception that arises during destruction should be caught 327 * and logged instead of propagated to the caller of this method. 328 * @param existingBean the bean instance to destroy 329 */ 330 void destroyBean(Object existingBean); 331 332 333 //------------------------------------------------------------------------- 334 // Delegate methods for resolving injection points 335 //------------------------------------------------------------------------- 336 337 /** 338 * Resolve the bean instance that uniquely matches the given object type, if any, 339 * including its bean name. 340 * <p>This is effectively a variant of {@link #getBean(Class)} which preserves the 341 * bean name of the matching instance. 342 * @param requiredType type the bean must match; can be an interface or superclass 343 * @return the bean name plus bean instance 344 * @throws NoSuchBeanDefinitionException if no matching bean was found 345 * @throws NoUniqueBeanDefinitionException if more than one matching bean was found 346 * @throws BeansException if the bean could not be created 347 * @since 4.3.3 348 * @see #getBean(Class) 349 */ 350 <T> NamedBeanHolder<T> resolveNamedBean(Class<T> requiredType) throws BeansException; 351 352 /** 353 * Resolve a bean instance for the given bean name, providing a dependency descriptor 354 * for exposure to target factory methods. 355 * <p>This is effectively a variant of {@link #getBean(String, Class)} which supports 356 * factory methods with an {@link org.springframework.beans.factory.InjectionPoint} 357 * argument. 358 * @param name the name of the bean to look up 359 * @param descriptor the dependency descriptor for the requesting injection point 360 * @return the corresponding bean instance 361 * @throws NoSuchBeanDefinitionException if there is no bean with the specified name 362 * @throws BeansException if the bean could not be created 363 * @since 5.1.5 364 * @see #getBean(String, Class) 365 */ 366 Object resolveBeanByName(String name, DependencyDescriptor descriptor) throws BeansException; 367 368 /** 369 * Resolve the specified dependency against the beans defined in this factory. 370 * @param descriptor the descriptor for the dependency (field/method/constructor) 371 * @param requestingBeanName the name of the bean which declares the given dependency 372 * @return the resolved object, or {@code null} if none found 373 * @throws NoSuchBeanDefinitionException if no matching bean was found 374 * @throws NoUniqueBeanDefinitionException if more than one matching bean was found 375 * @throws BeansException if dependency resolution failed for any other reason 376 * @since 2.5 377 * @see #resolveDependency(DependencyDescriptor, String, Set, TypeConverter) 378 */ 379 @Nullable 380 Object resolveDependency(DependencyDescriptor descriptor, @Nullable String requestingBeanName) throws BeansException; 381 382 /** 383 * Resolve the specified dependency against the beans defined in this factory. 384 * @param descriptor the descriptor for the dependency (field/method/constructor) 385 * @param requestingBeanName the name of the bean which declares the given dependency 386 * @param autowiredBeanNames a Set that all names of autowired beans (used for 387 * resolving the given dependency) are supposed to be added to 388 * @param typeConverter the TypeConverter to use for populating arrays and collections 389 * @return the resolved object, or {@code null} if none found 390 * @throws NoSuchBeanDefinitionException if no matching bean was found 391 * @throws NoUniqueBeanDefinitionException if more than one matching bean was found 392 * @throws BeansException if dependency resolution failed for any other reason 393 * @since 2.5 394 * @see DependencyDescriptor 395 */ 396 @Nullable 397 Object resolveDependency(DependencyDescriptor descriptor, @Nullable String requestingBeanName, 398 @Nullable Set<String> autowiredBeanNames, @Nullable TypeConverter typeConverter) throws BeansException; 399 400}