spring源码 AutowireCapableBeanFactory接口

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package org.springframework.beans.factory.config;

import java.util.Set;

import org.springframework.beans.BeansException;

import org.springframework.beans.TypeConverter;

import org.springframework.beans.factory.BeanFactory;

import org.springframework.beans.factory.NoSuchBeanDefinitionException;

import org.springframework.beans.factory.NoUniqueBeanDefinitionException;

/**
　此接口主要是针对框架之外，没有向spring托管Bean的应用，通过暴露此功能，spring框架之外的程序，具有自动装配等spring的功能。
　需要注意的是，ApplicationContext接口并没有实现此接口，因为应用代码很少用到此功能，如果确实需要的话，可以调用ApplicationContext的
　　getAutowireCapableBeanFactory方法，来获取此接口的实例。如果一个类实现了此接口，那么很大程序上它还需要实现BeanFactoryAware接口
　　它可以在应用上下文中返回BeanFactory

 *

 * @author Juergen Hoeller

 * @since 04.12.2003

 * @see org.springframework.beans.factory.BeanFactoryAware

 * @see org.springframework.beans.factory.config.ConfigurableListableBeanFactory

 * @see org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()

 */

public interface AutowireCapableBeanFactory extends BeanFactory {

    /**

     * Constant that indicates no externally defined autowiring. Note that

     * BeanFactoryAware etc and annotation-driven injection will still be applied.
　　常量，用于表示外部自动装配功能是否可用 ，但是此标识不影响正常的（基于注解的等）自动装配功能

     * @see #createBean

     * @see #autowire

     * @see #autowireBeanProperties

     */

    int AUTOWIRE_NO = 0;

    /**

     * Constant that indicates autowiring bean properties by name

     * (applying to all bean property setters).
　　　　常量，表示按照名称自动装配bean属性（适用于所有bean属性设置器）

     * @see #createBean

     * @see #autowire

     * @see #autowireBeanProperties

     */

    int AUTOWIRE_BY_NAME = 1;

    /**

     * Constant that indicates autowiring bean properties by type

     * (applying to all bean property setters).
　　　　常量，表示按类型自动装配bean属性（适用于所有bean属性设置器）

     * @see #createBean

     * @see #autowire

     * @see #autowireBeanProperties

     */

    int AUTOWIRE_BY_TYPE = 2;

    /**

     * Constant that indicates autowiring the greediest constructor that

     * can be satisfied (involves resolving the appropriate constructor).
　　　　常量，表示按照贪婪策略匹配出最符合的构造方法来自动装配（）

     * @see #createBean

     * @see #autowire

     */

    int AUTOWIRE_CONSTRUCTOR = 3;

    /**

     * Constant that indicates determining an appropriate autowire strategy

     * through introspection of the bean class.
　　　　常量，表示自动识别一种装配策略来自动装配的常量

     * @see #createBean

     * @see #autowire

     * @deprecated as of Spring 3.0: If you are using mixed autowiring strategies,

     * prefer annotation-based autowiring for clearer demarcation of autowiring needs.

     */

    @Deprecated

    int AUTOWIRE_AUTODETECT = 4;

    //-------------------------------------------------------------------------

    // Typical methods for creating and populating external bean instances

    //-------------------------------------------------------------------------

    /**

     * Fully create a new bean instance of the given class.

     * <p>Performs full initialization of the bean, including all applicable

     * {@link BeanPostProcessor BeanPostProcessors}.

     * <p>Note: This is intended for creating a fresh instance, populating annotated

     * fields and methods as well as applying all standard bean initialization callbacks.

     * It does <i>not</> imply traditional by-name or by-type autowiring of properties;

     * use {@link #createBean(Class, int, boolean)} for those purposes.

     * @param beanClass the class of the bean to create

     * @return the new bean instance

     * @throws BeansException if instantiation or wiring failed
　　　　创建一个给定Class的实例。
　　　　执行此Bean所有的关于Bean生命周期的接口方法如BeanPostProcessor
　　　　此方法用于创建一个新实例，它会处理各种带有注解的域和方法，并且会调用所有bean初始化时所需要调用的回调函数
　　　* 此方法并不意味着by-name或者by-type方式的自动装配，如果需要使用这写功能，可以使用其重载方法

     */

    <T> T createBean(Class<T> beanClass) throws BeansException;

