package org.springframework.beans.factory;

/**

 * 该接口是对BeanFactory的扩展，允许预加载bean定义的BeanFactory可以实现此接口

 * 其目的在于使实现它的BeanFactory能够枚举所有的Bean

 * 该接口不支持分层结构（对于继承了HierarchicalBeanFactory的BeanFactory来说）

 * 也即该接口只能枚举当前facotry的Bean

 * 除getBeanNamesOfType，getBeansOfType方法外，其他方法也将忽略由SingletonBeanRegistry的方法

 * 注册的Singleton Bean

 * 除getBeanDefinitionCount和containsBeanDefinition外的方法不要频繁使用，性能很慢

 */

public interface ListableBeanFactory extends BeanFactory {

    /**

     * 根据给出的BeanName判断是否包含该Bean定义

     * 该接口不支持分层结构（对于继承了HierarchicalBeanFactory的BeanFactory来说）

     * 也即该接口只能枚举当前facotry的Bean 忽略由SingletonBeanRegistry的方法 注册的Singleton Bean

     */

    boolean containsBeanDefinition(String beanName);

    /**

     * 返回Bean定义的数目 该接口不支持分层结构（对于继承了HierarchicalBeanFactory的BeanFactory来说）

     * 也即该接口只能枚举当前facotry的Bean 忽略由SingletonBeanRegistry的方法 注册的Singleton Bean

     */

    int getBeanDefinitionCount();

    /**

     * 返回所有Bean的BeanName组成的String数组

     */

    String[] getBeanDefinitionNames();

    /**

     * 根据提供的类型返回匹配的BeanName数组 只检测顶层Bean，忽略嵌套Bean

     * 对于FactoryBean，当提供的类型匹配FactoryBean.getObjectType时返回BeanName

     * 当提供的类型匹配FactoryBean时返回&BeanName

     * 该接口不支持分层结构（对于继承了HierarchicalBeanFactory的BeanFactory来说）

     * 也即该接口只能枚举当前facotry的Bean 不忽略由SingletonBeanRegistry的方法时注册的Singleton Bean

     * 不检测无法实例化的Bean(如抽象Bean)

     */

    String[] getBeanNamesForType(ResolvableType type);

    /**

     * 同上 String[] getBeanNamesForType(@Nullable Class<?> type);

     *

     * /** 作用同上 includeNonSingletons：判断是否匹配除Singleton外的其他scope allowEagerInit:

     * false只匹配FactoryBean本身，true时还匹配FactoryBean.getObjectType()

     */

    String[] getBeanNamesForType(@Nullable Class<?> type, boolean includeNonSingletons, boolean allowEagerInit);

    /**

     * 根据提供的类型返回匹配的Bean实例数组 只检测顶层Bean，忽略嵌套Bean

     * 对于FactoryBean，当提供的类型匹配FactoryBean.getObjectType时返回BeanName

     * 当提供的类型匹配FactoryBean时返回&BeanName

     * 该接口不支持分层结构（对于继承了HierarchicalBeanFactory的BeanFactory来说）

     * 也即该接口只能枚举当前facotry的Bean 不忽略由SingletonBeanRegistry的方法时注册的Singleton Bean

     * 不检测无法实例化的Bean(如抽象Bean)

     */

    <T> Map<String, T> getBeansOfType(@Nullable Class<T> type) throws BeansException;

    /**

     * 作用同上 includeNonSingletons：判断是否匹配除Singleton外的其他scope allowEagerInit:

     * false只匹配FactoryBean本身，true时还匹配FactoryBean.getObjectType()

     */

    <T> Map<String, T> getBeansOfType(@Nullable Class<T> type, boolean includeNonSingletons, boolean allowEagerInit)

            throws BeansException;

    /**

     * 根据提供的注解类型找到对于的BeanName数组， 不创建实例， 但FactoryBean类型将被初始化，因为该方法考虑FactoryBean创建的对象

     */

    String[] getBeanNamesForAnnotation(Class<? extends Annotation> annotationType);

    /**

     * 根据提供的注解类型找到对于的Bean实例数组， FactoryBean类型将被初始化，因为该方法考虑FactoryBean创建的对象

     */

    Map<String, Object> getBeansWithAnnotation(Class<? extends Annotation> annotationType) throws BeansException;

    /**

     * 根据提供的注解类型和beanNaeme找到对应的Bean，Bean的类类型本身找不到，则遍历它的 接口和超类

     * 如果不存在该Bean，则抛出NoSuchBeanDefinitionException 如果该Bean不支持该注解类型则返回null

     */

    @Nullable

    <A extends Annotation> A findAnnotationOnBean(String beanName, Class<A> annotationType)

            throws NoSuchBeanDefinitionException;

}