001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.beans.factory;
018:
019: import org.springframework.beans.BeansException;
020:
021: /**
022: * The root interface for accessing a Spring bean container.
023: * This is the basic client view of a bean container;
024: * further interfaces such as {@link ListableBeanFactory} and
025: * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}
026: * are available for specific purposes.
027: *
028: * <p>This interface is implemented by objects that hold a number of bean definitions,
029: * each uniquely identified by a String name. Depending on the bean definition,
030: * the factory will return either an independent instance of a contained object
031: * (the Prototype design pattern), or a single shared instance (a superior
032: * alternative to the Singleton design pattern, in which the instance is a
033: * singleton in the scope of the factory). Which type of instance will be returned
034: * depends on the bean factory configuration: the API is the same. Since Spring
035: * 2.0, further scopes are available depending on the concrete application
036: * context (e.g. "request" and "session" scopes in a web environment).
037: *
038: * <p>The point of this approach is that the BeanFactory is a central registry
039: * of application components, and centralizes configuration of application
040: * components (no more do individual objects need to read properties files,
041: * for example). See chapters 4 and 11 of "Expert One-on-One J2EE Design and
042: * Development" for a discussion of the benefits of this approach.
043: *
044: * <p>Note that it is generally better to rely on Dependency Injection
045: * ("push" configuration) to configure application objects through setters
046: * or constructors, rather than use any form of "pull" configuration like a
047: * BeanFactory lookup. Spring's Dependency Injection functionality is
048: * implemented using this BeanFactory interface and its subinterfaces.
049: *
050: * <p>Normally a BeanFactory will load bean definitions stored in a configuration
051: * source (such as an XML document), and use the <code>org.springframework.beans</code>
052: * package to configure the beans. However, an implementation could simply return
053: * Java objects it creates as necessary directly in Java code. There are no
054: * constraints on how the definitions could be stored: LDAP, RDBMS, XML,
055: * properties file, etc. Implementations are encouraged to support references
056: * amongst beans (Dependency Injection).
057: *
058: * <p>In contrast to the methods in {@link ListableBeanFactory}, all of the
059: * operations in this interface will also check parent factories if this is a
060: * {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance,
061: * the immediate parent factory will be asked. Beans in this factory instance
062: * are supposed to override beans of the same name in any parent factory.
063: *
064: * <p>Bean factory implementations should support the standard bean lifecycle interfaces
065: * as far as possible. The full set of initialization methods and their standard order is:<br>
066: * 1. BeanNameAware's <code>setBeanName</code><br>
067: * 2. BeanClassLoaderAware's <code>setBeanClassLoader</code><br>
068: * 3. BeanFactoryAware's <code>setBeanFactory</code><br>
069: * 4. ResourceLoaderAware's <code>setResourceLoader</code>
070: * (only applicable when running in an application context)<br>
071: * 5. ApplicationEventPublisherAware's <code>setApplicationEventPublisher</code>
072: * (only applicable when running in an application context)<br>
073: * 6. MessageSourceAware's <code>setMessageSource</code>
074: * (only applicable when running in an application context)<br>
075: * 7. ApplicationContextAware's <code>setApplicationContext</code>
076: * (only applicable when running in an application context)<br>
077: * 8. ServletContextAware's <code>setServletContext</code>
078: * (only applicable when running in a web application context)<br>
079: * 9. <code>postProcessBeforeInitialization</code> methods of BeanPostProcessors<br>
080: * 10. InitializingBean's <code>afterPropertiesSet</code><br>
081: * 11. a custom init-method definition<br>
082: * 12. <code>postProcessAfterInitialization</code> methods of BeanPostProcessors
083: *
084: * <p>On shutdown of a bean factory, the following lifecycle methods apply:<br>
085: * 1. DisposableBean's <code>destroy</code><br>
086: * 2. a custom destroy-method definition
087: *
088: * @author Rod Johnson
089: * @author Juergen Hoeller
090: * @since 13 April 2001
091: * @see BeanNameAware#setBeanName
092: * @see BeanClassLoaderAware#setBeanClassLoader
093: * @see BeanFactoryAware#setBeanFactory
094: * @see org.springframework.context.ResourceLoaderAware#setResourceLoader
095: * @see org.springframework.context.ApplicationEventPublisherAware#setApplicationEventPublisher
096: * @see org.springframework.context.MessageSourceAware#setMessageSource
097: * @see org.springframework.context.ApplicationContextAware#setApplicationContext
098: * @see org.springframework.web.context.ServletContextAware#setServletContext
099: * @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: * Return an instance, which may be shared or independent, of the specified bean.
118: * <p>This method allows a Spring BeanFactory to be used as a replacement for the
119: * Singleton or Prototype design pattern. Callers may retain references to
120: * returned objects in the case of Singleton beans.
121: * <p>Translates aliases back to the corresponding canonical bean name.
122: * Will ask the parent factory if the bean cannot be found in this factory instance.
123: * @param name the name of the bean to retrieve
124: * @return an instance of the bean
125: * @throws NoSuchBeanDefinitionException if there is no bean definition
126: * with the specified name
127: * @throws BeansException if the bean could not be obtained
128: */
129: Object getBean(String name) throws BeansException;
130:
131: /**
132: * Return an instance, which may be shared or independent, of the specified bean.
133: * <p>Behaves the same as {@link #getBean(String)}, but provides a measure of type
134: * safety by throwing a BeanNotOfRequiredTypeException if the bean is not of the
135: * required type. This means that ClassCastException can't be thrown on casting
136: * the result correctly, as can happen with {@link #getBean(String)}.
137: * <p>Translates aliases back to the corresponding canonical bean name.
138: * Will ask the parent factory if the bean cannot be found in this factory instance.
139: * @param name the name of the bean to retrieve
140: * @param requiredType type the bean must match. Can be an interface or superclass
141: * of the actual class, or <code>null</code> for any match. For example, if the value
142: * is <code>Object.class</code>, this method will succeed whatever the class of the
143: * returned instance.
144: * @return an instance of the bean
145: * @throws NoSuchBeanDefinitionException if there's no such bean definition
146: * @throws BeanNotOfRequiredTypeException if the bean is not of the required type
147: * @throws BeansException if the bean could not be created
148: */
149: Object getBean(String name, Class requiredType)
150: throws BeansException;
151:
152: /**
153: * Return an instance, which may be shared or independent, of the specified bean.
154: * <p>Allows for specifying explicit constructor arguments / factory method arguments,
155: * overriding the specified default arguments (if any) in the bean definition.
156: * @param name the name of the bean to retrieve
157: * @param args arguments to use if creating a prototype using explicit arguments to a
158: * static factory method. It is invalid to use a non-null args value in any other case.
159: * @return an instance of the bean
160: * @throws NoSuchBeanDefinitionException if there's no such bean definition
161: * @throws BeanDefinitionStoreException if arguments have been given but
162: * the affected bean isn't a prototype
163: * @throws BeansException if the bean could not be created
164: * @since 2.5
165: */
166: Object getBean(String name, Object[] args) throws BeansException;
167:
168: /**
169: * Does this bean factory contain a bean with the given name? More specifically,
170: * is {@link #getBean} able to obtain a bean instance for the given name?
171: * <p>Translates aliases back to the corresponding canonical bean name.
172: * Will ask the parent factory if the bean cannot be found in this factory instance.
173: * @param name the name of the bean to query
174: * @return whether a bean with the given name is defined
175: */
176: boolean containsBean(String name);
177:
178: /**
179: * Is this bean a shared singleton? That is, will {@link #getBean} always
180: * return the same instance?
181: * <p>Note: This method returning <code>false</code> does not clearly indicate
182: * independent instances. It indicates non-singleton instances, which may correspond
183: * to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly
184: * check for independent instances.
185: * <p>Translates aliases back to the corresponding canonical bean name.
186: * Will ask the parent factory if the bean cannot be found in this factory instance.
187: * @param name the name of the bean to query
188: * @return whether this bean corresponds to a singleton instance
189: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
190: * @see #getBean
191: * @see #isPrototype
192: */
193: boolean isSingleton(String name)
194: throws NoSuchBeanDefinitionException;
195:
196: /**
197: * Is this bean a prototype? That is, will {@link #getBean} always return
198: * independent instances?
199: * <p>Note: This method returning <code>false</code> does not clearly indicate
200: * a singleton object. It indicates non-independent instances, which may correspond
201: * to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly
202: * check for a shared singleton instance.
203: * <p>Translates aliases back to the corresponding canonical bean name.
204: * Will ask the parent factory if the bean cannot be found in this factory instance.
205: * @param name the name of the bean to query
206: * @return whether this bean will always deliver independent instances
207: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
208: * @since 2.0.3
209: * @see #getBean
210: * @see #isSingleton
211: */
212: boolean isPrototype(String name)
213: throws NoSuchBeanDefinitionException;
214:
215: /**
216: * Check whether the bean with the given name matches the specified type.
217: * More specifically, check whether a {@link #getBean} call for the given name
218: * would return an object that is assignable to the specified target type.
219: * <p>Translates aliases back to the corresponding canonical bean name.
220: * Will ask the parent factory if the bean cannot be found in this factory instance.
221: * @param name the name of the bean to query
222: * @param targetType the type to match against
223: * @return <code>true</code> if the bean type matches,
224: * <code>false</code> if it doesn't match or cannot be determined yet
225: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
226: * @since 2.0.1
227: * @see #getBean
228: * @see #getType
229: */
230: boolean isTypeMatch(String name, Class targetType)
231: throws NoSuchBeanDefinitionException;
232:
233: /**
234: * Determine the type of the bean with the given name. More specifically,
235: * determine the type of object that {@link #getBean} would return for the given name.
236: * <p>For a {@link FactoryBean}, return the type of object that the FactoryBean creates,
237: * as exposed by {@link FactoryBean#getObjectType()}.
238: * <p>Translates aliases back to the corresponding canonical bean name.
239: * Will ask the parent factory if the bean cannot be found in this factory instance.
240: * @param name the name of the bean to query
241: * @return the type of the bean, or <code>null</code> if not determinable
242: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
243: * @since 1.1.2
244: * @see #getBean
245: * @see #isTypeMatch
246: */
247: Class getType(String name) throws NoSuchBeanDefinitionException;
248:
249: /**
250: * Return the aliases for the given bean name, if any.
251: * All of those aliases point to the same bean when used in a {@link #getBean} call.
252: * <p>If the given name is an alias, the corresponding original bean name
253: * and other aliases (if any) will be returned, with the original bean name
254: * being the first element in the array.
255: * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
256: * @param name the bean name to check for aliases
257: * @return the aliases, or an empty array if none
258: * @see #getBean
259: */
260: String[] getAliases(String name);
261:
262: }
|