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}