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