    /**

     * Populate the given bean instance through applying after-instantiation callbacks

     * and bean property post-processing (e.g. for annotation-driven injection).
通过调用给定bean的after-instantiation及post-processing接口，对bean进行配置。

     * <p>Note: This is essentially intended for (re-)populating annotated fields and

     * methods, 
　　　　此方法主要是用于处理Bean中带有注解的域和方法
　　　　either for new instances or for deserialized instances. It does

     * <i>not</i> imply traditional by-name or by-type autowiring of properties;

     * use {@link #autowireBeanProperties} for those purposes.
　此方法并不意味着by-name或者by-type方式的自动装配，如果需要使用这些功能，可以使用其重载方法autowireBeanProperties

     * @param existingBean the existing bean instance

     * @throws BeansException if wiring failed
　　　　

     */

    void autowireBean(Object existingBean) throws BeansException;

    /**

     * Configure the given raw bean: autowiring bean properties, applying

     * bean property values, applying factory callbacks such as {@code setBeanName}

     * and {@code setBeanFactory}, and also applying all bean post processors

     * (including ones which might wrap the given raw bean).
　　　　配置参数中指定的bean，包括自动装配其域，对其应用如setBeanName功能的回调函数。
　　　　并且会调用其所有注册的post processor。

     * <p>This is effectively a superset of what {@link #initializeBean} provides,

     * fully applying the configuration specified by the corresponding bean definition.
　　　　此方法提供的功能是initializeBean方法的超集，会应用所有注册在bean defineneition中的操作
　　　　不过需要BeanFactory中有参数中指定名字的BeanDefinition.

     * <b>Note: This method requires a bean definition for the given name!</b>

     * @param existingBean the existing bean instance

     * @param beanName the name of the bean, to be passed to it if necessary

     * (a bean definition of that name has to be available)

     * @return the bean instance to use, either the original or a wrapped one

     * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException

     * if there is no bean definition with the given name

     * @throws BeansException if the initialization failed

     * @see #initializeBean

     */

    Object configureBean(Object existingBean, String beanName) throws BeansException;

    //-------------------------------------------------------------------------

    // Specialized methods for fine-grained control over the bean lifecycle

    //-------------------------------------------------------------------------

    /**

     * Fully create a new bean instance of the given class with the specified

     * autowire strategy. All constants defined in this interface are supported here.

     * <p>Performs full initialization of the bean, including all applicable

     * {@link BeanPostProcessor BeanPostProcessors}. This is effectively a superset

     * of what {@link #autowire} provides, adding {@link #initializeBean} behavior.

     * @param beanClass the class of the bean to create

     * @param autowireMode by name or type, using the constants in this interface

     * @param dependencyCheck whether to perform a dependency check for objects

     * (not applicable to autowiring a constructor, thus ignored there)

     * @return the new bean instance

     * @throws BeansException if instantiation or wiring failed

     * @see #AUTOWIRE_NO

     * @see #AUTOWIRE_BY_NAME

     * @see #AUTOWIRE_BY_TYPE

     * @see #AUTOWIRE_CONSTRUCTOR
　　创建一个指定class的实例，通过参数可以指定其自动装配模式（by-name or by-type）.
　　会执行所有注册在此class上用以初始化bean的方法.如BeanPostProcessors等

     */

