package org.springframework.beans.factory;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.*;
import org.springframework.core.ResolvableType;
import org.springframework.lang.Nullable;
/**
* The root interface for accessing a Spring bean container.
* 用于访问Springbean容器的根接口。
*
* <p>This is the basic client view of a bean container;
* 这是bean容器的基本客户端视图;
* further interfaces such as {@link ListableBeanFactory} and
* {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
* are available for specific purposes.
* <p>
* 其他接口,如{@link ListableBeanFactory}和
* {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
* 可用于特定用途。
*
* <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
* singleton in the scope of the factory).
* 这个接口由包含许多bean定义的对象实现,每个bean定义由一个字符串名唯一标识。根据bean定义,
* 工厂将返回包含对象的独立实例(原型设计模式)或单个共享实例(单件设计模式的高级替代方案,其中实例是工厂范围内的单件)。
* <p>
* Which type of instance will be returned
* depends on the bean factory configuration: the API is the same.
* 返回哪种类型的实例取决于bean工厂配置:API是相同的。
* Since Spring 2.0, further scopes are available depending on the concrete application
* context (e.g. "request" and "session" scopes in a web environment).
* 自Spring2.0以来,根据具体的应用程序上下文(例如web环境中的“请求”和“会话”作用域),可以使用更多的作用域。
*
* <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.
* 这种方法的要点是BeanFactory是应用程序组件的中心注册表,并集中配置应用程序组件(例如,单个对象不再需要读取属性文件)。
* 有关这种方法的好处的讨论,请参阅“专家一对一J2EE设计和开发”的第4章和第11章。
*
* <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.
* 请注意,通常最好依靠依赖项注入(“推”配置)通过setter或构造函数配置应用程序对象,
* 而不是使用任何形式的“拉”配置,如BeanFactory查找。
* <p>
* Spring's Dependency Injection functionality is
* implemented using this BeanFactory interface and its subinterfaces.
* Spring的依赖项注入功能是使用这个BeanFactory接口及其子接口实现的。
*
* <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}
* 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).
* 通常,BeanFactory将加载存储在配置源(如XML文档)中的bean定义,并使用{@code org.springframework.beans}包来配置bean。
* 然而,一个实现可以直接在Java代码中返回它根据需要创建的Java对象。对于如何存储定义没有任何限制:LDAP、RDBMS、XML、属性文件等。
* 建议实现支持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}.
* 与{@link ListableBeanFactory}中的方法不同,如果这是一个{@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应覆盖任何父工厂中同名的bean。
*
* <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:
* Bean工厂实现应该尽可能支持标准Bean生命周期接口。整套初始化方法及其标准顺序为:
* <ol>
* <li>BeanNameAware's {@code setBeanName}
* <li>BeanClassLoaderAware's {@code setBeanClassLoader}
* <li>BeanFactoryAware's {@code setBeanFactory}
* <li>EnvironmentAware's {@code setEnvironment}
* <li>EmbeddedValueResolverAware's {@code setEmbeddedValueResolver}
* <li>ResourceLoaderAware's {@code setResourceLoader}
* (only applicable when running in an application context)
* <li>ApplicationEventPublisherAware's {@code setApplicationEventPublisher}
* (only applicable when running in an application context)
* <li>MessageSourceAware's {@code setMessageSource}
* (only applicable when running in an application context)
* <li>ApplicationContextAware's {@code setApplicationContext}
* (only applicable when running in an application context)
* <li>ServletContextAware's {@code setServletContext}
* (only applicable when running in a web application context)
* <li>{@code postProcessBeforeInitialization} methods of BeanPostProcessors
* <li>InitializingBean's {@code afterPropertiesSet}
* <li>a custom {@code init-method} definition
* <li>{@code postProcessAfterInitialization} methods of BeanPostProcessors
* </ol>
*
* <p>On shutdown of a bean factory, the following lifecycle methods apply:
* <ol>
* <li>{@code postProcessBeforeDestruction} methods of DestructionAwareBeanPostProcessors
* <li>DisposableBean's {@code destroy}
* <li>a custom {@code destroy-method} definition
* </ol>
*
* @author Rod Johnson
* @author Juergen Hoeller
* @author Chris Beams
* @see BeanNameAware#setBeanName
* @see BeanClassLoaderAware#setBeanClassLoader
* @see BeanFactoryAware#setBeanFactory
* @see org.springframework.context.EnvironmentAware#setEnvironment
* @see org.springframework.context.EmbeddedValueResolverAware#setEmbeddedValueResolver
* @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 org.springframework.beans.factory.config.DestructionAwareBeanPostProcessor#postProcessBeforeDestruction
* @see DisposableBean#destroy
* @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName
* @since 13 April 2001
*/
public interface BeanFactory {
/**
* 用于取消对FactoryBean实例的引用,并将其与FactoryBean创建的Bean<i>区分开来。
* 例如,如果名为codemyJndiObject的bean是FactoryBean,
* 那么获取myJndiObject将返回工厂,而不是工厂返回的实例。
* =============================
* 说人话:看不懂
*/
String FACTORY_BEAN_PREFIX = "&";
/**
* 返回一个实例,该实例可以是共享的也可以是独立的。
* 此方法允许使用SpringBeanFactory替代Singleton或Prototype设计模式。对于单例bean,调用方可以保留对返回对象的引用。
* 将别名转换回相应的规范bean名称。
* 将询问父工厂是否在此工厂实例中找不到该bean。
* ======================================================================
* 说人话就是可以通过这个方法获取单例或者多例的对象引用。在获取对象时优先使用父类的getBean方法。
*
* @param name the name of the bean to retrieve
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there is no bean with the specified name
* @throws BeansException if the bean could not be obtained
*/
Object getBean(String name) throws BeansException;
/**
* Return an instance, which may be shared or independent, of the specified bean.
* 返回一个实例,该实例可以是共享的也可以是独立的。
* <p>Behaves the same as {@link #getBean(String)},
* 和 方法 getBean(String) 类似
* but provides a measure of type
* safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the
* required type.
* 但是,如果bean不是必需的类型,则通过抛出BeanNotOfRequiredTypeException来提供类型安全性度量
* This means that ClassCastException can't be thrown on casting
* the result correctly, as can happen with {@link #getBean(String)}.
* 这意味着ClassCastException不能像getBean(String)那样在正确转换结果时抛出
* <p>Translates aliases back to the corresponding canonical bean name.
* 将别名转换回相应的规范bean名称。
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* 将询问父工厂是否在此工厂实例中找不到该bean。
* ======================================================================
* 说人话就是功能和getBean(String)类似 可以将获取的对象转换成特定的类型。如果转换失败会抛出BeanNotOfRequiredTypeException
*
* @param name the name of the bean to retrieve
* @param requiredType type the bean must match; can be an interface or superclass
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there is 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 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.
* 允许指定显式构造函数参数/工厂方法参数,覆盖bean定义中指定的默认参数(如果有)。
* <p>
* ======================================================================
* 说人话:获取bean时可以指定对象属性
*
* @param name the name of the bean to retrieve
* @param args arguments to use when creating a bean instance using explicit arguments
* (only applied when creating a new instance as opposed to retrieving an existing one)
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there is 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;
/**
* Return the bean instance that uniquely matches the given object type, if any.
* 返回唯一匹配给定对象类型的bean实例(如果有)。
* <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}.
* 此方法进入ListableBeanFactory的按类型查找区域,但也可以根据给定类型的名称转换为传统的按名称查找。
* 要跨bean集执行更广泛的检索操作,请使用ListableBeanFactory和/或BeanFactoryUtils
* <p>
* ======================================================================
* 说人话:根据类型获取bean
*
* @param requiredType type the bean must match; can be an interface or superclass
* @return an instance of the single bean matching the required type
* @throws NoSuchBeanDefinitionException if no bean of the given type was found
* @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found
* @throws BeansException if the bean could not be created
* @see ListableBeanFactory
* @since 3.0
*/
<T> T getBean(Class<T> requiredType) throws BeansException;
/**
* Return an instance, which may be shared or independent, of the specified bean.
* 返回指定bean的实例,该实例可以是共享的,也可以是独立的。
*
* <p>Allows for specifying explicit constructor arguments / factory method arguments,
* overriding the specified default arguments (if any) in the bean definition.
* 允许指定显式构造函数参数/工厂方法参数,覆盖bean定义中指定的默认参数(如果有)。
*
* <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.
* 此方法进入ListableBeanFactory的按类型查找区域,但也可以根据给定类型的名称转换为传统的按名称查找。
* <p>
* For more extensive retrieval operations across sets of beans,
* use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}.
* <p>
* 要跨bean集执行更广泛的检索操作,请使用ListableBeanFactory和/或BeanFactoryUtils
* <p>
* ======================================================================
* 说人话:根据类型获取bean,并指定初始化属性
*
* @param requiredType type the bean must match; can be an interface or superclass
* @param args arguments to use when creating a bean instance using explicit arguments
* (only applied when creating a new instance as opposed to retrieving an existing one)
* @return an instance of the bean
* @throws NoSuchBeanDefinitionException if there is 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 4.1
*/
<T> T getBean(Class<T> requiredType, Object... args) throws BeansException;
/**
* Return a provider for the specified bean, allowing for lazy on-demand retrieval
* of instances, including availability and uniqueness options.
* 返回指定bean的提供程序,允许延迟按需检索实例,包括可用性和唯一性选项。
* ======================================================================
* 说人话:获取bean的提供者(对象工厂)根据入参的类型来获取
* requiredType 类型必须匹配 可以是接口或者父类
*
* @param requiredType type the bean must match; can be an interface or superclass
* @return a corresponding provider handle
* @see #getBeanProvider(ResolvableType)
* @since 5.1
*/
<T> ObjectProvider<T> getBeanProvider(Class<T> requiredType);
/**
* Return a provider for the specified bean, allowing for lazy on-demand retrieval
* of instances, including availability and uniqueness options.
* 返回指定bean的提供程序,允许延迟按需检索实例,包括可用性和唯一性选项。
* ======================================================================
* 说人话:获取bean的提供者(对象工厂)根据入参的类型来获取
* <p>
* requiredType 输入bean必须匹配的类型;可以是泛型类型声明。 请注意,与反射注入点相比,此处不支持集合类型。
* 要以编程方式检索与特定类型匹配的bean列表,请在此处指定实际bean类型作为参数,然后使用{@link ObjectProvider#orderedStream()}或其延迟流/迭代选项。
*
* @param requiredType type the bean must match; can be a generic type declaration.
* Note that collection types are not supported here, in contrast to reflective
* injection points. For programmatically retrieving a list of beans matching a
* specific type, specify the actual bean type as an argument here and subsequently
* use {@link ObjectProvider#orderedStream()} or its lazy streaming/iteration options.
* @return a corresponding provider handle
* @see ObjectProvider#iterator()
* @see ObjectProvider#stream()
* @see ObjectProvider#orderedStream()
* @since 5.1
*/
<T> ObjectProvider<T> getBeanProvider(ResolvableType requiredType);
/**
* Does this bean factory contain a bean definition or externally registered singleton
* instance with the given name?
* 这个bean工厂是否包含具有给定名称的bean定义或外部注册的单例实例?
*
* <p>If the given name is an alias, it will be translated back to the corresponding
* canonical bean name.
* 如果给定的名称是别名,它将被翻译回相应的规范bean名称。
*
* <p>If this factory is hierarchical, will ask any parent factory if the bean cannot
* be found in this factory instance.
* 如果此工厂是分层的,则将询问任何父工厂是否在此工厂实例中找不到该bean。
*
* <p>If a bean definition or singleton instance matching the given name is found,
* this method will return {@code true} whether the named bean definition is concrete
* or abstract, lazy or eager, in scope or not.
* 如果找到与给定名称匹配的bean定义或单例实例,无论指定的bean定义是具体的还是抽象的、惰性的还是急切的、范围内的还是非范围内的,
* 此方法都将返回{@code true}。
* <p>
* Therefore, note that a {@code true}
* return value from this method does not necessarily indicate that {@link #getBean}
* will be able to obtain an instance for the same name.
* 因此,请注意,来自此方法的{@code true}返回值并不一定表示{@link#getBean}将能够获得相同名称的实例。
* ======================================================
* 判断是否存在名称为name的bean,这个name也可以是别名。返回true只能表示有名称为name的或者别名为name的bean但并不代表只有一个。
*
* @param name the name of the bean to query
* @return whether a bean with the given name is present
*/
boolean containsBean(String name);
/**
* Is this bean a shared singleton? That is, will {@link #getBean} always
* return the same instance?
* 这个bean是共享的单例吗?也就是说,{@link#getBean}是否总是返回相同的实例?
*
* <p>Note: This method returning {@code false} does not clearly indicate
* independent instances.
* 注意:这个返回{@code false}的方法并没有明确指出独立实例。
* <p>
* 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.
* 它表示非单例实例,也可能对应于作用域bean。使用{@link#isPrototype}操作显式检查独立实例。
*
* <p>Translates aliases back to the corresponding canonical bean name.
* 将别名转换回相应的规范bean名称。
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* 将询问父工厂是否在此工厂实例中找不到该bean。
* <p>
* ===============================================
* 判断是否是单例的, 判断是否是多例的, 大概是返回false不代表一定是多例的,isPrototype 来判断 todo 后面两句现在还不理解
*
* @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;
/**
* Is this bean a prototype? That is, will {@link #getBean} always return
* independent instances?
* 这个bean是共享的多例吗?也就是说,{@link#getBean}是否总是返回相同的实例?
*
* <p>Note: This method returning {@code false} 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.
* 注意:这个返回{@code false}的方法并不能清楚地表示一个单例对象。它表示非独立实例,也可能对应于作用域bean。
* 使用{@link#isSingleton}操作显式检查共享单例实例。
*
* <p>Translates aliases back to the corresponding canonical bean name.
* 将别名转换回相应的规范bean名称。
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* 将询问父工厂是否在此工厂实例中找不到该bean。
* ===============================================
* 判断是否是多例的, 大概是返回false不代表一定是单例的,要结合isSingleton 来判断 todo 后面两句现在还不理解
*
* @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
* @see #getBean
* @see #isSingleton
* @since 2.0.3
*/
boolean isPrototype(String name) throws NoSuchBeanDefinitionException;
/**
* Check whether the bean with the given name matches the specified type.
* 检查具有给定名称的bean是否与指定类型匹配。
* More specifically, check whether a {@link #getBean} call for the given name
* would return an object that is assignable to the specified target type.
* 更具体地说,检查给定名称的{@link#getBean}调用是否会返回可分配给指定目标类型的对象。
*
* <p>Translates aliases back to the corresponding canonical bean name.
* 将别名转换回相应的规范bean名称。
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* 将询问父工厂是否在此工厂实例中找不到该bean。
* =====================================================
* 如上所示。通过 getBean(String) 获取的对象是否是 typeToMatch 给定的对象
*
* @param name the name of the bean to query
* @param typeToMatch the type to match against (as a {@code ResolvableType})
* @return {@code true} if the bean type matches,
* {@code false} if it doesn't match or cannot be determined yet
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @see #getBean
* @see #getType
* @since 4.2
*/
boolean isTypeMatch(String name, ResolvableType typeToMatch) throws NoSuchBeanDefinitionException;
/**
* 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.
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* <p>
* =====================================================
* 和上面的方法作用相同
*
* @param name the name of the bean to query
* @param typeToMatch the type to match against (as a {@code Class})
* @return {@code true} if the bean type matches,
* {@code false} if it doesn't match or cannot be determined yet
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @see #getBean
* @see #getType
* @since 2.0.1
*/
boolean isTypeMatch(String name, Class<?> typeToMatch) throws NoSuchBeanDefinitionException;
/**
* Determine the type of the bean with the given name.
* 确定具有给定名称的bean的类型。
* More specifically,determine the type of object that {@link #getBean} would return for the given name.
* 更具体地说,确定{@link#getBean}将为给定名称返回的对象类型。
* <p>For a {@link FactoryBean},return the type of object that the FactoryBean creates,as exposed by {@link FactoryBean#getObjectType()}.
* 对于{@link FactoryBean},返回FactoryBean创建的对象类型,如{@link FactoryBean#getObjectType()}所示。
* This may lead to the initialization of a previously uninitialized {@code FactoryBean} (see {@link #getType(String, boolean)}).
* 这可能会导致初始化以前未初始化的{@code FactoryBean}(请参见{@link#getType(String,boolean)})。
* <p>Translates aliases back to the corresponding canonical bean name.
* 将别名转换回相应的规范bean名称。
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* 将询问父工厂是否在此工厂实例中找不到该bean。
* <p>
* <p>
* =======================================
* 返回name对应的bean的类型
*
* @param name the name of the bean to query
* @return the type of the bean, or {@code null} if not determinable
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @see #getBean
* @see #isTypeMatch
* @since 1.1.2
*/
@Nullable
Class<?> getType(String name) throws NoSuchBeanDefinitionException;
/**
* 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()}. Depending on the
* {@code allowFactoryBeanInit} flag, this may lead to the initialization of a previously
* uninitialized {@code FactoryBean} if no early type information is available.
* <p>Translates aliases back to the corresponding canonical bean name.
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* =================================================
* 同上 allowFactoryBeanInit:{@code FactoryBean}是否可以仅为了确定其对象类型而初始化
*
* @param name the name of the bean to query
* @param allowFactoryBeanInit whether a {@code FactoryBean} may get initialized
* just for the purpose of determining its object type
* @return the type of the bean, or {@code null} if not determinable
* @throws NoSuchBeanDefinitionException if there is no bean with the given name
* @see #getBean
* @see #isTypeMatch
* @since 5.2
*/
@Nullable
Class<?> getType(String name, boolean allowFactoryBeanInit) throws NoSuchBeanDefinitionException;
/**
* Return the aliases for the given bean name, if any.
* 返回给定bean名称的别名(如果有)。
* <p>All of those aliases point to the same bean when used in a {@link #getBean} call.
* 当在{@link#getBean}调用中使用时,所有这些别名都指向同一个bean。
* <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.
* 如果给定的名称是别名,那么将返回相应的原始bean名称和其他别名(如果有),原始bean名称是数组中的第一个元素。
* <p>Will ask the parent factory if the bean cannot be found in this factory instance.
* 将询问父工厂是否在此工厂实例中找不到该bean。
* ==================================
* 获取别名,返回数组中的第一个名称是原始名称
*
* @param name the bean name to check for aliases
* @return the aliases, or an empty array if none
* @see #getBean
*/
String[] getAliases(String name);
}
BeanFactory[待补充]
最新推荐文章于 2024-06-30 20:23:11 发布