BeanFactory

/**
 * BeanFactory是Spring Bean容器的根接口，是bean容器的基本客户端视图。其他接口类似ListableBeanFactory和ConfigurableBeanFactory可以用于特定的用途。
 * 此接口由包含许多bean定义的对象实现，每个bean定义由String名称唯一标识。
 * 根据bean定义，工厂将返回包含对象的独立实例（Prototype设计模式），或者单例共享实例（Singleton设计模式的高级替代，其中实例是工厂作用域的单例）。
 * 将返回哪种类型的实例取决于bean工厂配置：API是相同的。 从Spring 2.0开始，根据具体的应用程序上下文（例如Web环境中的“request”和“session”作用域），可以使用更多的作用域。
 * 这种方法的重点是BeanFactory是应用程序组件的中央注册表，并集中应用程序组件的配置（例如，不再需要单个对象读取属性文件）。
 * 请注意，通常最好依靠依赖注入（“推送”配置），通过setter或构造函数来配置应用程序对象，而不是像BeanFactory查找一样使用任何形式的“拉”配置。 Spring的依赖注入功能是使用这个BeanFactory接口及其子接口实现的。
 * 通常，BeanFactory将加载存储在配置源（例如XML文档）中的bean定义，并使用code org.springframework.beans包来配置bean。但是，实现类可以直接在Java代码中直接返回它创建的Java对象。对如何存储定义没有限制：LDAP，RDBMS，XML，属性文件等。鼓励实现类支持bean之间的引用（依赖注入）。
 * 与ListableBeanFactory中的方法相反，如果是HierarchicalBeanFactory，则此接口中的所有操作也将检查父工厂。如果在此工厂实例中找不到bean，则会询问直接父工厂。此工厂实例中的Bean应该覆盖任何父工厂中同名的Bean。
 *
 * Bean工厂实现应尽可能支持标准bean生命周期接口。 完整的初始化方法及其标准顺序是：
 * BeanNameAware.setBeanName()
 * BeanClassLoaderAware.setBeanClassLoader()
 * BeanFactoryAware.setBeanFactory()
 * EnvironmentAware.setEnvironment()
 * EmbeddedValueResolverAware.setEmbeddedValueResolver()
 * ResourceLoaderAware.setResourceLoader()  仅适用于在应用程序上下文中运行时
 * ApplicationEventPublisherAware.setApplicationEventPublisher() 仅适用于在应用程序上下文中运行时
 * MessageSourceAware.setMessageSource() 仅适用于在应用程序上下文中运行时
 * ApplicationContextAware.setApplicationContext() 仅适用于在应用程序上下文中运行时
 * ServletContextAware.setServletContext() 仅适用于在应用程序上下文中运行时
 * BeanPostProcessors.postProcessBeforeInitialization()和InitializingBean.afterPropertiesSet() 自定义初始化方法定义
 * BeanPostProcessors.postProcessAfterInitialization()
 *
 * 关闭bean工厂时，以下生命周期方法适用：
 * DestructionAwareBeanPostProcessors.postProcessBeforeDestruction()
 * DisposableBea.destroy 自定义的销毁方法定义
 */
public interface BeanFactory {

    /**
     * 用于取消引用FactoryBean实例，并将其与FactoryBean创建的bean区分开来。例如，如果名为myJndiObject的bean是FactoryBean，则获取＆myJndiObject将返回工厂，而不是工厂返回的实例。
     */
    String FACTORY_BEAN_PREFIX = "&";

    /**
     * 返回指定bean的实例，该实例可以是共享的或独立的。此方法允许Spring BeanFactory用作Singleton或Prototype设计模式的替代。 
     * 在Singleton bean的情况下，调用者可以保留对返回对象的引用。将别名转换回相应的规范bean名称。将询问父工厂是否在此工厂实例中找不到bean。
     * @param 命名要检索的bean的名称
     * @return bean的一个实例
     * @throws 如果没有具有指定名称的bean，抛出NoSuchBeanDefinitionException
     * @throws 如果无法获取bean，抛出BeansException
     */
    Object getBean(String name) throws BeansException;

