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

}