/*
* Copyright 2002-2010 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.beans.factory;
import org.springframework.beans.BeansException;
/**
* 一个访问Spring Bean容器的根接口
* 这是一个bean容器的基本客户端视图
* 进一步接口如 ListableBeanFactory 和 ConfigurableBeanFactory 用于特定用途
*
* The root interface for accessing a Spring bean container.
* This is the basic client view of a bean container;
* further interfaces such as {@link ListableBeanFactory} and
* {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
* are available for specific purposes.
*
* 这个接口被实现为 持有若干Bean定义的对象，
* 每一个字符串名称唯一标识。根据bean的定义
* 该工厂将返回包含对象的独立实例（原型设计模式），
* 或单个共享实例（单例设计模式的一个更好的选择,.......
*
* <p>This interface is implemented by objects that hold a number of bean definitions,
* each uniquely identified by a String name. Depending on the bean definition,
* the factory will return either an independent instance of a contained object
* (the Prototype design pattern), or a single shared instance (a superior
* alternative to the Singleton design pattern, in which the instance is a
* single666the API is the same. Since Spring
* 2.0, further scopes are available depending on the concrete application
* context (e.g. "request" and "session" scopes in a web environment).
*
* 这种方法的要点是BeanFactory是一个应用程序组件的中央登记处，
* 并集中配置应用程序组件（例如不用再单个对象需要去读取properties文件 ）。
* 见第4和第11章节<Expert One-on-One J2EE Design and Development>讨论这种方法的好处
*
* <p>The point of this approach is that the BeanFactory is a central registry
* of application components, and centralizes configuration of application
* components (no more do individual objects need to read properties files,
* for example). See chapters 4 and 11 of "Expert One-on-One J2EE Design and
* Development" for a discussion of the benefits of this approach.
*
* 请注意，它一般是依靠依赖注入（"推"的配置）来配置应用程序对象，通过setters或构造，
* 而不是用任何形式拉的配置就像BeanFactory lookup.
* 使用BeanFactory接口和它的子接口来实现Spring的依赖注入功能
*
* <p>Note that it is generally better to rely on Dependency Injection
* ("push" configuration) to configure application objects through setters
* or constructors, rather than use any form of "pull" configuration like a
* BeanFactory lookup. Spring's Dependency Injection functionality is
* implemented using this BeanFactory interface and its subinterfaces.
*
* 通常，一个BeanFactory将会加载存储bean定义的配置源（如XML文档），和使用org.springframework.beans包来配置beans.
* 然而，一个实现可以简单的返回Java对象 必要的直接创建在Java代码中。
* 有关于如何定义可以存储的没有任何限制：LDAP,RDBMS,XML,properties文件等等。
* 鼓励实现支持beans之间的引用（依赖注入）
*
* <p>Normally a BeanFactory will load bean definitions stored in a configuration
* source (such as an XML document), and use the <code>org.springframework.beans</code>
* package to configure the beans. However, an implementation could simply return
* Java objects it creates as necessary directly in Java code. There are no
* constraints on how the definitions could be stored: LDAP, RDBMS, XML,
* properties file, etc. Implementations are encouraged to support references
* amongst beans (Dependency Injection).
*
* 对比方法{@link ListableBeanFactory},在此接口中的所有操作也将检查父工厂，如果这是一个{@link HierarchicalBeanFactory}.
* 如果一个bean在这个工厂实例中没有找到，则父工厂将立即被问。
* beans在这家工厂实例都应该覆盖在任何父工厂的同名bean.
*
* <p>In contrast to the methods in {@link ListableBeanFactory}, all of the
* operations in this interface will also check parent factories if this is a
* {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance,
* the immediate parent factory will be asked. Beans in this factory instance
* are supposed to override beans of the same name in any parent factory.
*
* bean工厂的实现应该尽可能的支持标准bean生命周期接口。
* 全部初始化方法和他们的标准顺序是：
* 1. BeanNameAware ------> setBeanName
* 2. BeanClassLoaderAware ------> setBeanClassLoader
* 3. BeanFactoryAware ------> setBeanFactory
* 4. ResourceLoaderAware ------> setResourceLoader ( ApplicationContext )
* 5. ApplicationEventPublisherAware------> setApplicationEventPublisher ( ApplicationContext )
* 6. MessageSourceAware ------> setMessageSource ( ApplicationContext )
* 7. ApplicationContextAware ------> setApplicationContext ( ApplicationContext )
* 8. ServletContextAware ------> setServletContext ( ApplicationContext )
* 9. BeanPostProcessors ------> postProcessBeforeInitialization
* 10.InitializingBean ------> afterPropertiesSet
* 11. init-method 定义
* 12.BeanPostProcessors ------> postProcessAfterInitialization
*
* <p>Bean factory implementations should support the standard bean lifecycle interfaces
* as far as possible. The full set of initialization methods and their standard order is:<br>
* 1. BeanNameAware's <code>setBeanName</code><br>
* 2. BeanClassLoaderAware's <code>setBeanClassLoader</code><br>
* 3. BeanFactoryAware's <code>setBeanFactory</code><br>
* 4. ResourceLoaderAware's <code>setResourceLoader</code>
* (only applicable when running in an application context)<br>
* 5. ApplicationEventPublisherAware's <code>setApplicationEventPublisher</code>
* (only applicable when running in an application context)<br>
* 6. MessageSourceAware's <code>setMessageSource</code>
* (only applicable when running in an application context)<br>
* 7. ApplicationContextAware's <code>setApplicationContext</code>
* (only applicable when running in an application context)<br>
* 8. ServletContextAware's <code>setServletContext</code>
* (only applicable when running in a web application context)<br>
* 9. <code>postProcessBeforeInitialization</code> methods of BeanPostProcessors<br>
* 10. InitializingBean's <code>afterPropertiesSet</code><br>
* 11. a custom init-method definition<br>
* 12. <code>postProcessAfterInitialization</code> methods of BeanPostProcessors
*
* 一个bean工厂的关闭，下面的生命周期方法适用于：
* 1.DisposableBean ------> destroy
* 2. destroy-method定义
*
* <p>On shutdown of a bean factory, the following lifecycle methods apply:<br>
* 1. DisposableBean's <code>destroy</code><br>
* 2. a custom destroy-method definition
*
* @author Rod Johnson
* @author Juergen Hoeller
* @since 13 April 2001
* @see BeanNameAware#setBeanName
* @see BeanClassLoaderAware#setBeanClassLoader
* @see BeanFactoryAware#setBeanFactory
* @see org.springframework.context.ResourceLoaderAware#setResourceLoader
* @see org.springframework.context.ApplicationEventPublisherAware#setApplicationEventPublisher
* @see org.springframework.context.MessageSourceAware#setMessageSource
* @see org.springframework.context.ApplicationContextAware#setApplicationContext
* @see org.springframework.web.context.ServletContextAware#setServletContext
* @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessBeforeInitialization
* @see InitializingBean#afterPropertiesSet
* @see org.springframework.beans.factory.support.RootBeanDefinition#getInitMethodName
* @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessAfterInitialization
* @see DisposableBean#destroy
* @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName
*/
public interface BeanFactory {
/**
* 用于取消引用的一个FactoryBean实例和区分FactoryBean创建的bean
* 例如，一个bean名字为myJndiObject的FactoryBean,
* 那么&myJndiObject将会返回FactoryBean本身，而不是FactoryBean产生的对象
*
* Used to dereference a {@link FactoryBean} instance and distinguish it from
* beans <i>created</i> by the FactoryBean. For example, if the bean named
* <code>myJndiObject</code> is a FactoryBean, getting <code>&myJndiObject</code>
* will return the factory, not the instance returned by the factory.
*/
String FACTORY_BEAN_PREFIX = "&";
/**
* 返回一个可能是共享的或者独立的指定bean的实例
* 此方法允许Spring BeanFactory更换为单例设计模式或者原型设计模式
* 调用者可保留在单例模式的情况下返回的对象的引用
* 转换回相应的规范bean的名称别名
* 会调用父工厂如果该bean不能在当前工厂实例中找到
*
* Return an instance, which may be shared or independent, of the specified bean.
* <p>This method allows a Spring BeanFactory to be used as a replacement for the
* Singleton or Prototype design pattern. Callers may retain references to
* returned objects in the case of Singleton beans.
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to retrieve
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there is no bean definition
* with the specified name
* @throws BeansException if the bean could not be obtained
*/
Object getBean(String name) throws BeansException;
/**
* 行为与getBean(String)相同，但提供一个类型安全措施
* 抛出一个BeanNotOfRequiredTypeException如果该bean不是所需的类型
* 这意味着ClassCastException不能被抛出铸造正确地结果，这也可能发生在getBean(String)
*
* Return an instance, which may be shared or independent, of the specified bean.
* <p>Behaves the same as {@link #getBean(String)}, but provides a measure of type
* safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the
* required type. This means that ClassCastException can't be thrown on casting
* the result correctly, as can happen with {@link #getBean(String)}.
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to retrieve
* @param requiredType type the bean must match. Can be an interface or superclass
* of the actual class, or <code>null</code> for any match. For example, if the value
* is <code>Object.class</code>, this method will succeed whatever the class of the
* returned instance.
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there's no such bean definition
* @throws BeanNotOfRequiredTypeException if the bean is not of the required type
* @throws BeansException if the bean could not be created
*/
<T> T getBean(String name, Class<T> requiredType) throws BeansException;
/**
* Return the bean instance that uniquely matches the given object type, if any.
* @param requiredType type the bean must match; can be an interface or superclass.
* {@literal null} is disallowed.
* <p>This method goes into {@link ListableBeanFactory} by-type lookup territory
* but may also be translated into a conventional by-name lookup based on the name
* of the given type. For more extensive retrieval operations across sets of beans,
* use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}.
* @return an instance of the single bean matching the required type
* @throws NoSuchBeanDefinitionException if there is not exactly one matching bean found
* @since 3.0
* @see ListableBeanFactory
*/
<T> T getBean(Class<T> requiredType) throws BeansException;
/**
* 允许指定明确的构造函数的参数/工厂方法的参数，覆盖在Bean定义中指定的默认参数（如果有的话）。
*
* Return an instance, which may be shared or independent, of the specified bean.
* <p>Allows for specifying explicit constructor arguments / factory method arguments,
* overriding the specified default arguments (if any) in the bean definition.
* @param name the name of the bean to retrieve
* @param args arguments to use if creating a prototype using explicit arguments to a
* static factory method. It is invalid to use a non-null args value in any other case.
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there's no such bean definition
* @throws BeanDefinitionStoreException if arguments have been given but
* the affected bean isn't a prototype
* @throws BeansException if the bean could not be created
* @since 2.5
*/
Object getBean(String name, Object... args) throws BeansException;
/**
* 这个bean工厂是否包含与给定名称的bean？
* 更具体地说，是的{@ link＃getBean}能够获得给定名称的Bean实例？
*
* Does this bean factory contain a bean with the given name? More specifically,
* is {@link #getBean} able to obtain a bean instance for the given name?
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to query
* @return whether a bean with the given name is defined
*/
boolean containsBean(String name);
/**
* 这是一个共享的单例Bean吗？
* 也就是说，{@link #getBean}将总是返回同一个实例吗？
* 注意：此方法返回false没有明确表示独立的实例。
* 这表明非singleton的情况下，可能对应一个范围的bean以及。
* 使用{@link #isPrototype}操作明确检查独立实例。
*
* Is this bean a shared singleton? That is, will {@link #getBean} always
* return the same instance?
* <p>Note: This method returning <code>false</code> does not clearly indicate
* independent instances. It indicates non-singleton instances, which may correspond
* to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly
* check for independent instances.
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to query
* @return whether this bean corresponds to a singleton instance
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @see #getBean
* @see #isPrototype
*/
boolean isSingleton(String name) throws NoSuchBeanDefinitionException;
/**
* 这是一个原型bean吗？
* 也就是说，{@link #getBean}将总是返回独立的实例吗？
*
* Is this bean a prototype? That is, will {@link #getBean} always return
* independent instances?
* <p>Note: This method returning <code>false</code> does not clearly indicate
* a singleton object. It indicates non-independent instances, which may correspond
* to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly
* check for a shared singleton instance.
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to query
* @return whether this bean will always deliver independent instances
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @since 2.0.3
* @see #getBean
* @see #isSingleton
*/
boolean isPrototype(String name) throws NoSuchBeanDefinitionException;
/**
* 检查是否具有给定名称的bean指定的类型相匹配。
* 更具体地说，检查是否一个{@＃getBean}给定名称的调用将返回一个对象，它是分配给指定的目标类型。
*
* Check whether the bean with the given name matches the specified type.
* More specifically, check whether a {@link #getBean} call for the given name
* would return an object that is assignable to the specified target type.
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to query
* @param targetType the type to match against
* @return <code>true</code> if the bean type matches,
* <code>false</code> if it doesn't match or cannot be determined yet
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @since 2.0.1
* @see #getBean
* @see #getType
*/
boolean isTypeMatch(String name, Class targetType) throws NoSuchBeanDefinitionException;
/**
* 确定具有给定名称的bean的类型。
* 更具体的说，指定了名称的{@link #getBean}返回的bean的对象类型
*
* Determine the type of the bean with the given name. More specifically,
* determine the type of object that {@link #getBean} would return for the given name.
* <p>For a {@link FactoryBean}, return the type of object that the FactoryBean creates,
* as exposed by {@link FactoryBean#getObjectType()}.
* <p>Translates aliases back to the corresponding canonical bean name.
* Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the name of the bean to query
* @return the type of the bean, or <code>null</code> if not determinable
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @since 1.1.2
* @see #getBean
* @see #isTypeMatch
*/
Class<?> getType(String name) throws NoSuchBeanDefinitionException;
/**
* 返回给定的bean的名称的别名，如果有的话。
* 所有这些别名指向同一个bean使用时{＃getBean}调用。
* 如果给定的名称是一个别名，返回相应的原始bean的名称和其它别名（如果有的话）
*
* Return the aliases for the given bean name, if any.
* All of those aliases point to the same bean when used in a {@link #getBean} call.
* <p>If the given name is an alias, the corresponding original bean name
* and other aliases (if any) will be returned, with the original bean name
* being the first element in the array.
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* @param name the bean name to check for aliases
* @return the aliases, or an empty array if none
* @see #getBean
*/
String[] getAliases(String name);
}