    /**
     * 返回指定bean的实例，该实例可以是共享的或独立的。
     * 与getBean(String)的行为相同，但如果bean不是所需类型，则通过抛出BeanNotOfRequiredTypeException来提供类型安全性的度量。这意味着在转换结果正确时不能抛出ClassCastException,就像#getBean(String)一样。将别名转换回相应的规范bean名称。 将询问父工厂是否在此工厂实例中找不到bean。
     * @param 命名要检索的bean的名称
     * @param bean要匹配的类型，可以是接口或是超类
     * @return 一个bean实例
     * @throws 如果没有具有指定名称的bean，抛出NoSuchBeanDefinitionException
     * @throws 如果bean不是要求的类型，抛出BeanNotOfRequiredTypeException
     * @throws 如果bean不能创建，抛出BeansException
     */
    <T> T getBean(String name, Class<T> requiredType) throws BeansException;

    /**
     * 返回指定bean的实例，该实例可以是共享的或独立的。
     * 允许指定显式构造函数参数/工厂方法参数，覆盖bean定义中指定的默认参数（如果有）。
     * @param 命名要检索的bean的名称
     * @param args 使用显式参数创建bean实例时使用的参数（仅在创建新实例时应用，而不是在检索现有实例时应用）
     * @return 一个bean实例
     * @throws 如果没有具有指定名称的bean，抛出NoSuchBeanDefinitionException
     * @throws 如果已经给出了参数但受影响的bean不是Prototype,抛出BeanDefinitionStoreException
     * @throws 如果bean不能创建，抛出BeansException
     */
    Object getBean(String name, Object... args) throws BeansException;

    /**
     * 返回唯一匹配给定对象类型的bean实例（如果有）。此方法进入ListableBeanFactory按类型查找区域，但也可以根据给定类型的名称转换为常规的按名称查找。要跨越多组bean进行更广泛的检索操作，请使用 ListableBeanFactory和/或BeanFactoryUtils。
     * @param bean要匹配的类型，可以是接口或是超类
     * @return 匹配所需类型的单个bean的实例
     * @throws 如果没有找到给定类型的bean，抛出NoSuchBeanDefinitionException 
     * @throws 如果找到多个给定类型的bean，抛出NoUniqueBeanDefinitionException
     * @throws 如果无法创建bean，抛出BeansException
     */
    <T> T getBean(Class<T> requiredType) throws BeansException;

    /**
     * 返回指定bean的实例，该实例可以是共享的或独立的。
     * 允许指定显式构造函数参数/工厂方法参数，覆盖bean定义中指定的默认参数（如果有）。此方法进入ListableBeanFactory按类型查找区域，但也可以转换为传统的按名称查找 基于给定类型的名称。对于跨bean集的更广泛的检索操作，请使用ListableBeanFactory和/或BeanFactoryUtils。
     * @param requiredType bean要匹配的类型，可以是接口或是超类
     * @param args 使用显式参数创建bean实例时使用的参数（仅在创建新实例时应用，而不是在检索现有实例时应用）
     * @return 一个bean实例
     * @throws 如果没有找到给定类型的bean，抛出NoSuchBeanDefinitionException 
     * @throws 如果已经给出了参数但受影响的bean不是Prototype,抛出BeanDefinitionStoreException
     * @throws 如果无法创建bean，抛出BeansException
     * @since 4.1
     */
    <T> T getBean(Class<T> requiredType, Object... args) throws BeansException;

    /**
     * 返回指定bean的提供程序，允许对实例进行惰性按需检索，包括可用性和唯一性选项。
     * @param requiredType bean要匹配的类型，可以是接口或是超类
     * @return 相应的提供者句柄
     */
    <T> ObjectProvider<T> getBeanProvider(Class<T> requiredType);

    /**
     * 返回指定bean的提供程序，允许对实例进行惰性按需检索，包括可用性和唯一性选项。
     * @param requiredType bean要匹配的类型。可以是泛型类型声明。请注意，此处不支持集合类型，与反射注入点相反。要以编程方式检索与特定类型匹配的bean列表，请在此处将实际bean类型指定为参数，然后使用 ObjectProvider.orderedStream()或其延迟流/迭代选项。
     * @return 相应的提供者句柄
     */
    <T> ObjectProvider<T> getBeanProvider(ResolvableType requiredType);

