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