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:
027: /**
028: * Configuration interface to be implemented by most bean factories. Provides
029: * facilities to configure a bean factory, in addition to the bean factory
030: * client methods in the {@link org.springframework.beans.factory.BeanFactory}
031: * interface.
032: *
033: * <p>This bean factory interface is not meant to be used in normal application
034: * code: Stick to {@link org.springframework.beans.factory.BeanFactory} or
035: * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
036: * needs. This extended interface is just meant to allow for framework-internal
037: * plug'n'play and for special access to bean factory configuration methods.
038: *
039: * @author Juergen Hoeller
040: * @since 03.11.2003
041: * @see org.springframework.beans.factory.BeanFactory
042: * @see org.springframework.beans.factory.ListableBeanFactory
043: * @see ConfigurableListableBeanFactory
044: */
045: public interface ConfigurableBeanFactory extends
046: HierarchicalBeanFactory, SingletonBeanRegistry {
047:
048: /**
049: * Scope identifier for the standard singleton scope: "singleton".
050: * Custom scopes can be added via <code>registerScope</code>.
051: * @see #registerScope
052: */
053: String SCOPE_SINGLETON = "singleton";
054:
055: /**
056: * Scope identifier for the standard prototype scope: "prototype".
057: * Custom scopes can be added via <code>registerScope</code>.
058: * @see #registerScope
059: */
060: String SCOPE_PROTOTYPE = "prototype";
061:
062: /**
063: * Set the parent of this bean factory.
064: * <p>Note that the parent cannot be changed: It should only be set outside
065: * a constructor if it isn't available at the time of factory instantiation.
066: * @param parentBeanFactory the parent BeanFactory
067: * @throws IllegalStateException if this factory is already associated with
068: * a parent BeanFactory
069: * @see #getParentBeanFactory()
070: */
071: void setParentBeanFactory(BeanFactory parentBeanFactory)
072: throws IllegalStateException;
073:
074: /**
075: * Set the class loader to use for loading bean classes.
076: * Default is the thread context class loader.
077: * <p>Note that this class loader will only apply to bean definitions
078: * that do not carry a resolved bean class yet. This is the case as of
079: * Spring 2.0 by default: Bean definitions only carry bean class names,
080: * to be resolved once the factory processes the bean definition.
081: * @param beanClassLoader the class loader to use,
082: * or <code>null</code> to suggest the default class loader
083: */
084: void setBeanClassLoader(ClassLoader beanClassLoader);
085:
086: /**
087: * Return this factory's class loader for loading bean classes.
088: */
089: ClassLoader getBeanClassLoader();
090:
091: /**
092: * Set whether to cache bean metadata such as given bean definitions
093: * (in merged fashion) and resolved bean classes. Default is on.
094: * <p>Turn this flag off to enable hot-refreshing of bean definition objects
095: * and in particular bean classes. If this flag is off, any creation of a bean
096: * instance will re-query the bean class loader for newly resolved classes.
097: */
098: void setCacheBeanMetadata(boolean cacheBeanMetadata);
099:
100: /**
101: * Return whether to cache bean metadata such as given bean definitions
102: * (in merged fashion) and resolved bean classes.
103: */
104: boolean isCacheBeanMetadata();
105:
106: /**
107: * Add a PropertyEditorRegistrar to be applied to all bean creation processes.
108: * <p>Such a registrar creates new PropertyEditor instances and registers them
109: * on the given registry, fresh for each bean creation attempt. This avoids
110: * the need for synchronization on custom editors; hence, it is generally
111: * preferable to use this method instead of <code>registerCustomEditor</code>.
112: * @param registrar the PropertyEditorRegistrar to register
113: * @see #registerCustomEditor
114: */
115: void addPropertyEditorRegistrar(PropertyEditorRegistrar registrar);
116:
117: /**
118: * Register the given custom property editor for all properties of the
119: * given type. To be invoked during factory configuration.
120: * <p>Note that this method will register a shared custom editor instance;
121: * access to that instance will be synchronized for thread-safety. It is
122: * generally prefable to use <code>addPropertyEditorRegistrar</code> instead
123: * of this method, to avoid for the need for synchronization on custom editors.
124: * @param requiredType type of the property
125: * @param propertyEditor editor to register
126: * @see #addPropertyEditorRegistrar
127: */
128: void registerCustomEditor(Class requiredType,
129: PropertyEditor propertyEditor);
130:
131: /**
132: * Obtain a type converter as used by this BeanFactory. This is typically a fresh
133: * instance for each call, since TypeConverters are usually <i>not</i> thread-safe.
134: */
135: TypeConverter getTypeConverter();
136:
137: /**
138: * Add a new BeanPostProcessor that will get applied to beans created
139: * by this factory. To be invoked during factory configuration.
140: * @param beanPostProcessor the bean processor to register
141: */
142: void addBeanPostProcessor(BeanPostProcessor beanPostProcessor);
143:
144: /**
145: * Return the current number of registered BeanPostProcessors, if any.
146: */
147: int getBeanPostProcessorCount();
148:
149: /**
150: * Register the given scope, backed by the given Scope implementation.
151: * @param scopeName the scope identifier
152: * @param scope the backing Scope implementation
153: */
154: void registerScope(String scopeName, Scope scope);
155:
156: /**
157: * Return the names of all currently registered scopes.
158: * <p>This will only return the names of explicitly registered scopes.
159: * Built-in scopes such as "singleton" and "prototype" won't be exposed.
160: * @return the array of scope names, or an empty array if none
161: * @see #registerScope
162: */
163: String[] getRegisteredScopeNames();
164:
165: /**
166: * Return the Scope implementation for the given scope name, if any.
167: * <p>This will only return explicitly registered scopes.
168: * Built-in scopes such as "singleton" and "prototype" won't be exposed.
169: * @param scopeName the name of the scope
170: * @return the registered Scope implementation, or <code>null</code> if none
171: * @see #registerScope
172: */
173: Scope getRegisteredScope(String scopeName);
174:
175: /**
176: * Copy all relevant configuration from the given other factory.
177: * <p>Should include all standard configuration settings as well as
178: * BeanPostProcessors, Scopes, and factory-specific internal settings.
179: * Should not include any metadata of actual bean definitions,
180: * such as BeanDefinition objects and bean name aliases.
181: * @param otherFactory the other BeanFactory to copy from
182: */
183: void copyConfigurationFrom(ConfigurableBeanFactory otherFactory);
184:
185: /**
186: * Given a bean name, create an alias. We typically use this method to
187: * support names that are illegal within XML ids (used for bean names).
188: * <p>Typically invoked during factory configuration, but can also be
189: * used for runtime registration of aliases. Therefore, a factory
190: * implementation should synchronize alias access.
191: * @param beanName the canonical name of the bean
192: * @param alias the alias to be registered for the bean
193: * @throws BeanDefinitionStoreException if the alias is already in use
194: */
195: void registerAlias(String beanName, String alias)
196: throws BeanDefinitionStoreException;
197:
198: /**
199: * Return whether the specified bean is currently in creation.
200: * @param beanName the name of the bean
201: */
202: boolean isCurrentlyInCreation(String beanName);
203:
204: /**
205: * Destroy the given bean instance (usually a prototype instance
206: * obtained from this factory) according to its bean definition.
207: * <p>Any exception that arises during destruction should be caught
208: * and logged instead of propagated to the caller of this method.
209: * @param beanName the name of the bean definition
210: * @param beanInstance the bean instance to destroy
211: */
212: void destroyBean(String beanName, Object beanInstance);
213:
214: /**
215: * Destroy the specified scoped bean in the current target scope, if any.
216: * <p>Any exception that arises during destruction should be caught
217: * and logged instead of propagated to the caller of this method.
218: * @param beanName the name of the scoped bean
219: */
220: void destroyScopedBean(String beanName);
221:
222: /**
223: * Destroy all singleton beans in this factory, including inner beans that have
224: * been registered as disposable. To be called on shutdown of a factory.
225: * <p>Any exception that arises during destruction should be caught
226: * and logged instead of propagated to the caller of this method.
227: */
228: void destroySingletons();
229:
230: }
|