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 is always the object that it creates.
028: *
029: * <p>FactoryBeans can support singletons and prototypes, and can
030: * either create objects lazily on demand or eagerly on startup.
031: *
032: * <p>This interface is heavily used within the framework itself, for
033: * example for the AOP {@link org.springframework.aop.framework.ProxyFactoryBean}
034: * or the {@link org.springframework.jndi.JndiObjectFactoryBean}.
035: * It can be used for application components as well; however,
036: * this is not common outside of infrastructure code.
037: *
038: * @author Rod Johnson
039: * @author Juergen Hoeller
040: * @since 08.03.2003
041: * @see org.springframework.beans.factory.BeanFactory
042: * @see org.springframework.aop.framework.ProxyFactoryBean
043: * @see org.springframework.jndi.JndiObjectFactoryBean
044: */
045: public interface FactoryBean {
046:
047: /**
048: * Return an instance (possibly shared or independent) of the object
049: * managed by this factory.
050: * <p>As with a {@link BeanFactory}, this allows support for both the
051: * Singleton and Prototype design pattern.
052: * <p>If this FactoryBean is not fully initialized yet at the time of
053: * the call (for example because it is involved in a circular reference),
054: * throw a corresponding {@link FactoryBeanNotInitializedException}.
055: * <p>As of Spring 2.0, FactoryBeans are allowed to return <code>null</code>
056: * objects. The factory will consider this as normal value to be used; it
057: * will not throw a FactoryBeanNotInitializedException in this case anymore.
058: * FactoryBean implementations are encouraged to throw
059: * FactoryBeanNotInitializedException themselves now, as appropriate.
060: * @return an instance of the bean (can be <code>null</code>)
061: * @throws Exception in case of creation errors
062: * @see FactoryBeanNotInitializedException
063: */
064: Object getObject() throws Exception;
065:
066: /**
067: * Return the type of object that this FactoryBean creates,
068: * or <code>null</code> if not known in advance.
069: * <p>This allows one to check for specific types of beans without
070: * instantiating objects, for example on autowiring.
071: * <p>In the case of implementations that are creating a singleton object,
072: * this method should try to avoid singleton creation as far as possible;
073: * it should rather estimate the type in advance.
074: * For prototypes, returning a meaningful type here is advisable too.
075: * <p>This method can be called <i>before</i> this FactoryBean has
076: * been fully initialized. It must not rely on state created during
077: * initialization; of course, it can still use such state if available.
078: * <p><b>NOTE:</b> Autowiring will simply ignore FactoryBeans that return
079: * <code>null</code> here. Therefore it is highly recommended to implement
080: * this method properly, using the current state of the FactoryBean.
081: * @return the type of object that this FactoryBean creates,
082: * or <code>null</code> if not known at the time of the call
083: * @see ListableBeanFactory#getBeansOfType
084: */
085: Class getObjectType();
086:
087: /**
088: * Is the object managed by this factory a singleton? That is,
089: * will {@link #getObject()} always return the same object
090: * (a reference that can be cached)?
091: * <p><b>NOTE:</b> If a FactoryBean indicates to hold a singleton object,
092: * the object returned from <code>getObject()</code> might get cached
093: * by the owning BeanFactory. Hence, do not return <code>true</code>
094: * unless the FactoryBean always exposes the same reference.
095: * <p>The singleton status of the FactoryBean itself will generally
096: * be provided by the owning BeanFactory; usually, it has to be
097: * defined as singleton there.
098: * <p><b>NOTE:</b> This method returning <code>false</code> does not
099: * necessarily indicate that returned objects are independent instances.
100: * An implementation of the extended {@link SmartFactoryBean} interface
101: * may explicitly indicate independent instances through its
102: * {@link SmartFactoryBean#isPrototype()} method. Plain {@link FactoryBean}
103: * implementations which do not implement this extended interface are
104: * simply assumed to always return independent instances if the
105: * <code>isSingleton()</code> implementation returns <code>false</code>.
106: * @return if the exposed object is a singleton
107: * @see #getObject()
108: * @see SmartFactoryBean#isPrototype()
109: */
110: boolean isSingleton();
111:
112: }
|