1 /*
2 * Copyright 2002-2012 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.config;
18
19 import java.beans.PropertyEditor;
20 import java.security.AccessControlContext;
21
22 import org.springframework.beans.PropertyEditorRegistrar;
23 import org.springframework.beans.PropertyEditorRegistry;
24 import org.springframework.beans.TypeConverter;
25 import org.springframework.beans.factory.BeanDefinitionStoreException;
26 import org.springframework.beans.factory.BeanFactory;
27 import org.springframework.beans.factory.HierarchicalBeanFactory;
28 import org.springframework.beans.factory.NoSuchBeanDefinitionException;
29 import org.springframework.core.convert.ConversionService;
30 import org.springframework.util.StringValueResolver;
31
32 /**
33 * Configuration interface to be implemented by most bean factories. Provides
34 * facilities to configure a bean factory, in addition to the bean factory
35 * client methods in the {@link org.springframework.beans.factory.BeanFactory}
36 * interface.
37 *
38 * <p>This bean factory interface is not meant to be used in normal application
39 * code: Stick to {@link org.springframework.beans.factory.BeanFactory} or
40 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
41 * needs. This extended interface is just meant to allow for framework-internal
42 * plug'n'play and for special access to bean factory configuration methods.
43 *
44 * @author Juergen Hoeller
45 * @since 03.11.2003
46 * @see org.springframework.beans.factory.BeanFactory
47 * @see org.springframework.beans.factory.ListableBeanFactory
48 * @see ConfigurableListableBeanFactory
49 */
50 public interface ConfigurableBeanFactory extends HierarchicalBeanFactory, SingletonBeanRegistry {
51
52 /**
53 * Scope identifier for the standard singleton scope: "singleton".
54 * Custom scopes can be added via {@code registerScope}.
55 * @see #registerScope
56 */
57 String SCOPE_SINGLETON = "singleton";
58
59 /**
60 * Scope identifier for the standard prototype scope: "prototype".
61 * Custom scopes can be added via {@code registerScope}.
62 * @see #registerScope
63 */
64 String SCOPE_PROTOTYPE = "prototype";
65
66
67 /**
68 * Set the parent of this bean factory.
69 * <p>Note that the parent cannot be changed: It should only be set outside
70 * a constructor if it isn't available at the time of factory instantiation.
71 * @param parentBeanFactory the parent BeanFactory
72 * @throws IllegalStateException if this factory is already associated with
73 * a parent BeanFactory
74 * @see #getParentBeanFactory()
75 */
76 void setParentBeanFactory(BeanFactory parentBeanFactory) throws IllegalStateException;
77
78 /**
79 * Set the class loader to use for loading bean classes.
80 * Default is the thread context class loader.
81 * <p>Note that this class loader will only apply to bean definitions
82 * that do not carry a resolved bean class yet. This is the case as of
83 * Spring 2.0 by default: Bean definitions only carry bean class names,
84 * to be resolved once the factory processes the bean definition.
85 * @param beanClassLoader the class loader to use,
86 * or {@code null} to suggest the default class loader
87 */
88 void setBeanClassLoader(ClassLoader beanClassLoader);
89
90 /**
91 * Return this factory's class loader for loading bean classes.
92 */
93 ClassLoader getBeanClassLoader();
94
95 /**
96 * Specify a temporary ClassLoader to use for type matching purposes.
97 * Default is none, simply using the standard bean ClassLoader.
98 * <p>A temporary ClassLoader is usually just specified if
99 * <i>load-time weaving</i> is involved, to make sure that actual bean
100 * classes are loaded as lazily as possible. The temporary loader is
101 * then removed once the BeanFactory completes its bootstrap phase.
102 * @since 2.5
103 */
104 void setTempClassLoader(ClassLoader tempClassLoader);
105
106 /**
107 * Return the temporary ClassLoader to use for type matching purposes,
108 * if any.
109 * @since 2.5
110 */
111 ClassLoader getTempClassLoader();
112
113 /**
114 * Set whether to cache bean metadata such as given bean definitions
115 * (in merged fashion) and resolved bean classes. Default is on.
116 * <p>Turn this flag off to enable hot-refreshing of bean definition objects
117 * and in particular bean classes. If this flag is off, any creation of a bean
118 * instance will re-query the bean class loader for newly resolved classes.
119 */
120 void setCacheBeanMetadata(boolean cacheBeanMetadata);
121
122 /**
123 * Return whether to cache bean metadata such as given bean definitions
124 * (in merged fashion) and resolved bean classes.
125 */
126 boolean isCacheBeanMetadata();
127
128 /**
129 * Specify the resolution strategy for expressions in bean definition values.
130 * <p>There is no expression support active in a BeanFactory by default.
131 * An ApplicationContext will typically set a standard expression strategy
132 * here, supporting "#{...}" expressions in a Unified EL compatible style.
133 * @since 3.0
134 */
135 void setBeanExpressionResolver(BeanExpressionResolver resolver);
136
137 /**
138 * Return the resolution strategy for expressions in bean definition values.
139 * @since 3.0
140 */
141 BeanExpressionResolver getBeanExpressionResolver();
142
143 /**
144 * Specify a Spring 3.0 ConversionService to use for converting
145 * property values, as an alternative to JavaBeans PropertyEditors.
146 * @since 3.0
147 */
148 void setConversionService(ConversionService conversionService);
149
150 /**
151 * Return the associated ConversionService, if any.
152 * @since 3.0
153 */
154 ConversionService getConversionService();
155
156 /**
157 * Add a PropertyEditorRegistrar to be applied to all bean creation processes.
158 * <p>Such a registrar creates new PropertyEditor instances and registers them
159 * on the given registry, fresh for each bean creation attempt. This avoids
160 * the need for synchronization on custom editors; hence, it is generally
161 * preferable to use this method instead of {@link #registerCustomEditor}.
162 * @param registrar the PropertyEditorRegistrar to register
163 */
164 void addPropertyEditorRegistrar(PropertyEditorRegistrar registrar);
165
166 /**
167 * Register the given custom property editor for all properties of the
168 * given type. To be invoked during factory configuration.
169 * <p>Note that this method will register a shared custom editor instance;
170 * access to that instance will be synchronized for thread-safety. It is
171 * generally preferable to use {@link #addPropertyEditorRegistrar} instead
172 * of this method, to avoid for the need for synchronization on custom editors.
173 * @param requiredType type of the property
174 * @param propertyEditorClass the {@link PropertyEditor} class to register
175 */
176 void registerCustomEditor(Class<?> requiredType, Class<? extends PropertyEditor> propertyEditorClass);
177
178 /**
179 * Initialize the given PropertyEditorRegistry with the custom editors
180 * that have been registered with this BeanFactory.
181 * @param registry the PropertyEditorRegistry to initialize
182 */
183 void copyRegisteredEditorsTo(PropertyEditorRegistry registry);
184
185 /**
186 * Set a custom type converter that this BeanFactory should use for converting
187 * bean property values, constructor argument values, etc.
188 * <p>This will override the default PropertyEditor mechanism and hence make
189 * any custom editors or custom editor registrars irrelevant.
190 * @see #addPropertyEditorRegistrar
191 * @see #registerCustomEditor
192 * @since 2.5
193 */
194 void setTypeConverter(TypeConverter typeConverter);
195
196 /**
197 * Obtain a type converter as used by this BeanFactory. This may be a fresh
198 * instance for each call, since TypeConverters are usually <i>not</i> thread-safe.
199 * <p>If the default PropertyEditor mechanism is active, the returned
200 * TypeConverter will be aware of all custom editors that have been registered.
201 * @since 2.5
202 */
203 TypeConverter getTypeConverter();
204
205 /**
206 * Add a String resolver for embedded values such as annotation attributes.
207 * @param valueResolver the String resolver to apply to embedded values
208 * @since 3.0
209 */
210 void addEmbeddedValueResolver(StringValueResolver valueResolver);
211
212 /**
213 * Resolve the given embedded value, e.g. an annotation attribute.
214 * @param value the value to resolve
215 * @return the resolved value (may be the original value as-is)
216 * @since 3.0
217 */
218 String resolveEmbeddedValue(String value);
219
220 /**
221 * Add a new BeanPostProcessor that will get applied to beans created
222 * by this factory. To be invoked during factory configuration.
223 * <p>Note: Post-processors submitted here will be applied in the order of
224 * registration; any ordering semantics expressed through implementing the
225 * {@link org.springframework.core.Ordered} interface will be ignored. Note
226 * that autodetected post-processors (e.g. as beans in an ApplicationContext)
227 * will always be applied after programmatically registered ones.
228 * @param beanPostProcessor the post-processor to register
229 */
230 void addBeanPostProcessor(BeanPostProcessor beanPostProcessor);
231
232 /**
233 * Return the current number of registered BeanPostProcessors, if any.
234 */
235 int getBeanPostProcessorCount();
236
237 /**
238 * Register the given scope, backed by the given Scope implementation.
239 * @param scopeName the scope identifier
240 * @param scope the backing Scope implementation
241 */
242 void registerScope(String scopeName, Scope scope);
243
244 /**
245 * Return the names of all currently registered scopes.
246 * <p>This will only return the names of explicitly registered scopes.
247 * Built-in scopes such as "singleton" and "prototype" won't be exposed.
248 * @return the array of scope names, or an empty array if none
249 * @see #registerScope
250 */
251 String[] getRegisteredScopeNames();
252
253 /**
254 * Return the Scope implementation for the given scope name, if any.
255 * <p>This will only return explicitly registered scopes.
256 * Built-in scopes such as "singleton" and "prototype" won't be exposed.
257 * @param scopeName the name of the scope
258 * @return the registered Scope implementation, or {@code null} if none
259 * @see #registerScope
260 */
261 Scope getRegisteredScope(String scopeName);
262
263 /**
264 * Provides a security access control context relevant to this factory.
265 * @return the applicable AccessControlContext (never {@code null})
266 * @since 3.0
267 */
268 AccessControlContext getAccessControlContext();
269
270 /**
271 * Copy all relevant configuration from the given other factory.
272 * <p>Should include all standard configuration settings as well as
273 * BeanPostProcessors, Scopes, and factory-specific internal settings.
274 * Should not include any metadata of actual bean definitions,
275 * such as BeanDefinition objects and bean name aliases.
276 * @param otherFactory the other BeanFactory to copy from
277 */
278 void copyConfigurationFrom(ConfigurableBeanFactory otherFactory);
279
280 /**
281 * Given a bean name, create an alias. We typically use this method to
282 * support names that are illegal within XML ids (used for bean names).
283 * <p>Typically invoked during factory configuration, but can also be
284 * used for runtime registration of aliases. Therefore, a factory
285 * implementation should synchronize alias access.
286 * @param beanName the canonical name of the target bean
287 * @param alias the alias to be registered for the bean
288 * @throws BeanDefinitionStoreException if the alias is already in use
289 */
290 void registerAlias(String beanName, String alias) throws BeanDefinitionStoreException;
291
292 /**
293 * Resolve all alias target names and aliases registered in this
294 * factory, applying the given StringValueResolver to them.
295 * <p>The value resolver may for example resolve placeholders
296 * in target bean names and even in alias names.
297 * @param valueResolver the StringValueResolver to apply
298 * @since 2.5
299 */
300 void resolveAliases(StringValueResolver valueResolver);
301
302 /**
303 * Return a merged BeanDefinition for the given bean name,
304 * merging a child bean definition with its parent if necessary.
305 * Considers bean definitions in ancestor factories as well.
306 * @param beanName the name of the bean to retrieve the merged definition for
307 * @return a (potentially merged) BeanDefinition for the given bean
308 * @throws NoSuchBeanDefinitionException if there is no bean definition with the given name
309 * @since 2.5
310 */
311 BeanDefinition getMergedBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;
312
313 /**
314 * Determine whether the bean with the given name is a FactoryBean.
315 * @param name the name of the bean to check
316 * @return whether the bean is a FactoryBean
317 * ({@code false} means the bean exists but is not a FactoryBean)
318 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
319 * @since 2.5
320 */
321 boolean isFactoryBean(String name) throws NoSuchBeanDefinitionException;
322
323 /**
324 * Explicitly control the current in-creation status of the specified bean.
325 * For container-internal use only.
326 * @param beanName the name of the bean
327 * @param inCreation whether the bean is currently in creation
328 * @since 3.1
329 */
330 void setCurrentlyInCreation(String beanName, boolean inCreation);
331
332 /**
333 * Determine whether the specified bean is currently in creation.
334 * @param beanName the name of the bean
335 * @return whether the bean is currently in creation
336 * @since 2.5
337 */
338 boolean isCurrentlyInCreation(String beanName);
339
340 /**
341 * Register a dependent bean for the given bean,
342 * to be destroyed before the given bean is destroyed.
343 * @param beanName the name of the bean
344 * @param dependentBeanName the name of the dependent bean
345 * @since 2.5
346 */
347 void registerDependentBean(String beanName, String dependentBeanName);
348
349 /**
350 * Return the names of all beans which depend on the specified bean, if any.
351 * @param beanName the name of the bean
352 * @return the array of dependent bean names, or an empty array if none
353 * @since 2.5
354 */
355 String[] getDependentBeans(String beanName);
356
357 /**
358 * Return the names of all beans that the specified bean depends on, if any.
359 * @param beanName the name of the bean
360 * @return the array of names of beans which the bean depends on,
361 * or an empty array if none
362 * @since 2.5
363 */
364 String[] getDependenciesForBean(String beanName);
365
366 /**
367 * Destroy the given bean instance (usually a prototype instance
368 * obtained from this factory) according to its bean definition.
369 * <p>Any exception that arises during destruction should be caught
370 * and logged instead of propagated to the caller of this method.
371 * @param beanName the name of the bean definition
372 * @param beanInstance the bean instance to destroy
373 */
374 void destroyBean(String beanName, Object beanInstance);
375
376 /**
377 * Destroy the specified scoped bean in the current target scope, if any.
378 * <p>Any exception that arises during destruction should be caught
379 * and logged instead of propagated to the caller of this method.
380 * @param beanName the name of the scoped bean
381 */
382 void destroyScopedBean(String beanName);
383
384 /**
385 * Destroy all singleton beans in this factory, including inner beans that have
386 * been registered as disposable. To be called on shutdown of a factory.
387 * <p>Any exception that arises during destruction should be caught
388 * and logged instead of propagated to the caller of this method.
389 */
390 void destroySingletons();
391
392 }