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