001/*
002 * Copyright 2002-2020 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 *      https://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
017package org.springframework.beans.factory;
018
019import org.springframework.lang.Nullable;
020
021/**
022 * Interface to be implemented by objects used within a {@link BeanFactory} which
023 * are themselves factories for individual objects. If a bean implements this
024 * interface, it is used as a factory for an object to expose, not directly as a
025 * bean instance that will be exposed itself.
026 *
027 * <p><b>NB: A bean that implements this interface cannot be used as a normal bean.</b>
028 * A FactoryBean is defined in a bean style, but the object exposed for bean
029 * references ({@link #getObject()}) is always the object that it creates.
030 *
031 * <p>FactoryBeans can support singletons and prototypes, and can either create
032 * objects lazily on demand or eagerly on startup. The {@link SmartFactoryBean}
033 * interface allows for exposing more fine-grained behavioral metadata.
034 *
035 * <p>This interface is heavily used within the framework itself, for example for
036 * the AOP {@link org.springframework.aop.framework.ProxyFactoryBean} or the
037 * {@link org.springframework.jndi.JndiObjectFactoryBean}. It can be used for
038 * custom components as well; however, this is only common for infrastructure code.
039 *
040 * <p><b>{@code FactoryBean} is a programmatic contract. Implementations are not
041 * supposed to rely on annotation-driven injection or other reflective facilities.</b>
042 * {@link #getObjectType()} {@link #getObject()} invocations may arrive early in the
043 * bootstrap process, even ahead of any post-processor setup. If you need access to
044 * other beans, implement {@link BeanFactoryAware} and obtain them programmatically.
045 *
046 * <p><b>The container is only responsible for managing the lifecycle of the FactoryBean
047 * instance, not the lifecycle of the objects created by the FactoryBean.</b> Therefore,
048 * a destroy method on an exposed bean object (such as {@link java.io.Closeable#close()}
049 * will <i>not</i> be called automatically. Instead, a FactoryBean should implement
050 * {@link DisposableBean} and delegate any such close call to the underlying object.
051 *
052 * <p>Finally, FactoryBean objects participate in the containing BeanFactory's
053 * synchronization of bean creation. There is usually no need for internal
054 * synchronization other than for purposes of lazy initialization within the
055 * FactoryBean itself (or the like).
056 *
057 * @author Rod Johnson
058 * @author Juergen Hoeller
059 * @since 08.03.2003
060 * @param <T> the bean type
061 * @see org.springframework.beans.factory.BeanFactory
062 * @see org.springframework.aop.framework.ProxyFactoryBean
063 * @see org.springframework.jndi.JndiObjectFactoryBean
064 */
065public interface FactoryBean<T> {
066
067        /**
068         * The name of an attribute that can be
069         * {@link org.springframework.core.AttributeAccessor#setAttribute set} on a
070         * {@link org.springframework.beans.factory.config.BeanDefinition} so that
071         * factory beans can signal their object type when it can't be deduced from
072         * the factory bean class.
073         * @since 5.2
074         */
075        String OBJECT_TYPE_ATTRIBUTE = "factoryBeanObjectType";
076
077
078        /**
079         * Return an instance (possibly shared or independent) of the object
080         * managed by this factory.
081         * <p>As with a {@link BeanFactory}, this allows support for both the
082         * Singleton and Prototype design pattern.
083         * <p>If this FactoryBean is not fully initialized yet at the time of
084         * the call (for example because it is involved in a circular reference),
085         * throw a corresponding {@link FactoryBeanNotInitializedException}.
086         * <p>As of Spring 2.0, FactoryBeans are allowed to return {@code null}
087         * objects. The factory will consider this as normal value to be used; it
088         * will not throw a FactoryBeanNotInitializedException in this case anymore.
089         * FactoryBean implementations are encouraged to throw
090         * FactoryBeanNotInitializedException themselves now, as appropriate.
091         * @return an instance of the bean (can be {@code null})
092         * @throws Exception in case of creation errors
093         * @see FactoryBeanNotInitializedException
094         */
095        @Nullable
096        T getObject() throws Exception;
097
098        /**
099         * Return the type of object that this FactoryBean creates,
100         * or {@code null} if not known in advance.
101         * <p>This allows one to check for specific types of beans without
102         * instantiating objects, for example on autowiring.
103         * <p>In the case of implementations that are creating a singleton object,
104         * this method should try to avoid singleton creation as far as possible;
105         * it should rather estimate the type in advance.
106         * For prototypes, returning a meaningful type here is advisable too.
107         * <p>This method can be called <i>before</i> this FactoryBean has
108         * been fully initialized. It must not rely on state created during
109         * initialization; of course, it can still use such state if available.
110         * <p><b>NOTE:</b> Autowiring will simply ignore FactoryBeans that return
111         * {@code null} here. Therefore it is highly recommended to implement
112         * this method properly, using the current state of the FactoryBean.
113         * @return the type of object that this FactoryBean creates,
114         * or {@code null} if not known at the time of the call
115         * @see ListableBeanFactory#getBeansOfType
116         */
117        @Nullable
118        Class<?> getObjectType();
119
120        /**
121         * Is the object managed by this factory a singleton? That is,
122         * will {@link #getObject()} always return the same object
123         * (a reference that can be cached)?
124         * <p><b>NOTE:</b> If a FactoryBean indicates to hold a singleton object,
125         * the object returned from {@code getObject()} might get cached
126         * by the owning BeanFactory. Hence, do not return {@code true}
127         * unless the FactoryBean always exposes the same reference.
128         * <p>The singleton status of the FactoryBean itself will generally
129         * be provided by the owning BeanFactory; usually, it has to be
130         * defined as singleton there.
131         * <p><b>NOTE:</b> This method returning {@code false} does not
132         * necessarily indicate that returned objects are independent instances.
133         * An implementation of the extended {@link SmartFactoryBean} interface
134         * may explicitly indicate independent instances through its
135         * {@link SmartFactoryBean#isPrototype()} method. Plain {@link FactoryBean}
136         * implementations which do not implement this extended interface are
137         * simply assumed to always return independent instances if the
138         * {@code isSingleton()} implementation returns {@code false}.
139         * <p>The default implementation returns {@code true}, since a
140         * {@code FactoryBean} typically manages a singleton instance.
141         * @return whether the exposed object is a singleton
142         * @see #getObject()
143         * @see SmartFactoryBean#isPrototype()
144         */
145        default boolean isSingleton() {
146                return true;
147        }
148
149}