FactoryBean


1   /*
2    * Copyright 2002-2007 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.beans.factory;
18  
19  /**
20   * Interface to be implemented by objects used within a {@link BeanFactory}
21   * which are themselves factories. If a bean implements this interface,
22   * it is used as a factory for an object to expose, not directly as a bean
23   * instance that will be exposed itself.
24   *
25   * <p><b>NB: A bean that implements this interface cannot be used as a
26   * normal bean.</b> A FactoryBean is defined in a bean style, but the
27   * object exposed for bean references is always the object that it creates.
28   *
29   * <p>FactoryBeans can support singletons and prototypes, and can
30   * either create objects lazily on demand or eagerly on startup.
31   *
32   * <p>This interface is heavily used within the framework itself, for
33   * example for the AOP {@link org.springframework.aop.framework.ProxyFactoryBean}
34   * or the {@link org.springframework.jndi.JndiObjectFactoryBean}.
35   * It can be used for application components as well; however,
36   * this is not common outside of infrastructure code.
37   *
38   * @author Rod Johnson
39   * @author Juergen Hoeller
40   * @since 08.03.2003
41   * @see org.springframework.beans.factory.BeanFactory
42   * @see org.springframework.aop.framework.ProxyFactoryBean
43   * @see org.springframework.jndi.JndiObjectFactoryBean
44   */
45  public interface FactoryBean {
46  
47      /**
48       * Return an instance (possibly shared or independent) of the object
49       * managed by this factory.
50       * <p>As with a {@link BeanFactory}, this allows support for both the
51       * Singleton and Prototype design pattern.
52       * <p>If this FactoryBean is not fully initialized yet at the time of
53       * the call (for example because it is involved in a circular reference),
54       * throw a corresponding {@link FactoryBeanNotInitializedException}.
55       * <p>As of Spring 2.0, FactoryBeans are allowed to return <code>null</code>
56       * objects. The factory will consider this as normal value to be used; it
57       * will not throw a FactoryBeanNotInitializedException in this case anymore.
58       * FactoryBean implementations are encouraged to throw
59       * FactoryBeanNotInitializedException themselves now, as appropriate.
60       * @return an instance of the bean (can be <code>null</code>)
61       * @throws Exception in case of creation errors
62       * @see FactoryBeanNotInitializedException
63       */
64      Object   getObject() throws Exception  ;
65  
66      /**
67       * Return the type of object that this FactoryBean creates,
68       * or <code>null</code> if not known in advance.
69       * <p>This allows one to check for specific types of beans without
70       * instantiating objects, for example on autowiring.
71       * <p>In the case of implementations that are creating a singleton object,
72       * this method should try to avoid singleton creation as far as possible;
73       * it should rather estimate the type in advance.
74       * For prototypes, returning a meaningful type here is advisable too.
75       * <p>This method can be called <i>before</i> this FactoryBean has
76       * been fully initialized. It must not rely on state created during
77       * initialization; of course, it can still use such state if available.
78       * <p><b>NOTE:</b> Autowiring will simply ignore FactoryBeans that return
79       * <code>null</code> here. Therefore it is highly recommended to implement
80       * this method properly, using the current state of the FactoryBean.
81       * @return the type of object that this FactoryBean creates,
82       * or <code>null</code> if not known at the time of the call
83       * @see ListableBeanFactory#getBeansOfType
84       */
85      Class   getObjectType();
86  
87      /**
88       * Is the object managed by this factory a singleton? That is,
89       * will {@link #getObject()} always return the same object
90       * (a reference that can be cached)?
91       * <p><b>NOTE:</b> If a FactoryBean indicates to hold a singleton object,
92       * the object returned from <code>getObject()</code> might get cached
93       * by the owning BeanFactory. Hence, do not return <code>true</code>
94       * unless the FactoryBean always exposes the same reference.
95       * <p>The singleton status of the FactoryBean itself will generally
96       * be provided by the owning BeanFactory; usually, it has to be
97       * defined as singleton there.
98       * <p><b>NOTE:</b> This method returning <code>false</code> does not
99       * 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 }
113
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags