KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > beans > factory > 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 JavaDoc 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 JavaDoc getBean(String JavaDoc 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 JavaDoc getBean(String JavaDoc name, Class JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc name, Class JavaDoc 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 JavaDoc getType(String JavaDoc 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 JavaDoc[] getAliases(String JavaDoc name);
229
230 }
231
Popular Tags