001/* 002 * Copyright 2002-2016 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 * https://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 017package org.springframework.beans.factory.config; 018 019import java.beans.PropertyEditor; 020import java.security.AccessControlContext; 021 022import org.springframework.beans.PropertyEditorRegistrar; 023import org.springframework.beans.PropertyEditorRegistry; 024import org.springframework.beans.TypeConverter; 025import org.springframework.beans.factory.BeanDefinitionStoreException; 026import org.springframework.beans.factory.BeanFactory; 027import org.springframework.beans.factory.HierarchicalBeanFactory; 028import org.springframework.beans.factory.NoSuchBeanDefinitionException; 029import org.springframework.core.convert.ConversionService; 030import org.springframework.util.StringValueResolver; 031 032/** 033 * Configuration interface to be implemented by most bean factories. Provides 034 * facilities to configure a bean factory, in addition to the bean factory 035 * client methods in the {@link org.springframework.beans.factory.BeanFactory} 036 * interface. 037 * 038 * <p>This bean factory interface is not meant to be used in normal application 039 * code: Stick to {@link org.springframework.beans.factory.BeanFactory} or 040 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical 041 * needs. This extended interface is just meant to allow for framework-internal 042 * plug'n'play and for special access to bean factory configuration methods. 043 * 044 * @author Juergen Hoeller 045 * @since 03.11.2003 046 * @see org.springframework.beans.factory.BeanFactory 047 * @see org.springframework.beans.factory.ListableBeanFactory 048 * @see ConfigurableListableBeanFactory 049 */ 050public interface ConfigurableBeanFactory extends HierarchicalBeanFactory, SingletonBeanRegistry { 051 052 /** 053 * Scope identifier for the standard singleton scope: "singleton". 054 * Custom scopes can be added via {@code registerScope}. 055 * @see #registerScope 056 */ 057 String SCOPE_SINGLETON = "singleton"; 058 059 /** 060 * Scope identifier for the standard prototype scope: "prototype". 061 * Custom scopes can be added via {@code registerScope}. 062 * @see #registerScope 063 */ 064 String SCOPE_PROTOTYPE = "prototype"; 065 066 067 /** 068 * Set the parent of this bean factory. 069 * <p>Note that the parent cannot be changed: It should only be set outside 070 * a constructor if it isn't available at the time of factory instantiation. 071 * @param parentBeanFactory the parent BeanFactory 072 * @throws IllegalStateException if this factory is already associated with 073 * a parent BeanFactory 074 * @see #getParentBeanFactory() 075 */ 076 void setParentBeanFactory(BeanFactory parentBeanFactory) throws IllegalStateException; 077 078 /** 079 * Set the class loader to use for loading bean classes. 080 * Default is the thread context class loader. 081 * <p>Note that this class loader will only apply to bean definitions 082 * that do not carry a resolved bean class yet. This is the case as of 083 * Spring 2.0 by default: Bean definitions only carry bean class names, 084 * to be resolved once the factory processes the bean definition. 085 * @param beanClassLoader the class loader to use, 086 * or {@code null} to suggest the default class loader 087 */ 088 void setBeanClassLoader(ClassLoader beanClassLoader); 089 090 /** 091 * Return this factory's class loader for loading bean classes. 092 */ 093 ClassLoader getBeanClassLoader(); 094 095 /** 096 * Specify a temporary ClassLoader to use for type matching purposes. 097 * Default is none, simply using the standard bean ClassLoader. 098 * <p>A temporary ClassLoader is usually just specified if 099 * <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 * Determine whether an embedded value resolver has been registered with this 214 * bean factory, to be applied through {@link #resolveEmbeddedValue(String)}. 215 * @since 4.3 216 */ 217 boolean hasEmbeddedValueResolver(); 218 219 /** 220 * Resolve the given embedded value, e.g. an annotation attribute. 221 * @param value the value to resolve 222 * @return the resolved value (may be the original value as-is) 223 * @since 3.0 224 */ 225 String resolveEmbeddedValue(String value); 226 227 /** 228 * Add a new BeanPostProcessor that will get applied to beans created 229 * by this factory. To be invoked during factory configuration. 230 * <p>Note: Post-processors submitted here will be applied in the order of 231 * registration; any ordering semantics expressed through implementing the 232 * {@link org.springframework.core.Ordered} interface will be ignored. Note 233 * that autodetected post-processors (e.g. as beans in an ApplicationContext) 234 * will always be applied after programmatically registered ones. 235 * @param beanPostProcessor the post-processor to register 236 */ 237 void addBeanPostProcessor(BeanPostProcessor beanPostProcessor); 238 239 /** 240 * Return the current number of registered BeanPostProcessors, if any. 241 */ 242 int getBeanPostProcessorCount(); 243 244 /** 245 * Register the given scope, backed by the given Scope implementation. 246 * @param scopeName the scope identifier 247 * @param scope the backing Scope implementation 248 */ 249 void registerScope(String scopeName, Scope scope); 250 251 /** 252 * Return the names of all currently registered scopes. 253 * <p>This will only return the names of explicitly registered scopes. 254 * Built-in scopes such as "singleton" and "prototype" won't be exposed. 255 * @return the array of scope names, or an empty array if none 256 * @see #registerScope 257 */ 258 String[] getRegisteredScopeNames(); 259 260 /** 261 * Return the Scope implementation for the given scope name, if any. 262 * <p>This will only return explicitly registered scopes. 263 * Built-in scopes such as "singleton" and "prototype" won't be exposed. 264 * @param scopeName the name of the scope 265 * @return the registered Scope implementation, or {@code null} if none 266 * @see #registerScope 267 */ 268 Scope getRegisteredScope(String scopeName); 269 270 /** 271 * Provides a security access control context relevant to this factory. 272 * @return the applicable AccessControlContext (never {@code null}) 273 * @since 3.0 274 */ 275 AccessControlContext getAccessControlContext(); 276 277 /** 278 * Copy all relevant configuration from the given other factory. 279 * <p>Should include all standard configuration settings as well as 280 * BeanPostProcessors, Scopes, and factory-specific internal settings. 281 * Should not include any metadata of actual bean definitions, 282 * such as BeanDefinition objects and bean name aliases. 283 * @param otherFactory the other BeanFactory to copy from 284 */ 285 void copyConfigurationFrom(ConfigurableBeanFactory otherFactory); 286 287 /** 288 * Given a bean name, create an alias. We typically use this method to 289 * support names that are illegal within XML ids (used for bean names). 290 * <p>Typically invoked during factory configuration, but can also be 291 * used for runtime registration of aliases. Therefore, a factory 292 * implementation should synchronize alias access. 293 * @param beanName the canonical name of the target bean 294 * @param alias the alias to be registered for the bean 295 * @throws BeanDefinitionStoreException if the alias is already in use 296 */ 297 void registerAlias(String beanName, String alias) throws BeanDefinitionStoreException; 298 299 /** 300 * Resolve all alias target names and aliases registered in this 301 * factory, applying the given StringValueResolver to them. 302 * <p>The value resolver may for example resolve placeholders 303 * in target bean names and even in alias names. 304 * @param valueResolver the StringValueResolver to apply 305 * @since 2.5 306 */ 307 void resolveAliases(StringValueResolver valueResolver); 308 309 /** 310 * Return a merged BeanDefinition for the given bean name, 311 * merging a child bean definition with its parent if necessary. 312 * Considers bean definitions in ancestor factories as well. 313 * @param beanName the name of the bean to retrieve the merged definition for 314 * @return a (potentially merged) BeanDefinition for the given bean 315 * @throws NoSuchBeanDefinitionException if there is no bean definition with the given name 316 * @since 2.5 317 */ 318 BeanDefinition getMergedBeanDefinition(String beanName) throws NoSuchBeanDefinitionException; 319 320 /** 321 * Determine whether the bean with the given name is a FactoryBean. 322 * @param name the name of the bean to check 323 * @return whether the bean is a FactoryBean 324 * ({@code false} means the bean exists but is not a FactoryBean) 325 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 326 * @since 2.5 327 */ 328 boolean isFactoryBean(String name) throws NoSuchBeanDefinitionException; 329 330 /** 331 * Explicitly control the current in-creation status of the specified bean. 332 * For container-internal use only. 333 * @param beanName the name of the bean 334 * @param inCreation whether the bean is currently in creation 335 * @since 3.1 336 */ 337 void setCurrentlyInCreation(String beanName, boolean inCreation); 338 339 /** 340 * Determine whether the specified bean is currently in creation. 341 * @param beanName the name of the bean 342 * @return whether the bean is currently in creation 343 * @since 2.5 344 */ 345 boolean isCurrentlyInCreation(String beanName); 346 347 /** 348 * Register a dependent bean for the given bean, 349 * to be destroyed before the given bean is destroyed. 350 * @param beanName the name of the bean 351 * @param dependentBeanName the name of the dependent bean 352 * @since 2.5 353 */ 354 void registerDependentBean(String beanName, String dependentBeanName); 355 356 /** 357 * Return the names of all beans which depend on the specified bean, if any. 358 * @param beanName the name of the bean 359 * @return the array of dependent bean names, or an empty array if none 360 * @since 2.5 361 */ 362 String[] getDependentBeans(String beanName); 363 364 /** 365 * Return the names of all beans that the specified bean depends on, if any. 366 * @param beanName the name of the bean 367 * @return the array of names of beans which the bean depends on, 368 * or an empty array if none 369 * @since 2.5 370 */ 371 String[] getDependenciesForBean(String beanName); 372 373 /** 374 * Destroy the given bean instance (usually a prototype instance 375 * obtained from this factory) according to its bean definition. 376 * <p>Any exception that arises during destruction should be caught 377 * and logged instead of propagated to the caller of this method. 378 * @param beanName the name of the bean definition 379 * @param beanInstance the bean instance to destroy 380 */ 381 void destroyBean(String beanName, Object beanInstance); 382 383 /** 384 * Destroy the specified scoped bean in the current target scope, if any. 385 * <p>Any exception that arises during destruction should be caught 386 * and logged instead of propagated to the caller of this method. 387 * @param beanName the name of the scoped bean 388 */ 389 void destroyScopedBean(String beanName); 390 391 /** 392 * Destroy all singleton beans in this factory, including inner beans that have 393 * been registered as disposable. To be called on shutdown of a factory. 394 * <p>Any exception that arises during destruction should be caught 395 * and logged instead of propagated to the caller of this method. 396 */ 397 void destroySingletons(); 398 399}