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);

}