    /**
     * 此bean工厂是否包含bean定义或具有给定名称的外部注册的singleton实例？
     * 如果给定的名称是别名，它将被转换回相应的规范bean名称。如果此工厂是分层的，将询问任何父工厂是否在这个工厂实例中找不到bean。如果找到匹配给定名称的bean定义或单例实例，则此方法将返回true。
     * 无论命名bean定义是具体的还是抽象的，lazy还是eager的，作用域与否。 因此，请注意此方法的true返回值不一定表示getBean将能够获取同名的实例。
     * @param name 查询的bean的名称
     * @return 给定名称的bean是否存在
     */
    boolean containsBean(String name);

    /**
     * 该Bean是否是共享的单例? 也就是说， getBean()方法总是返回相同的实例？
     * 注意：返回false的此方法不能清楚地表明是独立的实例。它表示非单例实例，也可以对应于作用域的bean。使用isPrototype操作显式检查是否是独立的实例。将别名转换回相应的规范bean名称。将询问父工厂是否在此工厂实例中找不到bean。
     * @param name 查询的bean的名称
     * @return 该bean是否有单例实例
     * @throws 如果没有给定名称的Bean，抛出NoSuchBeanDefinitionException
     */
    boolean isSingleton(String name) throws NoSuchBeanDefinitionException;

    /**
     * 该bean是否是Prototype? 也就是说，getBean总会返回独立实例吗？
     * 注意：返回false的此方法不能清楚地指示单个对象。它表示非独立实例，也可以对应于范围内的bean。使用isSingleton操作显式检查共享单例实例。将别名转换回相应的规范bean名称。将询问父工厂是否在此工厂实例中找不到bean。
     * @param name 查询的bean的名称
     * @return 这个bean是否总是提供独立的实例
     * @throws 如果没有给定名称的Bean，抛出NoSuchBeanDefinitionException
     */
    boolean isPrototype(String name) throws NoSuchBeanDefinitionException;

    /**
     * 检查具有给定名称的bean是否与指定的类型匹配。更具体地说，检查对给定名称的getBean调用是否将返回可分配给指定目标类型的对象。将别名转换回相应的规范bean的名称.将询问父工厂是否在此工厂实例中找不到bean。
     * @param name 查询bean的名称
     * @param typeToMatch 要匹配的类型
     * @return 如果Bean类型匹配，返回true;如果bean类型不匹配或不确定，返回false。
     * @throws 如果没有给定名称的Bean，抛出NoSuchBeanDefinitionException
     */
    boolean isTypeMatch(String name, ResolvableType typeToMatch) throws NoSuchBeanDefinitionException;

    /**
     * 检查具有给定名称的bean是否与指定的类型匹配。更具体地说，检查对给定名称的getBean调用是否将返回可分配给指定目标类型的对象。将别名转换回相应的规范bean的名称.将询问父工厂是否在此工厂实例中找不到bean。
     * @param name 查询bean的名称
     * @param typeToMatch 要匹配的类型
     * @return 如果Bean类型匹配，返回true;如果bean类型不匹配或不确定，返回false。
     * @throws 如果没有给定名称的Bean，抛出NoSuchBeanDefinitionException
     */
    boolean isTypeMatch(String name, Class<?> typeToMatch) throws NoSuchBeanDefinitionException;

    /**
     * 确定给定名称的bean的类型。 进一步来说，确定getBean方法为给定bean名称返回的对象类型。对于FactoryBean，返回FactoryBean创建的对象类型，由FactoryBean.getObjectType()公开。将别名转换回相应的规范bean名称。将询问父工厂是否在此工厂实例中找不到bean。
     * @param name 查询的bean的名称
     * @return bean的类型, 或者不可确定返回null。
     * @throws 如果没有给定名称的Bean，抛出NoSuchBeanDefinitionException
     */
    @Nullable
    Class<?> getType(String name) throws NoSuchBeanDefinitionException;

    /**
     * 返回给定bean名称的别名（如果有）。所有这些别名在getBean调用中使用时指向同一个bean。
     * 如果给定名称是别名，则对应原始bean名称和其他别名（ 如果有的话）将返回，原始bean名称是数组中的第一个元素。将询问父工厂是否在此工厂实例中找不到bean。
     * @param name 用于检查别名的bean名称
     * @return 别名，如果没有，则为空数组
     */
    String[] getAliases(String name);

}