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   /**
   20    * Interface to be implemented by objects used within a {@link BeanFactory}
   21    * which are themselves factories. If a bean implements this interface,
   22    * it is used as a factory for an object to expose, not directly as a bean
   23    * instance that will be exposed itself.
   24    *
   25    * <p><b>NB: A bean that implements this interface cannot be used as a
   26    * normal bean.</b> A FactoryBean is defined in a bean style, but the
   27    * object exposed for bean references ({@link #getObject()} is always
   28    * the object that it creates.
   29    *
   30    * <p>FactoryBeans can support singletons and prototypes, and can
   31    * either create objects lazily on demand or eagerly on startup.
   32    * The {@link SmartFactoryBean} interface allows for exposing
   33    * more fine-grained behavioral metadata.
   34    *
   35    * <p>This interface is heavily used within the framework itself, for
   36    * example for the AOP {@link org.springframework.aop.framework.ProxyFactoryBean}
   37    * or the {@link org.springframework.jndi.JndiObjectFactoryBean}.
   38    * It can be used for application components as well; however,
   39    * this is not common outside of infrastructure code.
   40    *
   41    * <p><b>NOTE:</b> FactoryBean objects participate in the containing
   42    * BeanFactory's synchronization of bean creation. There is usually no
   43    * need for internal synchronization other than for purposes of lazy
   44    * initialization within the FactoryBean itself (or the like).
   45    *
   46    * @author Rod Johnson
   47    * @author Juergen Hoeller
   48    * @since 08.03.2003
   49    * @see org.springframework.beans.factory.BeanFactory
   50    * @see org.springframework.aop.framework.ProxyFactoryBean
   51    * @see org.springframework.jndi.JndiObjectFactoryBean
   52    */
   53   public interface FactoryBean {
   54   
   55   	/**
   56   	 * Return an instance (possibly shared or independent) of the object
   57   	 * managed by this factory.
   58   	 * <p>As with a {@link BeanFactory}, this allows support for both the
   59   	 * Singleton and Prototype design pattern.
   60   	 * <p>If this FactoryBean is not fully initialized yet at the time of
   61   	 * the call (for example because it is involved in a circular reference),
   62   	 * throw a corresponding {@link FactoryBeanNotInitializedException}.
   63   	 * <p>As of Spring 2.0, FactoryBeans are allowed to return <code>null</code>
   64   	 * objects. The factory will consider this as normal value to be used; it
   65   	 * will not throw a FactoryBeanNotInitializedException in this case anymore.
   66   	 * FactoryBean implementations are encouraged to throw
   67   	 * FactoryBeanNotInitializedException themselves now, as appropriate.
   68   	 * @return an instance of the bean (can be <code>null</code>)
   69   	 * @throws Exception in case of creation errors
   70   	 * @see FactoryBeanNotInitializedException
   71   	 */
   72   	Object getObject() throws Exception;
   73   
   74   	/**
   75   	 * Return the type of object that this FactoryBean creates,
   76   	 * or <code>null</code> if not known in advance.
   77   	 * <p>This allows one to check for specific types of beans without
   78   	 * instantiating objects, for example on autowiring.
   79   	 * <p>In the case of implementations that are creating a singleton object,
   80   	 * this method should try to avoid singleton creation as far as possible;
   81   	 * it should rather estimate the type in advance.
   82   	 * For prototypes, returning a meaningful type here is advisable too.
   83   	 * <p>This method can be called <i>before</i> this FactoryBean has
   84   	 * been fully initialized. It must not rely on state created during
   85   	 * initialization; of course, it can still use such state if available.
   86   	 * <p><b>NOTE:</b> Autowiring will simply ignore FactoryBeans that return
   87   	 * <code>null</code> here. Therefore it is highly recommended to implement
   88   	 * this method properly, using the current state of the FactoryBean.
   89   	 * @return the type of object that this FactoryBean creates,
   90   	 * or <code>null</code> if not known at the time of the call
   91   	 * @see ListableBeanFactory#getBeansOfType
   92   	 */
   93   	Class getObjectType();
   94   
   95   	/**
   96   	 * Is the object managed by this factory a singleton? That is,
   97   	 * will {@link #getObject()} always return the same object
   98   	 * (a reference that can be cached)?
   99   	 * <p><b>NOTE:</b> If a FactoryBean indicates to hold a singleton object,
  100   	 * the object returned from <code>getObject()</code> might get cached
  101   	 * by the owning BeanFactory. Hence, do not return <code>true</code>
  102   	 * unless the FactoryBean always exposes the same reference.
  103   	 * <p>The singleton status of the FactoryBean itself will generally
  104   	 * be provided by the owning BeanFactory; usually, it has to be
  105   	 * defined as singleton there.
  106   	 * <p><b>NOTE:</b> This method returning <code>false</code> does not
  107   	 * necessarily indicate that returned objects are independent instances.
  108   	 * An implementation of the extended {@link SmartFactoryBean} interface
  109   	 * may explicitly indicate independent instances through its
  110   	 * {@link SmartFactoryBean#isPrototype()} method. Plain {@link FactoryBean}
  111   	 * implementations which do not implement this extended interface are
  112   	 * simply assumed to always return independent instances if the
  113   	 * <code>isSingleton()</code> implementation returns <code>false</code>.
  114   	 * @return whether the exposed object is a singleton
  115   	 * @see #getObject()
  116   	 * @see SmartFactoryBean#isPrototype()
  117   	 */
  118   	boolean isSingleton();
  119   
  120   }

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