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

}