001: /*
002: * Copyright 2002-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.beans.factory;
018:
019: /**
020: * Interface to be implemented by objects used within a {@link BeanFactory}
021: * which are themselves factories. If a bean implements this interface,
022: * it is used as a factory for an object to expose, not directly as a bean
023: * instance that will be exposed itself.
024: *
025: * <p><b>NB: A bean that implements this interface cannot be used as a
026: * normal bean.</b> A FactoryBean is defined in a bean style, but the
027: * object exposed for bean references ({@link #getObject()} is always
028: * the object that it creates.
029: *
030: * <p>FactoryBeans can support singletons and prototypes, and can
031: * either create objects lazily on demand or eagerly on startup.
032: * The {@link SmartFactoryBean} interface allows for exposing
033: * more fine-grained behavioral metadata.
034: *
035: * <p>This interface is heavily used within the framework itself, for
036: * example for the AOP {@link org.springframework.aop.framework.ProxyFactoryBean}
037: * or the {@link org.springframework.jndi.JndiObjectFactoryBean}.
038: * It can be used for application components as well; however,
039: * this is not common outside of infrastructure code.
040: *
041: * @author Rod Johnson
042: * @author Juergen Hoeller
043: * @since 08.03.2003
044: * @see org.springframework.beans.factory.BeanFactory
045: * @see org.springframework.aop.framework.ProxyFactoryBean
046: * @see org.springframework.jndi.JndiObjectFactoryBean
047: */
048: public interface FactoryBean {
049:
050: /**
051: * Return an instance (possibly shared or independent) of the object
052: * managed by this factory.
053: * <p>As with a {@link BeanFactory}, this allows support for both the
054: * Singleton and Prototype design pattern.
055: * <p>If this FactoryBean is not fully initialized yet at the time of
056: * the call (for example because it is involved in a circular reference),
057: * throw a corresponding {@link FactoryBeanNotInitializedException}.
058: * <p>As of Spring 2.0, FactoryBeans are allowed to return <code>null</code>
059: * objects. The factory will consider this as normal value to be used; it
060: * will not throw a FactoryBeanNotInitializedException in this case anymore.
061: * FactoryBean implementations are encouraged to throw
062: * FactoryBeanNotInitializedException themselves now, as appropriate.
063: * @return an instance of the bean (can be <code>null</code>)
064: * @throws Exception in case of creation errors
065: * @see FactoryBeanNotInitializedException
066: */
067: Object getObject() throws Exception;
068:
069: /**
070: * Return the type of object that this FactoryBean creates,
071: * or <code>null</code> if not known in advance.
072: * <p>This allows one to check for specific types of beans without
073: * instantiating objects, for example on autowiring.
074: * <p>In the case of implementations that are creating a singleton object,
075: * this method should try to avoid singleton creation as far as possible;
076: * it should rather estimate the type in advance.
077: * For prototypes, returning a meaningful type here is advisable too.
078: * <p>This method can be called <i>before</i> this FactoryBean has
079: * been fully initialized. It must not rely on state created during
080: * initialization; of course, it can still use such state if available.
081: * <p><b>NOTE:</b> Autowiring will simply ignore FactoryBeans that return
082: * <code>null</code> here. Therefore it is highly recommended to implement
083: * this method properly, using the current state of the FactoryBean.
084: * @return the type of object that this FactoryBean creates,
085: * or <code>null</code> if not known at the time of the call
086: * @see ListableBeanFactory#getBeansOfType
087: */
088: Class getObjectType();
089:
090: /**
091: * Is the object managed by this factory a singleton? That is,
092: * will {@link #getObject()} always return the same object
093: * (a reference that can be cached)?
094: * <p><b>NOTE:</b> If a FactoryBean indicates to hold a singleton object,
095: * the object returned from <code>getObject()</code> might get cached
096: * by the owning BeanFactory. Hence, do not return <code>true</code>
097: * unless the FactoryBean always exposes the same reference.
098: * <p>The singleton status of the FactoryBean itself will generally
099: * be provided by the owning BeanFactory; usually, it has to be
100: * defined as singleton there.
101: * <p><b>NOTE:</b> This method returning <code>false</code> does not
102: * necessarily indicate that returned objects are independent instances.
103: * An implementation of the extended {@link SmartFactoryBean} interface
104: * may explicitly indicate independent instances through its
105: * {@link SmartFactoryBean#isPrototype()} method. Plain {@link FactoryBean}
106: * implementations which do not implement this extended interface are
107: * simply assumed to always return independent instances if the
108: * <code>isSingleton()</code> implementation returns <code>false</code>.
109: * @return whether the exposed object is a singleton
110: * @see #getObject()
111: * @see SmartFactoryBean#isPrototype()
112: */
113: boolean isSingleton();
114:
115: }
|