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.config;
018:
019: import java.beans.PropertyEditor;
020:
021: import org.springframework.beans.PropertyEditorRegistrar;
022: import org.springframework.beans.TypeConverter;
023: import org.springframework.beans.factory.BeanDefinitionStoreException;
024: import org.springframework.beans.factory.BeanFactory;
025: import org.springframework.beans.factory.HierarchicalBeanFactory;
026: import org.springframework.beans.factory.NoSuchBeanDefinitionException;
027: import org.springframework.util.StringValueResolver;
028:
029: /**
030: * Configuration interface to be implemented by most bean factories. Provides
031: * facilities to configure a bean factory, in addition to the bean factory
032: * client methods in the {@link org.springframework.beans.factory.BeanFactory}
033: * interface.
034: *
035: * <p>This bean factory interface is not meant to be used in normal application
036: * code: Stick to {@link org.springframework.beans.factory.BeanFactory} or
037: * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
038: * needs. This extended interface is just meant to allow for framework-internal
039: * plug'n'play and for special access to bean factory configuration methods.
040: *
041: * @author Juergen Hoeller
042: * @since 03.11.2003
043: * @see org.springframework.beans.factory.BeanFactory
044: * @see org.springframework.beans.factory.ListableBeanFactory
045: * @see ConfigurableListableBeanFactory
046: */
047: public interface ConfigurableBeanFactory extends
048: HierarchicalBeanFactory, SingletonBeanRegistry {
049:
050: /**
051: * Scope identifier for the standard singleton scope: "singleton".
052: * Custom scopes can be added via <code>registerScope</code>.
053: * @see #registerScope
054: */
055: String SCOPE_SINGLETON = "singleton";
056:
057: /**
058: * Scope identifier for the standard prototype scope: "prototype".
059: * Custom scopes can be added via <code>registerScope</code>.
060: * @see #registerScope
061: */
062: String SCOPE_PROTOTYPE = "prototype";
063:
064: /**
065: * Set the parent of this bean factory.
066: * <p>Note that the parent cannot be changed: It should only be set outside
067: * a constructor if it isn't available at the time of factory instantiation.
068: * @param parentBeanFactory the parent BeanFactory
069: * @throws IllegalStateException if this factory is already associated with
070: * a parent BeanFactory
071: * @see #getParentBeanFactory()
072: */
073: void setParentBeanFactory(BeanFactory parentBeanFactory)
074: throws IllegalStateException;
075:
076: /**
077: * Set the class loader to use for loading bean classes.
078: * Default is the thread context class loader.
079: * <p>Note that this class loader will only apply to bean definitions
080: * that do not carry a resolved bean class yet. This is the case as of
081: * Spring 2.0 by default: Bean definitions only carry bean class names,
082: * to be resolved once the factory processes the bean definition.
083: * @param beanClassLoader the class loader to use,
084: * or <code>null</code> to suggest the default class loader
085: */
086: void setBeanClassLoader(ClassLoader beanClassLoader);
087:
088: /**
089: * Return this factory's class loader for loading bean classes.
090: */
091: ClassLoader getBeanClassLoader();
092:
093: /**
094: * Specify a temporary ClassLoader to use for type matching purposes.
095: * Default is none, simply using the standard bean ClassLoader.
096: * <p>A temporary ClassLoader is usually just specified if
097: * <i>load-time weaving</i> is involved, to make sure that actual bean
098: * classes are loaded as lazily as possible. The temporary loader is
099: * then removed once the BeanFactory completes its bootstrap phase.
100: */
101: void setTempClassLoader(ClassLoader tempClassLoader);
102:
103: /**
104: * Return the temporary ClassLoader to use for type matching purposes,
105: * if any.
106: */
107: ClassLoader getTempClassLoader();
108:
109: /**
110: * Set whether to cache bean metadata such as given bean definitions
111: * (in merged fashion) and resolved bean classes. Default is on.
112: * <p>Turn this flag off to enable hot-refreshing of bean definition objects
113: * and in particular bean classes. If this flag is off, any creation of a bean
114: * instance will re-query the bean class loader for newly resolved classes.
115: */
116: void setCacheBeanMetadata(boolean cacheBeanMetadata);
117:
118: /**
119: * Return whether to cache bean metadata such as given bean definitions
120: * (in merged fashion) and resolved bean classes.
121: */
122: boolean isCacheBeanMetadata();
123:
124: /**
125: * Add a PropertyEditorRegistrar to be applied to all bean creation processes.
126: * <p>Such a registrar creates new PropertyEditor instances and registers them
127: * on the given registry, fresh for each bean creation attempt. This avoids
128: * the need for synchronization on custom editors; hence, it is generally
129: * preferable to use this method instead of {@link #registerCustomEditor}.
130: * @param registrar the PropertyEditorRegistrar to register
131: */
132: void addPropertyEditorRegistrar(PropertyEditorRegistrar registrar);
133:
134: /**
135: * Register the given custom property editor for all properties of the
136: * given type. To be invoked during factory configuration.
137: * <p>Note that this method will register a shared custom editor instance;
138: * access to that instance will be synchronized for thread-safety. It is
139: * generally prefable to use {@link #addPropertyEditorRegistrar} instead
140: * of this method, to avoid for the need for synchronization on custom editors.
141: * @param requiredType type of the property
142: * @param propertyEditor editor to register
143: * @deprecated as of Spring 2.0.7, in favor of {@link #addPropertyEditorRegistrar}
144: */
145: void registerCustomEditor(Class requiredType,
146: PropertyEditor propertyEditor);
147:
148: /**
149: * Set a custom type converter that this BeanFactory should use for converting
150: * bean property values, constructor argument values, etc.
151: * <p>This will override the default PropertyEditor mechanism and hence make
152: * any custom editors or custom editor registrars irrelevant.
153: * @see #addPropertyEditorRegistrar
154: * @see #registerCustomEditor
155: */
156: void setTypeConverter(TypeConverter typeConverter);
157:
158: /**
159: * Obtain a type converter as used by this BeanFactory. This may be a fresh
160: * instance for each call, since TypeConverters are usually <i>not</i> thread-safe.
161: * <p>If the default PropertyEditor mechanism is active, the returned
162: * TypeConverter will be aware of all custom editors that have been registered.
163: */
164: TypeConverter getTypeConverter();
165:
166: /**
167: * Add a new BeanPostProcessor that will get applied to beans created
168: * by this factory. To be invoked during factory configuration.
169: * @param beanPostProcessor the bean processor to register
170: */
171: void addBeanPostProcessor(BeanPostProcessor beanPostProcessor);
172:
173: /**
174: * Return the current number of registered BeanPostProcessors, if any.
175: */
176: int getBeanPostProcessorCount();
177:
178: /**
179: * Register the given scope, backed by the given Scope implementation.
180: * @param scopeName the scope identifier
181: * @param scope the backing Scope implementation
182: */
183: void registerScope(String scopeName, Scope scope);
184:
185: /**
186: * Return the names of all currently registered scopes.
187: * <p>This will only return the names of explicitly registered scopes.
188: * Built-in scopes such as "singleton" and "prototype" won't be exposed.
189: * @return the array of scope names, or an empty array if none
190: * @see #registerScope
191: */
192: String[] getRegisteredScopeNames();
193:
194: /**
195: * Return the Scope implementation for the given scope name, if any.
196: * <p>This will only return explicitly registered scopes.
197: * Built-in scopes such as "singleton" and "prototype" won't be exposed.
198: * @param scopeName the name of the scope
199: * @return the registered Scope implementation, or <code>null</code> if none
200: * @see #registerScope
201: */
202: Scope getRegisteredScope(String scopeName);
203:
204: /**
205: * Copy all relevant configuration from the given other factory.
206: * <p>Should include all standard configuration settings as well as
207: * BeanPostProcessors, Scopes, and factory-specific internal settings.
208: * Should not include any metadata of actual bean definitions,
209: * such as BeanDefinition objects and bean name aliases.
210: * @param otherFactory the other BeanFactory to copy from
211: */
212: void copyConfigurationFrom(ConfigurableBeanFactory otherFactory);
213:
214: /**
215: * Given a bean name, create an alias. We typically use this method to
216: * support names that are illegal within XML ids (used for bean names).
217: * <p>Typically invoked during factory configuration, but can also be
218: * used for runtime registration of aliases. Therefore, a factory
219: * implementation should synchronize alias access.
220: * @param beanName the canonical name of the target bean
221: * @param alias the alias to be registered for the bean
222: * @throws BeanDefinitionStoreException if the alias is already in use
223: */
224: void registerAlias(String beanName, String alias)
225: throws BeanDefinitionStoreException;
226:
227: /**
228: * Resolve all alias target names and aliases registered in this
229: * factory, applying the given StringValueResolver to them.
230: * <p>The value resolver may for example resolve placeholders
231: * in target bean names and even in alias names.
232: * @param valueResolver the StringValueResolver to apply
233: */
234: void resolveAliases(StringValueResolver valueResolver);
235:
236: /**
237: * Return a merged BeanDefinition for the given bean name,
238: * merging a child bean definition with its parent if necessary.
239: * Considers bean definitions in ancestor factories as well.
240: * @param beanName the name of the bean to retrieve the merged definition for
241: * @return a (potentially merged) BeanDefinition for the given bean
242: * @throws NoSuchBeanDefinitionException if there is no bean definition with the given name
243: */
244: BeanDefinition getMergedBeanDefinition(String beanName)
245: throws NoSuchBeanDefinitionException;
246:
247: /**
248: * Determine whether the bean with the given name is a FactoryBean.
249: * @param name the name of the bean to check
250: * @return whether the bean is a FactoryBean
251: * (<code>false</code> means the bean exists but is not a FactoryBean)
252: * @throws NoSuchBeanDefinitionException if there is no bean with the given name
253: */
254: boolean isFactoryBean(String name)
255: throws NoSuchBeanDefinitionException;
256:
257: /**
258: * Determine whether the specified bean is currently in creation.
259: * @param beanName the name of the bean
260: * @return whether the bean is currently in creation
261: */
262: boolean isCurrentlyInCreation(String beanName);
263:
264: /**
265: * Register a dependent bean for the given bean,
266: * to be destroyed before the given bean is destroyed.
267: * @param beanName the name of the bean
268: * @param dependentBeanName the name of the dependent bean
269: */
270: void registerDependentBean(String beanName, String dependentBeanName);
271:
272: /**
273: * Return the names of all beans which depend on the specified bean, if any.
274: * @param beanName the name of the bean
275: * @return the array of dependent bean names, or an empty array if none
276: */
277: String[] getDependentBeans(String beanName);
278:
279: /**
280: * Return the names of all beans that the specified bean depends on, if any.
281: * @param beanName the name of the bean
282: * @return the array of names of beans which the bean depends on,
283: * or an empty array if none
284: */
285: String[] getDependenciesForBean(String beanName);
286:
287: /**
288: * Destroy the given bean instance (usually a prototype instance
289: * obtained from this factory) according to its bean definition.
290: * <p>Any exception that arises during destruction should be caught
291: * and logged instead of propagated to the caller of this method.
292: * @param beanName the name of the bean definition
293: * @param beanInstance the bean instance to destroy
294: */
295: void destroyBean(String beanName, Object beanInstance);
296:
297: /**
298: * Destroy the specified scoped bean in the current target scope, if any.
299: * <p>Any exception that arises during destruction should be caught
300: * and logged instead of propagated to the caller of this method.
301: * @param beanName the name of the scoped bean
302: */
303: void destroyScopedBean(String beanName);
304:
305: /**
306: * Destroy all singleton beans in this factory, including inner beans that have
307: * been registered as disposable. To be called on shutdown of a factory.
308: * <p>Any exception that arises during destruction should be caught
309: * and logged instead of propagated to the caller of this method.
310: */
311: void destroySingletons();
312:
313: }
|