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

    1   /*
    2    * Copyright 2002-2007 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 org.springframework.beans.BeansException;
   20   
   21   /**
   22    * The root interface for accessing a Spring bean container.
   23    * This is the basic client view of a bean container;
   24    * further interfaces such as {@link ListableBeanFactory} and
   25    * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
   26    * are available for specific purposes.
   27    *
   28    * <p>This interface is implemented by objects that hold a number of bean definitions,
   29    * each uniquely identified by a String name. Depending on the bean definition,
   30    * the factory will return either an independent instance of a contained object
   31    * (the Prototype design pattern), or a single shared instance (a superior
   32    * alternative to the Singleton design pattern, in which the instance is a
   33    * singleton in the scope of the factory). Which type of instance will be returned
   34    * depends on the bean factory configuration: the API is the same. Since Spring
   35    * 2.0, further scopes are available depending on the concrete application
   36    * context (e.g. "request" and "session" scopes in a web environment).
   37    *
   38    * <p>The point of this approach is that the BeanFactory is a central registry
   39    * of application components, and centralizes configuration of application
   40    * components (no more do individual objects need to read properties files,
   41    * for example). See chapters 4 and 11 of "Expert One-on-One J2EE Design and
   42    * Development" for a discussion of the benefits of this approach.
   43    *
   44    * <p>Note that it is generally better to rely on Dependency Injection
   45    * ("push" configuration) to configure application objects through setters
   46    * or constructors, rather than use any form of "pull" configuration like a
   47    * BeanFactory lookup. Spring's Dependency Injection functionality is
   48    * implemented using this BeanFactory interface and its subinterfaces.
   49    *
   50    * <p>Normally a BeanFactory will load bean definitions stored in a configuration
   51    * source (such as an XML document), and use the <code>org.springframework.beans</code>
   52    * package to configure the beans. However, an implementation could simply return
   53    * Java objects it creates as necessary directly in Java code. There are no
   54    * constraints on how the definitions could be stored: LDAP, RDBMS, XML,
   55    * properties file, etc. Implementations are encouraged to support references
   56    * amongst beans (Dependency Injection).
   57    *
   58    * <p>In contrast to the methods in {@link ListableBeanFactory}, all of the
   59    * operations in this interface will also check parent factories if this is a
   60    * {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance,
   61    * the immediate parent factory will be asked. Beans in this factory instance
   62    * are supposed to override beans of the same name in any parent factory.
   63    *
   64    * <p>Bean factory implementations should support the standard bean lifecycle interfaces
   65    * as far as possible. The full set of initialization methods and their standard order is:<br>
   66    * 1. BeanNameAware's <code>setBeanName</code><br>
   67    * 2. BeanClassLoaderAware's <code>setBeanClassLoader</code><br>
   68    * 3. BeanFactoryAware's <code>setBeanFactory</code><br>
   69    * 4. ResourceLoaderAware's <code>setResourceLoader</code>
   70    * (only applicable when running in an application context)<br>
   71    * 5. ApplicationEventPublisherAware's <code>setApplicationEventPublisher</code>
   72    * (only applicable when running in an application context)<br>
   73    * 6. MessageSourceAware's <code>setMessageSource</code>
   74    * (only applicable when running in an application context)<br>
   75    * 7. ApplicationContextAware's <code>setApplicationContext</code>
   76    * (only applicable when running in an application context)<br>
   77    * 8. ServletContextAware's <code>setServletContext</code>
   78    * (only applicable when running in a web application context)<br>
   79    * 9. <code>postProcessBeforeInitialization</code> methods of BeanPostProcessors<br>
   80    * 10. InitializingBean's <code>afterPropertiesSet</code><br>
   81    * 11. a custom init-method definition<br>
   82    * 12. <code>postProcessAfterInitialization</code> methods of BeanPostProcessors
   83    *
   84    * <p>On shutdown of a bean factory, the following lifecycle methods apply:<br>
   85    * 1. DisposableBean's <code>destroy</code><br>
   86    * 2. a custom destroy-method definition
   87    *
   88    * @author Rod Johnson
   89    * @author Juergen Hoeller
   90    * @since 13 April 2001
   91    * @see BeanNameAware#setBeanName
   92    * @see BeanClassLoaderAware#setBeanClassLoader
   93    * @see BeanFactoryAware#setBeanFactory
   94    * @see org.springframework.context.ResourceLoaderAware#setResourceLoader
   95    * @see org.springframework.context.ApplicationEventPublisherAware#setApplicationEventPublisher
   96    * @see org.springframework.context.MessageSourceAware#setMessageSource
   97    * @see org.springframework.context.ApplicationContextAware#setApplicationContext
   98    * @see org.springframework.web.context.ServletContextAware#setServletContext
   99    * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessBeforeInitialization
  100    * @see InitializingBean#afterPropertiesSet
  101    * @see org.springframework.beans.factory.support.RootBeanDefinition#getInitMethodName
  102    * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessAfterInitialization
  103    * @see DisposableBean#destroy
  104    * @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName
  105    */
  106   public interface BeanFactory {
  107   
  108   	/**
  109   	 * Used to dereference a {@link FactoryBean} instance and distinguish it from
  110   	 * beans <i>created</i> by the FactoryBean. For example, if the bean named
  111   	 * <code>myJndiObject</code> is a FactoryBean, getting <code>&myJndiObject</code>
  112   	 * will return the factory, not the instance returned by the factory.
  113   	 */
  114   	String FACTORY_BEAN_PREFIX = "&";
  115   
  116   
  117   	/**
  118   	 * Return an instance, which may be shared or independent, of the specified bean.
  119   	 * <p>This method allows a Spring BeanFactory to be used as a replacement for the
  120   	 * Singleton or Prototype design pattern. Callers may retain references to
  121   	 * returned objects in the case of Singleton beans.
  122   	 * <p>Translates aliases back to the corresponding canonical bean name.
  123   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  124   	 * @param name the name of the bean to retrieve
  125   	 * @return an instance of the bean
  126   	 * @throws NoSuchBeanDefinitionException if there is no bean definition
  127   	 * with the specified name
  128   	 * @throws BeansException if the bean could not be obtained
  129   	 */
  130   	Object getBean(String name) throws BeansException;
  131   
  132   	/**
  133   	 * Return an instance, which may be shared or independent, of the specified bean.
  134   	 * <p>Behaves the same as {@link #getBean(String)}, but provides a measure of type
  135   	 * safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the
  136   	 * required type. This means that ClassCastException can't be thrown on casting
  137   	 * the result correctly, as can happen with {@link #getBean(String)}.
  138   	 * <p>Translates aliases back to the corresponding canonical bean name.
  139   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  140   	 * @param name the name of the bean to retrieve
  141   	 * @param requiredType type the bean must match. Can be an interface or superclass
  142   	 * of the actual class, or <code>null</code> for any match. For example, if the value
  143   	 * is <code>Object.class</code>, this method will succeed whatever the class of the
  144   	 * returned instance.
  145   	 * @return an instance of the bean
  146   	 * @throws NoSuchBeanDefinitionException if there's no such bean definition
  147   	 * @throws BeanNotOfRequiredTypeException if the bean is not of the required type
  148   	 * @throws BeansException if the bean could not be created
  149   	 */
  150   	Object getBean(String name, Class requiredType) throws BeansException;
  151   
  152   	/**
  153   	 * Return an instance, which may be shared or independent, of the specified bean.
  154   	 * <p>Allows for specifying explicit constructor arguments / factory method arguments,
  155   	 * overriding the specified default arguments (if any) in the bean definition.
  156   	 * @param name the name of the bean to retrieve
  157   	 * @param args arguments to use if creating a prototype using explicit arguments to a
  158   	 * static factory method. It is invalid to use a non-null args value in any other case.
  159   	 * @return an instance of the bean
  160   	 * @throws NoSuchBeanDefinitionException if there's no such bean definition
  161   	 * @throws BeanDefinitionStoreException if arguments have been given but
  162   	 * the affected bean isn't a prototype
  163   	 * @throws BeansException if the bean could not be created
  164   	 * @since 2.5
  165   	 */
  166   	Object getBean(String name, Object[] args) throws BeansException;
  167   
  168   	/**
  169   	 * Does this bean factory contain a bean with the given name? More specifically,
  170   	 * is {@link #getBean} able to obtain a bean instance for the given name?
  171   	 * <p>Translates aliases back to the corresponding canonical bean name.
  172   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  173   	 * @param name the name of the bean to query
  174   	 * @return whether a bean with the given name is defined
  175   	 */
  176   	boolean containsBean(String name);
  177   
  178   	/**
  179   	 * Is this bean a shared singleton? That is, will {@link #getBean} always
  180   	 * return the same instance?
  181   	 * <p>Note: This method returning <code>false</code> does not clearly indicate
  182   	 * independent instances. It indicates non-singleton instances, which may correspond
  183   	 * to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly
  184   	 * check for independent instances.
  185   	 * <p>Translates aliases back to the corresponding canonical bean name.
  186   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  187   	 * @param name the name of the bean to query
  188   	 * @return whether this bean corresponds to a singleton instance
  189   	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
  190   	 * @see #getBean
  191   	 * @see #isPrototype
  192   	 */
  193   	boolean isSingleton(String name) throws NoSuchBeanDefinitionException;
  194   
  195   	/**
  196   	 * Is this bean a prototype? That is, will {@link #getBean} always return
  197   	 * independent instances?
  198   	 * <p>Note: This method returning <code>false</code> does not clearly indicate
  199   	 * a singleton object. It indicates non-independent instances, which may correspond
  200   	 * to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly
  201   	 * check for a shared singleton instance.
  202   	 * <p>Translates aliases back to the corresponding canonical bean name.
  203   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  204   	 * @param name the name of the bean to query
  205   	 * @return whether this bean will always deliver independent instances
  206   	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
  207   	 * @since 2.0.3
  208   	 * @see #getBean
  209   	 * @see #isSingleton
  210   	 */
  211   	boolean isPrototype(String name) throws NoSuchBeanDefinitionException;
  212   
  213   	/**
  214   	 * Check whether the bean with the given name matches the specified type.
  215   	 * More specifically, check whether a {@link #getBean} call for the given name
  216   	 * would return an object that is assignable to the specified target type.
  217   	 * <p>Translates aliases back to the corresponding canonical bean name.
  218   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  219   	 * @param name the name of the bean to query
  220   	 * @param targetType the type to match against
  221   	 * @return <code>true</code> if the bean type matches,
  222   	 * <code>false</code> if it doesn't match or cannot be determined yet
  223   	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
  224   	 * @since 2.0.1
  225   	 * @see #getBean
  226   	 * @see #getType
  227   	 */
  228   	boolean isTypeMatch(String name, Class targetType) throws NoSuchBeanDefinitionException;
  229   
  230   	/**
  231   	 * Determine the type of the bean with the given name. More specifically,
  232   	 * determine the type of object that {@link #getBean} would return for the given name.
  233   	 * <p>For a {@link FactoryBean}, return the type of object that the FactoryBean creates,
  234   	 * as exposed by {@link FactoryBean#getObjectType()}.
  235   	 * <p>Translates aliases back to the corresponding canonical bean name.
  236   	 * Will ask the parent factory if the bean cannot be found in this factory instance.
  237   	 * @param name the name of the bean to query
  238   	 * @return the type of the bean, or <code>null</code> if not determinable
  239   	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
  240   	 * @since 1.1.2
  241   	 * @see #getBean
  242   	 * @see #isTypeMatch
  243   	 */
  244   	Class getType(String name) throws NoSuchBeanDefinitionException;
  245   
  246   	/**
  247   	 * Return the aliases for the given bean name, if any.
  248   	 * All of those aliases point to the same bean when used in a {@link #getBean} call.
  249   	 * <p>If the given name is an alias, the corresponding original bean name
  250   	 * and other aliases (if any) will be returned, with the original bean name
  251   	 * being the first element in the array.
  252   	 * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
  253   	 * @param name the bean name to check for aliases
  254   	 * @return the aliases, or an empty array if none
  255   	 * @see #getBean
  256   	 */
  257   	String[] getAliases(String name);
  258   
  259   }

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