BeanFactory


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  import org.springframework.beans.BeansException;
20  
21  /**
22   * The root interface for accessing a Spring bean container.
23   * This is the basic client view of a bean container;
24   * further interfaces such as {@link ListableBeanFactory} and
25   * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
26   * are available for specific purposes.
27   *
28   * <p>This interface is implemented by objects that hold a number of bean definitions,
29   * each uniquely identified by a String name. Depending on the bean definition,
30   * the factory will return either an independent instance of a contained object
31   * (the Prototype design pattern), or a single shared instance (a superior
32   * alternative to the Singleton design pattern, in which the instance is a
33   * singleton in the scope of the factory). Which type of instance will be returned
34   * depends on the bean factory configuration: the API is the same. Since Spring
35   * 2.0, further scopes are available depending on the concrete application
36   * context (e.g. "request" and "session" scopes in a web environment).
37   *
38   * <p>The point of this approach is that the BeanFactory is a central registry
39   * of application components, and centralizes configuration of application
40   * components (no more do individual objects need to read properties files,
41   * for example). See chapters 4 and 11 of "Expert One-on-One J2EE Design and
42   * Development" for a discussion of the benefits of this approach.
43   *
44   * <p>Note that it is generally better to rely on Dependency Injection
45   * ("push" configuration) to configure application objects through setters
46   * or constructors, rather than use any form of "pull" configuration like a
47   * BeanFactory lookup. Spring's Dependency Injection functionality is
48   * implemented using this BeanFactory interface and its subinterfaces.
49   *
50   * <p>Normally a BeanFactory will load bean definitions stored in a configuration
51   * source (such as an XML document), and use the <code>org.springframework.beans</code>
52   * package to configure the beans. However, an implementation could simply return
53   * Java objects it creates as necessary directly in Java code. There are no
54   * constraints on how the definitions could be stored: LDAP, RDBMS, XML,
55   * properties file, etc. Implementations are encouraged to support references
56   * amongst beans (Dependency Injection).
57   *
58   * <p>In contrast to the methods in {@link ListableBeanFactory}, all of the
59   * operations in this interface will also check parent factories if this is a
60   * {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance,
61   * the immediate parent factory will be asked. Beans in this factory instance
62   * are supposed to override beans of the same name in any parent factory.
63   *
64   * <p>Bean factory implementations should support the standard bean lifecycle interfaces
65   * as far as possible. The full set of initialization methods and their standard order is:<br>
66   * 1. BeanNameAware's <code>setBeanName</code><br>
67   * 2. BeanClassLoaderAware's <code>setBeanClassLoader</code><br>
68   * 3. BeanFactoryAware's <code>setBeanFactory</code><br>
69   * 4. ResourceLoaderAware's <code>setResourceLoader</code>
70   * (only applicable when running in an application context)<br>
71   * 5. ApplicationEventPublisherAware's <code>setApplicationEventPublisher</code>
72   * (only applicable when running in an application context)<br>
73   * 6. MessageSourceAware's <code>setMessageSource</code>
74   * (only applicable when running in an application context)<br>
75   * 7. ApplicationContextAware's <code>setApplicationContext</code>
76   * (only applicable when running in an application context)<br>
77   * 8. ServletContextAware's <code>setServletContext</code>
78   * (only applicable when running in a web application context)<br>
79   * 9. <code>postProcessBeforeInitialization</code> methods of BeanPostProcessors<br>
80   * 10. InitializingBean's <code>afterPropertiesSet</code><br>
81   * 11. a custom init-method definition<br>
82   * 12. <code>postProcessAfterInitialization</code> methods of BeanPostProcessors
83   *
84   * <p>On shutdown of a bean factory, the following lifecycle methods apply:<br>
85   * 1. DisposableBean's <code>destroy</code><br>
86   * 2. a custom destroy-method definition
87   *
88   * @author Rod Johnson
89   * @author Juergen Hoeller
90   * @since 13 April 2001
91   * @see BeanNameAware#setBeanName
92   * @see BeanClassLoaderAware#setBeanClassLoader
93   * @see BeanFactoryAware#setBeanFactory
94   * @see org.springframework.context.ResourceLoaderAware#setResourceLoader
95   * @see org.springframework.context.ApplicationEventPublisherAware#setApplicationEventPublisher
96   * @see org.springframework.context.MessageSourceAware#setMessageSource
97   * @see org.springframework.context.ApplicationContextAware#setApplicationContext
98   * @see org.springframework.web.context.ServletContextAware#setServletContext
99   * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessBeforeInitialization
100  * @see InitializingBean#afterPropertiesSet
101  * @see org.springframework.beans.factory.support.RootBeanDefinition#getInitMethodName
102  * @see org.springframework.beans.factory.config.BeanPostProcessor#postProcessAfterInitialization
103  * @see DisposableBean#destroy
104  * @see org.springframework.beans.factory.support.RootBeanDefinition#getDestroyMethodName
105  */
106 public interface BeanFactory {
107 
108     /**
109      * Used to dereference a {@link FactoryBean} instance and distinguish it from
110      * beans <i>created</i> by the FactoryBean. For example, if the bean named
111      * <code>myJndiObject</code> is a FactoryBean, getting <code>&myJndiObject</code>
112      * will return the factory, not the instance returned by the factory.
113      */
114     String   FACTORY_BEAN_PREFIX = "&";
115 
116 
117     /**
118      * Return an instance, which may be shared or independent, of the specified bean.
119      * <p>This method allows a Spring BeanFactory to be used as a replacement for the
120      * Singleton or Prototype design pattern. Callers may retain references to
121      * returned objects in the case of Singleton beans.
122      * <p>Translates aliases back to the corresponding canonical bean name.
123      * Will ask the parent factory if the bean cannot be found in this factory instance.
124      * @param name the name of the bean to retrieve
125      * @return an instance of the bean
126      * @throws NoSuchBeanDefinitionException if there is no bean definition
127      * with the specified name
128      * @throws BeansException if the bean could not be obtained
129      */
130     Object   getBean(String   name) throws BeansException;
131 
132     /**
133      * Return an instance, which may be shared or independent, of the specified bean.
134      * <p>Behaves the same as {@link #getBean(String)}, but provides a measure of type
135      * safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the
136      * required type. This means that ClassCastException can't be thrown on casting
137      * the result correctly, as can happen with {@link #getBean(String)}.
138      * <p>Translates aliases back to the corresponding canonical bean name.
139      * Will ask the parent factory if the bean cannot be found in this factory instance.
140      * @param name the name of the bean to retrieve
141      * @param requiredType type the bean must match. Can be an interface or superclass
142      * of the actual class, or <code>null</code> for any match. For example, if the value
143      * is <code>Object.class</code>, this method will succeed whatever the class of the
144      * returned instance.
145      * @return an instance of the bean
146      * @throws BeanNotOfRequiredTypeException if the bean is not of the required type
147      * @throws NoSuchBeanDefinitionException if there's no such bean definition
148      * @throws BeansException if the bean could not be created
149      */
150     Object   getBean(String   name, Class   requiredType) throws BeansException;
151 
152     /**
153      * Does this bean factory contain a bean with the given name?
154      * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
155      * @param name the name of the bean to query
156      * @return whether a bean with the given name is defined
157      */
158     boolean containsBean(String   name);
159 
160     /**
161      * Is this bean a shared singleton? That is, will {@link #getBean} always
162      * return the same instance?
163      * <p>Note: This method returning <code>false</code> does not clearly indicate
164      * independent instances. It indicates non-singleton instances, which may correspond
165      * to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly
166      * check for independent instances.
167      * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
168      * @param name the name of the bean to query
169      * @return whether this bean corresponds to a singleton instance
170      * @throws NoSuchBeanDefinitionException if there is no bean with the given name
171      * @see #getBean
172      * @see #isPrototype
173      */
174     boolean isSingleton(String   name) throws NoSuchBeanDefinitionException;
175 
176     /**
177      * Is this bean a prototype? That is, will {@link #getBean} always return
178      * independent instances?
179      * <p>Note: This method returning <code>false</code> does not clearly indicate
180      * a singleton object. It indicates non-independent instances, which may correspond
181      * to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly
182      * check for a shared singleton instance.
183      * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
184      * @param name the name of the bean to query
185      * @return whether this bean will always deliver independent instances
186      * @throws NoSuchBeanDefinitionException if there is no bean with the given name
187      * @since 2.0.3
188      * @see #getBean
189      * @see #isSingleton
190      */
191     boolean isPrototype(String   name) throws NoSuchBeanDefinitionException;
192 
193     /**
194      * Check whether the bean with the given name matches the specified type.
195      * @param name the name of the bean to query
196      * @param targetType the type to match against
197      * @return <code>true</code> if the bean type matches,
198      * <code>false</code> if it doesn't match or cannot be determined yet
199      * @throws NoSuchBeanDefinitionException if there is no bean with the given name
200      * @since 2.0.1
201      * @see #getBean
202      * @see #getType
203      */
204     boolean isTypeMatch(String   name, Class   targetType) throws NoSuchBeanDefinitionException;
205 
206     /**
207      * Determine the type of the bean with the given name. More specifically,
208      * check the type of object that {@link #getBean} would return.
209      * For a FactoryBean, return the type of object that the FactoryBean creates.
210      * @param name the name of the bean to query
211      * @return the type of the bean, or <code>null</code> if not determinable
212      * @throws NoSuchBeanDefinitionException if there is no bean with the given name
213      * @since 1.1.2
214      * @see #getBean
215      * @see FactoryBean#getObjectType()
216      */
217     Class   getType(String   name) throws NoSuchBeanDefinitionException;
218 
219     /**
220      * Return the aliases for the given bean name, if defined.
221      * <p>If the given name is an alias, the corresponding original bean name
222      * and other aliases (if any) will be returned, with the original bean name
223      * being the first element in the array.
224      * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
225      * @param name the bean name to check for aliases
226      * @return the aliases, or an empty array if none
227      */
228     String  [] getAliases(String   name);
229 
230 }
231
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags