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 BeanNotOfRequiredTypeException if the bean is not of the required type
146: * @throws NoSuchBeanDefinitionException if there's no such bean definition
147: * @throws BeansException if the bean could not be created
148: */
149: Object getBean(String name, Class requiredType)
150: throws BeansException;
151:
152: /**
153: * Does this bean factory contain a bean with the given name? More specifically,
154: * is {@link #getBean} able to obtain a bean instance for the given name?
155: * <p>Translates aliases back to the corresponding canonical bean name.
156: * Will ask the parent factory if the bean cannot be found in this factory instance.
157: * @param name the name of the bean to query
158: * @return whether a bean with the given name is defined
159: */
160: boolean containsBean(String name);
161:
162: /**
163: * Is this bean a shared singleton? That is, will {@link #getBean} always
164: * return the same instance?
165: * <p>Note: This method returning <code>false</code> does not clearly indicate
166: * independent instances. It indicates non-singleton instances, which may correspond
167: * to a scoped bean as well. Use the {@link #isPrototype} operation to explicitly
168: * check for independent instances.
169: * <p>Translates aliases back to the corresponding canonical bean name.
170: * Will ask the parent factory if the bean cannot be found in this factory instance.
171: * @param name the name of the bean to query
172: * @return whether this bean corresponds to a singleton instance
173: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
174: * @see #getBean
175: * @see #isPrototype
176: */
177: boolean isSingleton(String name)
178: throws NoSuchBeanDefinitionException;
179:
180: /**
181: * Is this bean a prototype? That is, will {@link #getBean} always return
182: * independent instances?
183: * <p>Note: This method returning <code>false</code> does not clearly indicate
184: * a singleton object. It indicates non-independent instances, which may correspond
185: * to a scoped bean as well. Use the {@link #isSingleton} operation to explicitly
186: * check for a shared singleton instance.
187: * <p>Translates aliases back to the corresponding canonical bean name.
188: * Will ask the parent factory if the bean cannot be found in this factory instance.
189: * @param name the name of the bean to query
190: * @return whether this bean will always deliver independent instances
191: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
192: * @since 2.0.3
193: * @see #getBean
194: * @see #isSingleton
195: */
196: boolean isPrototype(String name)
197: throws NoSuchBeanDefinitionException;
198:
199: /**
200: * Check whether the bean with the given name matches the specified type.
201: * More specifically, check whether a {@link #getBean} call for the given name
202: * would return an object that is assignable to the specified target type.
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: * @param targetType the type to match against
207: * @return <code>true</code> if the bean type matches,
208: * <code>false</code> if it doesn't match or cannot be determined yet
209: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
210: * @since 2.0.1
211: * @see #getBean
212: * @see #getType
213: */
214: boolean isTypeMatch(String name, Class targetType)
215: throws NoSuchBeanDefinitionException;
216:
217: /**
218: * Determine the type of the bean with the given name. More specifically,
219: * determine the type of object that {@link #getBean} would return for the given name.
220: * <p>For a {@link FactoryBean}, return the type of object that the FactoryBean creates,
221: * as exposed by {@link FactoryBean#getObjectType()}.
222: * <p>Translates aliases back to the corresponding canonical bean name.
223: * Will ask the parent factory if the bean cannot be found in this factory instance.
224: * @param name the name of the bean to query
225: * @return the type of the bean, or <code>null</code> if not determinable
226: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
227: * @since 1.1.2
228: * @see #getBean
229: * @see #isTypeMatch
230: */
231: Class getType(String name) throws NoSuchBeanDefinitionException;
232:
233: /**
234: * Return the aliases for the given bean name, if any.
235: * All of those aliases point to the same bean when used in a {@link #getBean} call.
236: * <p>If the given name is an alias, the corresponding original bean name
237: * and other aliases (if any) will be returned, with the original bean name
238: * being the first element in the array.
239: * <p>Will ask the parent factory if the bean cannot be found in this factory instance.
240: * @param name the bean name to check for aliases
241: * @return the aliases, or an empty array if none
242: * @see #getBean
243: */
244: String[] getAliases(String name);
245:
246: }
|