Home » Spring-Framework-090522 » org.springframework » beans » factory » [javadoc | source]

    1   /*
    2    * Copyright 2002-2008 the original author or authors.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *      http://www.apache.org/licenses/LICENSE-2.0
    9    *
   10    * Unless required by applicable law or agreed to in writing, software
   11    * distributed under the License is distributed on an "AS IS" BASIS,
   12    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   13    * See the License for the specific language governing permissions and
   14    * limitations under the License.
   15    */
   16   
   17   package org.springframework.beans.factory;
   18   
   19   import java.util.Map;
   20   
   21   import org.springframework.beans.BeansException;
   22   
   23   /**
   24    * Extension of the {@link BeanFactory} interface to be implemented by bean factories
   25    * that can enumerate all their bean instances, rather than attempting bean lookup
   26    * by name one by one as requested by clients. BeanFactory implementations that
   27    * preload all their bean definitions (such as XML-based factories) may implement
   28    * this interface.
   29    *
   30    * <p>If this is a {@link HierarchicalBeanFactory}, the return values will <i>not</i>
   31    * take any BeanFactory hierarchy into account, but will relate only to the beans
   32    * defined in the current factory. Use the {@link BeanFactoryUtils} helper class
   33    * to consider beans in ancestor factories too.
   34    *
   35    * <p>The methods in this interface will just respect bean definitions of this factory.
   36    * They will ignore any singleton beans that have been registered by other means like
   37    * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}'s
   38    * <code>registerSingleton</code> method, with the exception of
   39    * <code>getBeanNamesOfType</code> and <code>getBeansOfType</code> which will check
   40    * such manually registered singletons too. Of course, BeanFactory's <code>getBean</code>
   41    * does allow transparent access to such special beans as well. However, in typical
   42    * scenarios, all beans will be defined by external bean definitions anyway, so most
   43    * applications don't need to worry about this differentation.
   44    *
   45    * <p><b>NOTE:</b> With the exception of <code>getBeanDefinitionCount</code>
   46    * and <code>containsBeanDefinition</code>, the methods in this interface
   47    * are not designed for frequent invocation. Implementations may be slow.
   48    *
   49    * @author Rod Johnson
   50    * @author Juergen Hoeller
   51    * @since 16 April 2001
   52    * @see HierarchicalBeanFactory
   53    * @see BeanFactoryUtils
   54    */
   55   public interface ListableBeanFactory extends BeanFactory {
   56   
   57   	/**
   58   	 * Check if this bean factory contains a bean definition with the given name.
   59   	 * <p>Does not consider any hierarchy this factory may participate in,
   60   	 * and ignores any singleton beans that have been registered by
   61   	 * other means than bean definitions.
   62   	 * @param beanName the name of the bean to look for
   63   	 * @return if this bean factory contains a bean definition with the given name
   64   	 * @see #containsBean
   65   	 */
   66   	boolean containsBeanDefinition(String beanName);
   67   
   68   	/**
   69   	 * Return the number of beans defined in the factory.
   70   	 * <p>Does not consider any hierarchy this factory may participate in,
   71   	 * and ignores any singleton beans that have been registered by
   72   	 * other means than bean definitions.
   73   	 * @return the number of beans defined in the factory
   74   	 */
   75   	int getBeanDefinitionCount();
   76   
   77   	/**
   78   	 * Return the names of all beans defined in this factory.
   79   	 * <p>Does not consider any hierarchy this factory may participate in,
   80   	 * and ignores any singleton beans that have been registered by
   81   	 * other means than bean definitions.
   82   	 * @return the names of all beans defined in this factory,
   83   	 * or an empty array if none defined
   84   	 */
   85   	String[] getBeanDefinitionNames();
   86   	
   87   	/**
   88   	 * Return the names of beans matching the given type (including subclasses),
   89   	 * judging from either bean definitions or the value of <code>getObjectType</code>
   90   	 * in the case of FactoryBeans.
   91   	 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
   92   	 * check nested beans which might match the specified type as well.
   93   	 * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
   94   	 * will get initialized. If the object created by the FactoryBean doesn't match,
   95   	 * the raw FactoryBean itself will be matched against the type.
   96   	 * <p>Does not consider any hierarchy this factory may participate in.
   97   	 * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code>
   98   	 * to include beans in ancestor factories too.
   99   	 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
  100   	 * by other means than bean definitions.
  101   	 * <p>This version of <code>getBeanNamesForType</code> matches all kinds of beans,
  102   	 * be it singletons, prototypes, or FactoryBeans. In most implementations, the
  103   	 * result will be the same as for <code>getBeanNamesOfType(type, true, true)</code>.
  104   	 * <p>Bean names returned by this method should always return bean names <i>in the
  105   	 * order of definition</i> in the backend configuration, as far as possible.
  106   	 * @param type the class or interface to match, or <code>null</code> for all bean names
  107   	 * @return the names of beans (or objects created by FactoryBeans) matching
  108   	 * the given object type (including subclasses), or an empty array if none
  109   	 * @see FactoryBean#getObjectType
  110   	 * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class)
  111   	 */
  112   	String[] getBeanNamesForType(Class type);
  113   
  114   	/**
  115   	 * Return the names of beans matching the given type (including subclasses),
  116   	 * judging from either bean definitions or the value of <code>getObjectType</code>
  117   	 * in the case of FactoryBeans.
  118   	 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
  119   	 * check nested beans which might match the specified type as well.
  120   	 * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
  121   	 * which means that FactoryBeans will get initialized. If the object created by the
  122   	 * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
  123   	 * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
  124   	 * (which doesn't require initialization of each FactoryBean).
  125   $	 * <p>Does not consider any hierarchy this factory may participate in.
  126   	 * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code>
  127   	 * to include beans in ancestor factories too.
  128   	 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
  129   	 * by other means than bean definitions.
  130   	 * <p>Bean names returned by this method should always return bean names <i>in the
  131   	 * order of definition</i> in the backend configuration, as far as possible.
  132   	 * @param type the class or interface to match, or <code>null</code> for all bean names
  133   	 * @param includeNonSingletons whether to include prototype or scoped beans too
  134   	 * or just singletons (also applies to FactoryBeans)
  135   	 * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
  136   	 * <i>objects created by FactoryBeans</i> (or by factory methods with a
  137   	 * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
  138   	 * eagerly initialized to determine their type: So be aware that passing in "true"
  139   	 * for this flag will initialize FactoryBeans and "factory-bean" references.
  140   	 * @return the names of beans (or objects created by FactoryBeans) matching
  141   	 * the given object type (including subclasses), or an empty array if none
  142   	 * @see FactoryBean#getObjectType
  143   	 * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
  144   	 */
  145   	String[] getBeanNamesForType(Class type, boolean includeNonSingletons, boolean allowEagerInit);
  146   
  147   	/**
  148   	 * Return the bean instances that match the given object type (including
  149   	 * subclasses), judging from either bean definitions or the value of
  150   	 * <code>getObjectType</code> in the case of FactoryBeans.
  151   	 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
  152   	 * check nested beans which might match the specified type as well.
  153   	 * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
  154   	 * will get initialized. If the object created by the FactoryBean doesn't match,
  155   	 * the raw FactoryBean itself will be matched against the type.
  156   	 * <p>Does not consider any hierarchy this factory may participate in.
  157   	 * Use BeanFactoryUtils' <code>beansOfTypeIncludingAncestors</code>
  158   	 * to include beans in ancestor factories too.
  159   	 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
  160   	 * by other means than bean definitions.
  161   	 * <p>This version of getBeansOfType matches all kinds of beans, be it
  162   	 * singletons, prototypes, or FactoryBeans. In most implementations, the
  163   	 * result will be the same as for <code>getBeansOfType(type, true, true)</code>.
  164   	 * <p>The Map returned by this method should always return bean names and
  165   	 * corresponding bean instances <i>in the order of definition</i> in the
  166   	 * backend configuration, as far as possible.
  167   	 * @param type the class or interface to match, or <code>null</code> for all concrete beans
  168   	 * @return a Map with the matching beans, containing the bean names as
  169   	 * keys and the corresponding bean instances as values
  170   	 * @throws BeansException if a bean could not be created
  171   	 * @since 1.1.2
  172   	 * @see FactoryBean#getObjectType
  173   	 * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class)
  174   	 */
  175   	Map getBeansOfType(Class type) throws BeansException;
  176   
  177   	/**
  178   	 * Return the bean instances that match the given object type (including
  179   	 * subclasses), judging from either bean definitions or the value of
  180   	 * <code>getObjectType</code> in the case of FactoryBeans.
  181   	 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
  182   	 * check nested beans which might match the specified type as well.
  183   	 * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
  184   	 * which means that FactoryBeans will get initialized. If the object created by the
  185   	 * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
  186   	 * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
  187   	 * (which doesn't require initialization of each FactoryBean).
  188   	 * <p>Does not consider any hierarchy this factory may participate in.
  189   	 * Use BeanFactoryUtils' <code>beansOfTypeIncludingAncestors</code>
  190   	 * to include beans in ancestor factories too.
  191   	 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
  192   	 * by other means than bean definitions.
  193   	 * <p>The Map returned by this method should always return bean names and
  194   	 * corresponding bean instances <i>in the order of definition</i> in the
  195   	 * backend configuration, as far as possible.
  196   	 * @param type the class or interface to match, or <code>null</code> for all concrete beans
  197   	 * @param includeNonSingletons whether to include prototype or scoped beans too
  198   	 * or just singletons (also applies to FactoryBeans)
  199   	 * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
  200   	 * <i>objects created by FactoryBeans</i> (or by factory methods with a
  201   	 * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
  202   	 * eagerly initialized to determine their type: So be aware that passing in "true"
  203   	 * for this flag will initialize FactoryBeans and "factory-bean" references.
  204   	 * @return a Map with the matching beans, containing the bean names as
  205   	 * keys and the corresponding bean instances as values
  206   	 * @throws BeansException if a bean could not be created
  207   	 * @see FactoryBean#getObjectType
  208   	 * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
  209   	 */
  210   	Map getBeansOfType(Class type, boolean includeNonSingletons, boolean allowEagerInit)
  211   	    throws BeansException;
  212   
  213   }

Home » Spring-Framework-090522 » org.springframework » beans » factory » [javadoc | source]