    Object createBean(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException;

    /**

     * Instantiate a new bean instance of the given class with the specified autowire

     * strategy. All constants defined in this interface are supported here.

     * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply

     * before-instantiation callbacks (e.g. for annotation-driven injection).

     * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}

     * callbacks or perform any further initialization of the bean. This interface

     * offers distinct, fine-grained operations for those purposes, for example

     * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}

     * callbacks are applied, if applicable to the construction of the instance.

     * @param beanClass the class of the bean to instantiate

     * @param autowireMode by name or type, using the constants in this interface

     * @param dependencyCheck whether to perform a dependency check for object

     * references in the bean instance (not applicable to autowiring a constructor,

     * thus ignored there)

     * @return the new bean instance

     * @throws BeansException if instantiation or wiring failed

     * @see #AUTOWIRE_NO

     * @see #AUTOWIRE_BY_NAME

     * @see #AUTOWIRE_BY_TYPE

     * @see #AUTOWIRE_CONSTRUCTOR

     * @see #AUTOWIRE_AUTODETECT

     * @see #initializeBean

     * @see #applyBeanPostProcessorsBeforeInitialization

     * @see #applyBeanPostProcessorsAfterInitialization
　　　　创建一个指定Class的实例，通过参数可以指定其自动装配模式（by-name or by-type）
　　　　会执行所有注册在此class上用以初始化bean的方法。如BeanPostProcessors等

     */

    Object autowire(Class<?> beanClass, int autowireMode, boolean dependencyCheck) throws BeansException;

    /**

     * Autowire the bean properties of the given bean instance by name or type.

     * Can also be invoked with {@code AUTOWIRE_NO} in order to just apply

     * after-instantiation callbacks (e.g. for annotation-driven injection).

     * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}

     * callbacks or perform any further initialization of the bean. This interface

     * offers distinct, fine-grained operations for those purposes, for example

     * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}

     * callbacks are applied, if applicable to the configuration of the instance.

     * @param existingBean the existing bean instance

     * @param autowireMode by name or type, using the constants in this interface

     * @param dependencyCheck whether to perform a dependency check for object

     * references in the bean instance

     * @throws BeansException if wiring failed

     * @see #AUTOWIRE_BY_NAME

     * @see #AUTOWIRE_BY_TYPE

     * @see #AUTOWIRE_NO
　　　　通过指定的自动装配方式来对给定的Bean进行自动装配
　　　　不过会调用指定bean注册的beanPostProcessors等回调函数来初始化Bean
　　　　如果指定装配方式AUTOWIRE_NO的话，不会自动装配属性，但是依然会调用BeanPiostProcesser等回调方法

     */

    void autowireBeanProperties(Object existingBean, int autowireMode, boolean dependencyCheck)

            throws BeansException;

    /**

     * Apply the property values of the bean definition with the given name to

     * the given bean instance. The bean definition can either define a fully

     * self-contained bean, reusing its property values, or just property values

     * meant to be used for existing bean instances.

     * <p>This method does <i>not</i> autowire bean properties; it just applies

     * explicitly defined property values. Use the {@link #autowireBeanProperties}

     * method to autowire an existing bean instance.

     * <b>Note: This method requires a bean definition for the given name!</b>

     * <p>Does <i>not</i> apply standard {@link BeanPostProcessor BeanPostProcessors}

     * callbacks or perform any further initialization of the bean. This interface

     * offers distinct, fine-grained operations for those purposes, for example

     * {@link #initializeBean}. However, {@link InstantiationAwareBeanPostProcessor}

     * callbacks are applied, if applicable to the configuration of the instance.

     * @param existingBean the existing bean instance

     * @param beanName the name of the bean definition in the bean factory

     * (a bean definition of that name has to be available)

     * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException

     * if there is no bean definition with the given name

     * @throws BeansException if applying the property values failed

     * @see #autowireBeanProperties
　　　　讲参数中指定的那个bean，注入给定实力当中
　　　　此方法不会自动注入bean的属性，它仅仅会应用在显式定义的属性之上。如果需要自动注入Bean属性，
　　　　　autowierBeanProperties方法
　　　　此方法需要BeanFactory中存在指定名字的Bean。除了InstantiationAwareBeanPostProcessor的回调函数外
　　　　此方法不会再bean上应用其它的例如BeanPostProcessors
　　　　等回调方法。不过可以调用其它诸如initializeBean等方法来达到目的

     */

    void applyBeanPropertyValues(Object existingBean, String beanName) throws BeansException;

    /**

     * Initialize the given raw bean, applying factory callbacks

     * such as {@code setBeanName} and {@code setBeanFactory},

     * also applying all bean post processors (including ones which

     * might wrap the given raw bean).

     * <p>Note that no bean definition of the given name has to exist

     * in the bean factory. The passed-in bean name will simply be used

     * for callbacks but not checked against the registered bean definitions.

     * @param existingBean the existing bean instance

     * @param beanName the name of the bean, to be passed to it if necessary

     * (only passed to {@link BeanPostProcessor BeanPostProcessors})

     * @return the bean instance to use, either the original or a wrapped one

     * @throws BeansException if the initialization failed
　　　　初始化参数中指定的bean,调用任何其注册的回调函数如setBean,setBeanFactory等。
　　　　另外还会调用此Bean上的所有PostProcessors方法

     */

    Object initializeBean(Object existingBean, String beanName) throws BeansException;

    /**

     * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean

     * instance, invoking their {@code postProcessBeforeInitialization} methods.

     * The returned bean instance may be a wrapper around the original.

     * @param existingBean the new bean instance

     * @param beanName the name of the bean

     * @return the bean instance to use, either the original or a wrapped one

     * @throws BeansException if any post-processing failed

     * @see BeanPostProcessor#postProcessBeforeInitialization
　　　　调用参数中指定bean的postProcessBeforeInitialization方法

     */

    Object applyBeanPostProcessorsBeforeInitialization(Object existingBean, String beanName)

            throws BeansException;

    /**

     * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing bean

     * instance, invoking their {@code postProcessAfterInitialization} methods.

     * The returned bean instance may be a wrapper around the original.

     * @param existingBean the new bean instance

     * @param beanName the name of the bean

     * @return the bean instance to use, either the original or a wrapped one

     * @throws BeansException if any post-processing failed

     * @see BeanPostProcessor#postProcessAfterInitialization
　　　　调用参数中指定bean的postProcessAfterInitialization方法

     */

    Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName)

