Spring源码解析 - BeanFactory 接口

package org.springframework.beans.factory;

import org.springframework.beans.BeansException;
import org.springframework.core.ResolvableType;
import org.springframework.lang.Nullable;

/**
 * 1、概述
 *  BeanFactory是访问Spring Bean容器的根接口，实现此接口的类可以生成BeanDefinition。
 *  根据BeanDefinition和BeanFactory的配置，返回包含对象的独立示例（原型设计模式）或单个共享示例（单例模式）。
 *  通常，BeanFactory会加载存储在配置源（xml文件甚至于ldap或其他属性文件,注解）中的Bean的定义。
 *
 * 2.BeanFactory的子接口
 *  Bean工厂实现应该尽可能支持标准的Bean生命周期接口。BeanFactory的子接口实现及其作用：
 *   -- ListableBeanFactory：支持获取BeanDefinition的beanNames；
 *   -- HierarchicalBeanFactory：可以获取到父类工厂，且此接口中的所有操作都会检查父工厂；
 *   -- AutowireCapableBeanFactory：，支持在创建Bean的过程中对Bean进行自动装配。
 *
 * 3.关闭BeanFactory
 *  关闭bean工厂时，以下生命周期方法适用：
 *  --> postProcessBeforeDestroyment：销毁wareBeanPostProcessors的方法；
 *  --> DisposableBean的destroy()方法；
 *  --> 自定义销毁方法定义。
 *
 *  4.该类中包含的方法有
 *      getBean：获取一个bean实例；
 *      containsBean(String)：根据名称判断是否包含一个bean；
 *      isSingleton(String)：根据名称判断是否单例；
 *      isPrototype(String)：根据名称判断是否多例（原型）；
 *      isTypeMath：是否类型匹配；
 *      getType：获取bean的类型；
 *      getAliases(String)：根据名称获取所有别名。
 */
public interface BeanFactory {

    /**
     * 用于取消对FactoryBean的引用。比如：如果名为“myJndiObject”的bean是一个FactoryBean：
     * (1) “myJndiObject”返回工厂实例；
     * (2) “&myJndiObject”将返回工厂，而不是工厂返回的实例。
     * Tip：和C语言中的“&”：&xxx是代表对象地址，xxx代表对象指针。
     */
    String FACTORY_BEAN_PREFIX = "&";
    
    /**
     * 根据Bean的名称获取一个Bean实例
     * @param name bean的名称
     * @return 一个bean实例
     * @throws BeansException 如果bean无法被获取则抛出异常
     */
    Object getBean(String name) throws BeansException;
    
    // 根据Bean的名称和Bean的类型获取Bean实例
    <T> T getBean(String name, Class<T> requiredType) throws BeansException;
    
    Object getBean(String name, Object... args) throws BeansException;
    
    // 根据Bean的类型来获取Bean实例
    <T> T getBean(Class<T> requiredType) throws BeansException;
    
    <T> T getBean(Class<T> requiredType, Object... args) throws BeansException;
    
    /**
     * 返回指定bean的提供程序，允许延迟按需检索实例，包括可用性和唯一性选项。
     * @param requiredType 类型必须和bean匹配，可以解开或者超类
     * @return 相应的提供程序句柄
     * @since 5.1
     */
    <T> ObjectProvider<T> getBeanProvider(Class<T> requiredType);
    
    <T> ObjectProvider<T> getBeanProvider(ResolvableType requiredType);
    
    /**
     * 根据名称判断bean实例是否已经存在，存在以下三种情况：
     * （1）如果给定的名称是别名，它将被转换回相应的规范bean名称；
     * （2）如果这个工厂是hierarchical类型的，当bean实例在此工厂中不存在时，将查询任何父工厂是否存在bean实例；
     * （3）如果根据名称找到一个bean定义或singleton实例，无论命名的bean定义是具体的还是抽象的、懒惰的还是急切的、在作用域内的，这个方法都将返回true。
     *      因此，请注意，这个方法的返回值为true时，并不一定表示"getBean()"将能够获得同名的实例。
     * @param name bean的名称
     * @return true:存在; false:不存在
     */
    boolean containsBean(String name);

    /**
     * 根据名称判断这个bean是共享单例。即判断getBean()是否总是返回相同的实例。
     * 注意：返回false时，表明它是一个非单例实例。同时，如果当前工厂内找不到，则会从所有父工厂中查找。
     * @param name bean的名称
     * @return bean是否单例bean
     * @throws NoSuchBeanDefinitionException 如果根据名称无法查找到bean
     */
    boolean isSingleton(String name) throws NoSuchBeanDefinitionException;

    /**
     * 根据名称判断这个bean是原型bean。即判断getBean()是否总是返回不同的实例。
     * 注意：方法返回false时并不能清楚地指示一个singleton对象。它表示非独立实例，也可能对应于作用域bean。
     *      使用isSingleton()操作可以显式检查共享单例实例。同时，如果当前工厂内找不到，则会从所有父工厂中查找。
     * @param name bean的名称
     * @return bean是否原型bean
     * @throws NoSuchBeanDefinitionException 如果根据名称无法查找到bean
     */
    boolean isPrototype(String name) throws NoSuchBeanDefinitionException;

    /**
     * 判断该名称对应的bean是否该类型
     * @param name bean的名称
     * @param typeToMatch 类型
     * @return true：类型匹配; false：类型不匹配
     * @throws NoSuchBeanDefinitionException 如果根据名称无法查找到bean
     */
    boolean isTypeMatch(String name, Class<?> typeToMatch) throws NoSuchBeanDefinitionException;
    
    // 判断该名称对应的bean是否该类型
    boolean isTypeMatch(String name, ResolvableType typeToMatch) throws NoSuchBeanDefinitionException;

    /**
     * 根据名称获取bean的类型。注意：这个方法可能会导致未被初始化的bean初始化。
     * @param name bean的名称
     * @return bean的类型, 或者null(bean不存在时)
     * @throws NoSuchBeanDefinitionException 如果根据名称无法查找到bean
     */
    @Nullable
    Class<?> getType(String name) throws NoSuchBeanDefinitionException;
    
    // 根据名称获取bean的类型（allowFactoryBeanInit：是否允许bean在获取过程中初始化）。
    @Nullable
    Class<?> getType(String name, boolean allowFactoryBeanInit) throws NoSuchBeanDefinitionException;
    
    // 根据名称返回指定名称的所有别名（如果有；如果没有则返回空）
    String[] getAliases(String name);

}