            throws BeansException;

    /**

     * Destroy the given bean instance (typically coming from {@link #createBean}),

     * applying the {@link org.springframework.beans.factory.DisposableBean} contract as well as

     * registered {@link DestructionAwareBeanPostProcessor DestructionAwareBeanPostProcessors}.

     * <p>Any exception that arises during destruction should be caught

     * and logged instead of propagated to the caller of this method.

     * @param existingBean the bean instance to destroy
　　　　　销毁参数中给定的bean，同时调用此bean上的DisposableBean和DestructionAwareBeanPostProce
　　　　　在销毁途中，任何的异常情况都只应该被捕获和记录，而不应该向外抛出。

     */

    void destroyBean(Object existingBean);

    //-------------------------------------------------------------------------

    // Delegate methods for resolving injection points

    //-------------------------------------------------------------------------

    /**

     * Resolve the bean instance that uniquely matches the given object type, if any,

     * including its bean name.

     * <p>This is effectively a variant of {@link #getBean(Class)} which preserves the

     * bean name of the matching instance.

     * @param requiredType type the bean must match; can be an interface or superclass.

     * {@code null} is disallowed.

     * @return the bean name plus bean instance

     * @throws NoSuchBeanDefinitionException if no matching bean was found

     * @throws NoUniqueBeanDefinitionException if more than one matching bean was found

     * @throws BeansException if the bean could not be created

     * @since 4.3.3

     * @see #getBean(Class)
　　　　查找唯一符合指定类的实例，如果有，则返回实例的名字和实例本身和beanFactory中的getBean（class）方法类似，
　　　　只不过多加了一个bean的名字

     */

    <T> NamedBeanHolder<T> resolveNamedBean(Class<T> requiredType) throws BeansException;

    /**

     * Resolve the specified dependency against the beans defined in this factory.

     * @param descriptor the descriptor for the dependency (field/method/constructor)

     * @param requestingBeanName the name of the bean which declares the given dependency

     * @return the resolved object, or {@code null} if none found

     * @throws NoSuchBeanDefinitionException if no matching bean was found

     * @throws NoUniqueBeanDefinitionException if more than one matching bean was found

     * @throws BeansException if dependency resolution failed for any other reason

     * @since 2.5

     * @see #resolveDependency(DependencyDescriptor, String, Set, TypeConverter)
　　　　解析出在Factory中与指定bean有指定依赖关系的bean

     */

    Object resolveDependency(DependencyDescriptor descriptor, String requestingBeanName) throws BeansException;

    /**

     * Resolve the specified dependency against the beans defined in this factory.
　　　　解析指定bean在Factory中的依赖关系

     * @param descriptor the descriptor for the dependency (field/method/constructor)
　　　　　　　　　　　　　　　　依赖描述（field/method/constructor）

     * @param requestingBeanName the name of the bean which declares the given dependency
　　　　　　　　　　　　　　　　　　　　依赖描述所属的Bean

     * @param autowiredBeanNames a Set that all names of autowired beans (used for

     * resolving the given dependency) are supposed to be added to
　　　　　　　　　autowireBeanNames 与指定bean有依赖关系的Bean

     * @param typeConverter the TypeConverter to use for populating arrays and collections
　　　　　　　　　　　　　　　　　　用以转换数组和连表的转换器

     * @return the resolved object, or {@code null} if none found
　　　　　　　　　　解析结果，可能为null

     * @throws NoSuchBeanDefinitionException if no matching bean was found

     * @throws NoUniqueBeanDefinitionException if more than one matching bean was found

     * @throws BeansException if dependency resolution failed for any other reason

     * @since 2.5

     * @see DependencyDescriptor

　　　　

     */

    Object resolveDependency(DependencyDescriptor descriptor, String requestingBeanName,

            Set<String> autowiredBeanNames, TypeConverter typeConverter) throws BeansException;

}