/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import java.beans.PropertyEditor;
import java.security.AccessControlContext;

import org.springframework.beans.PropertyEditorRegistrar;
import org.springframework.beans.PropertyEditorRegistry;
import org.springframework.beans.TypeConverter;
import org.springframework.beans.factory.BeanDefinitionStoreException;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.beans.factory.HierarchicalBeanFactory;
import org.springframework.beans.factory.NoSuchBeanDefinitionException;
import org.springframework.core.convert.ConversionService;
import org.springframework.lang.Nullable;
import org.springframework.util.StringValueResolver;

Configuration interface to be implemented by most bean factories. Provides facilities to configure a bean factory, in addition to the bean factory client methods in the BeanFactory interface. 
This bean factory interface is not meant to be used in normal application code: Stick to BeanFactory or ListableBeanFactory for typical needs. This extended interface is just meant to allow for framework-internal plug'n'play and for special access to bean factory configuration methods. 
Author:
Juergen Hoeller
See Also:
BeanFactory
ListableBeanFactory
ConfigurableListableBeanFactory
Since:
03.11.2003/**
 * Configuration interface to be implemented by most bean factories. Provides
 * facilities to configure a bean factory, in addition to the bean factory
 * client methods in the {@link org.springframework.beans.factory.BeanFactory}
 * interface.
 *
 * <p>This bean factory interface is not meant to be used in normal application
 * code: Stick to {@link org.springframework.beans.factory.BeanFactory} or
 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
 * needs. This extended interface is just meant to allow for framework-internal
 * plug'n'play and for special access to bean factory configuration methods.
 *
 * @author Juergen Hoeller
 * @since 03.11.2003
 * @see org.springframework.beans.factory.BeanFactory
 * @see org.springframework.beans.factory.ListableBeanFactory
 * @see ConfigurableListableBeanFactory
 */
public interface ConfigurableBeanFactory extends HierarchicalBeanFactory, SingletonBeanRegistry {

	
Scope identifier for the standard singleton scope: "singleton". Custom scopes can be added via registerScope. 
See Also:
registerScope/**
	 * Scope identifier for the standard singleton scope: "singleton".
	 * Custom scopes can be added via {@code registerScope}.
	 * @see #registerScope
	 */
	String SCOPE_SINGLETON = "singleton";

	
Scope identifier for the standard prototype scope: "prototype". Custom scopes can be added via registerScope. 
See Also:
registerScope/**
	 * Scope identifier for the standard prototype scope: "prototype".
	 * Custom scopes can be added via {@code registerScope}.
	 * @see #registerScope
	 */
	String SCOPE_PROTOTYPE = "prototype";


	
Set the parent of this bean factory.
Note that the parent cannot be changed: It should only be set outside
a constructor if it isn't available at the time of factory instantiation.
Params:
parentBeanFactory – the parent BeanFactory
Throws:
IllegalStateException – if this factory is already associated with
a parent BeanFactory
See Also:
HierarchicalBeanFactory.getParentBeanFactory()/**
	 * Set the parent of this bean factory.
	 * <p>Note that the parent cannot be changed: It should only be set outside
	 * a constructor if it isn't available at the time of factory instantiation.
	 * @param parentBeanFactory the parent BeanFactory
	 * @throws IllegalStateException if this factory is already associated with
	 * a parent BeanFactory
	 * @see #getParentBeanFactory()
	 */
	void setParentBeanFactory(BeanFactory parentBeanFactory) throws IllegalStateException;

	
Set the class loader to use for loading bean classes.
Default is the thread context class loader.
Note that this class loader will only apply to bean definitions
that do not carry a resolved bean class yet. This is the case as of
Spring 2.0 by default: Bean definitions only carry bean class names,
to be resolved once the factory processes the bean definition.
Params:
beanClassLoader – the class loader to use, or null to suggest the default class loader/**
	 * Set the class loader to use for loading bean classes.
	 * Default is the thread context class loader.
	 * <p>Note that this class loader will only apply to bean definitions
	 * that do not carry a resolved bean class yet. This is the case as of
	 * Spring 2.0 by default: Bean definitions only carry bean class names,
	 * to be resolved once the factory processes the bean definition.
	 * @param beanClassLoader the class loader to use,
	 * or {@code null} to suggest the default class loader
	 */
	void setBeanClassLoader(@Nullable ClassLoader beanClassLoader);

	
Return this factory's class loader for loading bean classes (only null if even the system ClassLoader isn't accessible). 
See Also:
ClassUtils.forName(String, ClassLoader)/**
	 * Return this factory's class loader for loading bean classes
	 * (only {@code null} if even the system ClassLoader isn't accessible).
	 * @see org.springframework.util.ClassUtils#forName(String, ClassLoader)
	 */
	@Nullable
	ClassLoader getBeanClassLoader();

	
Specify a temporary ClassLoader to use for type matching purposes.
Default is none, simply using the standard bean ClassLoader.
A temporary ClassLoader is usually just specified if
load-time weaving is involved, to make sure that actual bean
classes are loaded as lazily as possible. The temporary loader is
then removed once the BeanFactory completes its bootstrap phase.
Since:
2.5/**
	 * Specify a temporary ClassLoader to use for type matching purposes.
	 * Default is none, simply using the standard bean ClassLoader.
	 * <p>A temporary ClassLoader is usually just specified if
	 * <i>load-time weaving</i> is involved, to make sure that actual bean
	 * classes are loaded as lazily as possible. The temporary loader is
	 * then removed once the BeanFactory completes its bootstrap phase.
	 * @since 2.5
	 */
	void setTempClassLoader(@Nullable ClassLoader tempClassLoader);

	
Return the temporary ClassLoader to use for type matching purposes,
if any.
Since:
2.5/**
	 * Return the temporary ClassLoader to use for type matching purposes,
	 * if any.
	 * @since 2.5
	 */
	@Nullable
	ClassLoader getTempClassLoader();

	
Set whether to cache bean metadata such as given bean definitions
(in merged fashion) and resolved bean classes. Default is on.
Turn this flag off to enable hot-refreshing of bean definition objects
and in particular bean classes. If this flag is off, any creation of a bean
instance will re-query the bean class loader for newly resolved classes.
/**
	 * Set whether to cache bean metadata such as given bean definitions
	 * (in merged fashion) and resolved bean classes. Default is on.
	 * <p>Turn this flag off to enable hot-refreshing of bean definition objects
	 * and in particular bean classes. If this flag is off, any creation of a bean
	 * instance will re-query the bean class loader for newly resolved classes.
	 */
	void setCacheBeanMetadata(boolean cacheBeanMetadata);

	
Return whether to cache bean metadata such as given bean definitions
(in merged fashion) and resolved bean classes.
/**
	 * Return whether to cache bean metadata such as given bean definitions
	 * (in merged fashion) and resolved bean classes.
	 */
	boolean isCacheBeanMetadata();

	
Specify the resolution strategy for expressions in bean definition values.
There is no expression support active in a BeanFactory by default.
An ApplicationContext will typically set a standard expression strategy
here, supporting "#{...}" expressions in a Unified EL compatible style.
Since:
3.0/**
	 * Specify the resolution strategy for expressions in bean definition values.
	 * <p>There is no expression support active in a BeanFactory by default.
	 * An ApplicationContext will typically set a standard expression strategy
	 * here, supporting "#{...}" expressions in a Unified EL compatible style.
	 * @since 3.0
	 */
	void setBeanExpressionResolver(@Nullable BeanExpressionResolver resolver);

	
Return the resolution strategy for expressions in bean definition values.
Since:
3.0/**
	 * Return the resolution strategy for expressions in bean definition values.
	 * @since 3.0
	 */
	@Nullable
	BeanExpressionResolver getBeanExpressionResolver();

	
Specify a Spring 3.0 ConversionService to use for converting
property values, as an alternative to JavaBeans PropertyEditors.
Since:
3.0/**
	 * Specify a Spring 3.0 ConversionService to use for converting
	 * property values, as an alternative to JavaBeans PropertyEditors.
	 * @since 3.0
	 */
	void setConversionService(@Nullable ConversionService conversionService);

	
Return the associated ConversionService, if any.
Since:
3.0/**
	 * Return the associated ConversionService, if any.
	 * @since 3.0
	 */
	@Nullable
	ConversionService getConversionService();

	
Add a PropertyEditorRegistrar to be applied to all bean creation processes.
Such a registrar creates new PropertyEditor instances and registers them on the given registry, fresh for each bean creation attempt. This avoids the need for synchronization on custom editors; hence, it is generally preferable to use this method instead of registerCustomEditor. 
Params:
registrar – the PropertyEditorRegistrar to register/**
	 * Add a PropertyEditorRegistrar to be applied to all bean creation processes.
	 * <p>Such a registrar creates new PropertyEditor instances and registers them
	 * on the given registry, fresh for each bean creation attempt. This avoids
	 * the need for synchronization on custom editors; hence, it is generally
	 * preferable to use this method instead of {@link #registerCustomEditor}.
	 * @param registrar the PropertyEditorRegistrar to register
	 */
	void addPropertyEditorRegistrar(PropertyEditorRegistrar registrar);

	
Register the given custom property editor for all properties of the
given type. To be invoked during factory configuration.
Note that this method will register a shared custom editor instance; access to that instance will be synchronized for thread-safety. It is generally preferable to use addPropertyEditorRegistrar instead of this method, to avoid for the need for synchronization on custom editors. 
Params:
requiredType – type of the property
propertyEditorClass – the PropertyEditor class to register/**
	 * Register the given custom property editor for all properties of the
	 * given type. To be invoked during factory configuration.
	 * <p>Note that this method will register a shared custom editor instance;
	 * access to that instance will be synchronized for thread-safety. It is
	 * generally preferable to use {@link #addPropertyEditorRegistrar} instead
	 * of this method, to avoid for the need for synchronization on custom editors.
	 * @param requiredType type of the property
	 * @param propertyEditorClass the {@link PropertyEditor} class to register
	 */
	void registerCustomEditor(Class<?> requiredType, Class<? extends PropertyEditor> propertyEditorClass);

	
Initialize the given PropertyEditorRegistry with the custom editors
that have been registered with this BeanFactory.
Params:
registry – the PropertyEditorRegistry to initialize/**
	 * Initialize the given PropertyEditorRegistry with the custom editors
	 * that have been registered with this BeanFactory.
	 * @param registry the PropertyEditorRegistry to initialize
	 */
	void copyRegisteredEditorsTo(PropertyEditorRegistry registry);

	
Set a custom type converter that this BeanFactory should use for converting
bean property values, constructor argument values, etc.
This will override the default PropertyEditor mechanism and hence make
any custom editors or custom editor registrars irrelevant.
See Also:
addPropertyEditorRegistrar
registerCustomEditor
Since:
2.5/**
	 * Set a custom type converter that this BeanFactory should use for converting
	 * bean property values, constructor argument values, etc.
	 * <p>This will override the default PropertyEditor mechanism and hence make
	 * any custom editors or custom editor registrars irrelevant.
	 * @since 2.5
	 * @see #addPropertyEditorRegistrar
	 * @see #registerCustomEditor
	 */
	void setTypeConverter(TypeConverter typeConverter);

	
Obtain a type converter as used by this BeanFactory. This may be a fresh
instance for each call, since TypeConverters are usually not thread-safe.
If the default PropertyEditor mechanism is active, the returned
TypeConverter will be aware of all custom editors that have been registered.
Since:
2.5/**
	 * Obtain a type converter as used by this BeanFactory. This may be a fresh
	 * instance for each call, since TypeConverters are usually <i>not</i> thread-safe.
	 * <p>If the default PropertyEditor mechanism is active, the returned
	 * TypeConverter will be aware of all custom editors that have been registered.
	 * @since 2.5
	 */
	TypeConverter getTypeConverter();

	
Add a String resolver for embedded values such as annotation attributes.
Params:
valueResolver – the String resolver to apply to embedded values
Since:
3.0/**
	 * Add a String resolver for embedded values such as annotation attributes.
	 * @param valueResolver the String resolver to apply to embedded values
	 * @since 3.0
	 */
	void addEmbeddedValueResolver(StringValueResolver valueResolver);

	
Determine whether an embedded value resolver has been registered with this bean factory, to be applied through resolveEmbeddedValue(String). 
Since:
4.3/**
	 * Determine whether an embedded value resolver has been registered with this
	 * bean factory, to be applied through {@link #resolveEmbeddedValue(String)}.
	 * @since 4.3
	 */
	boolean hasEmbeddedValueResolver();

	
Resolve the given embedded value, e.g. an annotation attribute.
Params:
value – the value to resolve
Returns:
the resolved value (may be the original value as-is)
Since:
3.0/**
	 * Resolve the given embedded value, e.g. an annotation attribute.
	 * @param value the value to resolve
	 * @return the resolved value (may be the original value as-is)
	 * @since 3.0
	 */
	@Nullable
	String resolveEmbeddedValue(String value);

	
Add a new BeanPostProcessor that will get applied to beans created
by this factory. To be invoked during factory configuration.
Note: Post-processors submitted here will be applied in the order of registration; any ordering semantics expressed through implementing the Ordered interface will be ignored. Note that autodetected post-processors (e.g. as beans in an ApplicationContext) will always be applied after programmatically registered ones. 
Params:
beanPostProcessor – the post-processor to register/**
	 * Add a new BeanPostProcessor that will get applied to beans created
	 * by this factory. To be invoked during factory configuration.
	 * <p>Note: Post-processors submitted here will be applied in the order of
	 * registration; any ordering semantics expressed through implementing the
	 * {@link org.springframework.core.Ordered} interface will be ignored. Note
	 * that autodetected post-processors (e.g. as beans in an ApplicationContext)
	 * will always be applied after programmatically registered ones.
	 * @param beanPostProcessor the post-processor to register
	 */
	void addBeanPostProcessor(BeanPostProcessor beanPostProcessor);

	
Return the current number of registered BeanPostProcessors, if any.
/**
	 * Return the current number of registered BeanPostProcessors, if any.
	 */
	int getBeanPostProcessorCount();

	
Register the given scope, backed by the given Scope implementation.
Params:
scopeName – the scope identifier
scope – the backing Scope implementation/**
	 * Register the given scope, backed by the given Scope implementation.
	 * @param scopeName the scope identifier
	 * @param scope the backing Scope implementation
	 */
	void registerScope(String scopeName, Scope scope);

	
Return the names of all currently registered scopes.
This will only return the names of explicitly registered scopes.
Built-in scopes such as "singleton" and "prototype" won't be exposed.
See Also:
registerScope
Returns:
the array of scope names, or an empty array if none/**
	 * Return the names of all currently registered scopes.
	 * <p>This will only return the names of explicitly registered scopes.
	 * Built-in scopes such as "singleton" and "prototype" won't be exposed.
	 * @return the array of scope names, or an empty array if none
	 * @see #registerScope
	 */
	String[] getRegisteredScopeNames();

	
Return the Scope implementation for the given scope name, if any.
This will only return explicitly registered scopes.
Built-in scopes such as "singleton" and "prototype" won't be exposed.
Params:
scopeName – the name of the scope
See Also:
registerScope
Returns:
the registered Scope implementation, or null if none/**
	 * Return the Scope implementation for the given scope name, if any.
	 * <p>This will only return explicitly registered scopes.
	 * Built-in scopes such as "singleton" and "prototype" won't be exposed.
	 * @param scopeName the name of the scope
	 * @return the registered Scope implementation, or {@code null} if none
	 * @see #registerScope
	 */
	@Nullable
	Scope getRegisteredScope(String scopeName);

	
Provides a security access control context relevant to this factory.
Returns:
the applicable AccessControlContext (never null)
Since:
3.0/**
	 * Provides a security access control context relevant to this factory.
	 * @return the applicable AccessControlContext (never {@code null})
	 * @since 3.0
	 */
	AccessControlContext getAccessControlContext();

	
Copy all relevant configuration from the given other factory.
Should include all standard configuration settings as well as
BeanPostProcessors, Scopes, and factory-specific internal settings.
Should not include any metadata of actual bean definitions,
such as BeanDefinition objects and bean name aliases.
Params:
otherFactory – the other BeanFactory to copy from/**
	 * Copy all relevant configuration from the given other factory.
	 * <p>Should include all standard configuration settings as well as
	 * BeanPostProcessors, Scopes, and factory-specific internal settings.
	 * Should not include any metadata of actual bean definitions,
	 * such as BeanDefinition objects and bean name aliases.
	 * @param otherFactory the other BeanFactory to copy from
	 */
	void copyConfigurationFrom(ConfigurableBeanFactory otherFactory);

	
Given a bean name, create an alias. We typically use this method to
support names that are illegal within XML ids (used for bean names).
Typically invoked during factory configuration, but can also be
used for runtime registration of aliases. Therefore, a factory
implementation should synchronize alias access.
Params:
beanName – the canonical name of the target bean
alias – the alias to be registered for the bean
Throws:
BeanDefinitionStoreException – if the alias is already in use/**
	 * Given a bean name, create an alias. We typically use this method to
	 * support names that are illegal within XML ids (used for bean names).
	 * <p>Typically invoked during factory configuration, but can also be
	 * used for runtime registration of aliases. Therefore, a factory
	 * implementation should synchronize alias access.
	 * @param beanName the canonical name of the target bean
	 * @param alias the alias to be registered for the bean
	 * @throws BeanDefinitionStoreException if the alias is already in use
	 */
	void registerAlias(String beanName, String alias) throws BeanDefinitionStoreException;

	
Resolve all alias target names and aliases registered in this
factory, applying the given StringValueResolver to them.
The value resolver may for example resolve placeholders
in target bean names and even in alias names.
Params:
valueResolver – the StringValueResolver to apply
Since:
2.5/**
	 * Resolve all alias target names and aliases registered in this
	 * factory, applying the given StringValueResolver to them.
	 * <p>The value resolver may for example resolve placeholders
	 * in target bean names and even in alias names.
	 * @param valueResolver the StringValueResolver to apply
	 * @since 2.5
	 */
	void resolveAliases(StringValueResolver valueResolver);

	
Return a merged BeanDefinition for the given bean name,
merging a child bean definition with its parent if necessary.
Considers bean definitions in ancestor factories as well.
Params:
beanName – the name of the bean to retrieve the merged definition for
Throws:
NoSuchBeanDefinitionException – if there is no bean definition with the given name
Returns:
a (potentially merged) BeanDefinition for the given bean
Since:
2.5/**
	 * Return a merged BeanDefinition for the given bean name,
	 * merging a child bean definition with its parent if necessary.
	 * Considers bean definitions in ancestor factories as well.
	 * @param beanName the name of the bean to retrieve the merged definition for
	 * @return a (potentially merged) BeanDefinition for the given bean
	 * @throws NoSuchBeanDefinitionException if there is no bean definition with the given name
	 * @since 2.5
	 */
	BeanDefinition getMergedBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;

	
Determine whether the bean with the given name is a FactoryBean.
Params:
name – the name of the bean to check
Throws:
NoSuchBeanDefinitionException – if there is no bean with the given name
Returns:
whether the bean is a FactoryBean (false means the bean exists but is not a FactoryBean)
Since:
2.5/**
	 * Determine whether the bean with the given name is a FactoryBean.
	 * @param name the name of the bean to check
	 * @return whether the bean is a FactoryBean
	 * ({@code false} means the bean exists but is not a FactoryBean)
	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
	 * @since 2.5
	 */
	boolean isFactoryBean(String name) throws NoSuchBeanDefinitionException;

	
Explicitly control the current in-creation status of the specified bean.
For container-internal use only.
Params:
beanName – the name of the bean
inCreation – whether the bean is currently in creation
Since:
3.1/**
	 * Explicitly control the current in-creation status of the specified bean.
	 * For container-internal use only.
	 * @param beanName the name of the bean
	 * @param inCreation whether the bean is currently in creation
	 * @since 3.1
	 */
	void setCurrentlyInCreation(String beanName, boolean inCreation);

	
Determine whether the specified bean is currently in creation.
Params:
beanName – the name of the bean
Returns:
whether the bean is currently in creation
Since:
2.5/**
	 * Determine whether the specified bean is currently in creation.
	 * @param beanName the name of the bean
	 * @return whether the bean is currently in creation
	 * @since 2.5
	 */
	boolean isCurrentlyInCreation(String beanName);

	
Register a dependent bean for the given bean,
to be destroyed before the given bean is destroyed.
Params:
beanName – the name of the bean
dependentBeanName – the name of the dependent bean
Since:
2.5/**
	 * Register a dependent bean for the given bean,
	 * to be destroyed before the given bean is destroyed.
	 * @param beanName the name of the bean
	 * @param dependentBeanName the name of the dependent bean
	 * @since 2.5
	 */
	void registerDependentBean(String beanName, String dependentBeanName);

	
Return the names of all beans which depend on the specified bean, if any.
Params:
beanName – the name of the bean
Returns:
the array of dependent bean names, or an empty array if none
Since:
2.5/**
	 * Return the names of all beans which depend on the specified bean, if any.
	 * @param beanName the name of the bean
	 * @return the array of dependent bean names, or an empty array if none
	 * @since 2.5
	 */
	String[] getDependentBeans(String beanName);

	
Return the names of all beans that the specified bean depends on, if any.
Params:
beanName – the name of the bean
Returns:
the array of names of beans which the bean depends on,
or an empty array if none
Since:
2.5/**
	 * Return the names of all beans that the specified bean depends on, if any.
	 * @param beanName the name of the bean
	 * @return the array of names of beans which the bean depends on,
	 * or an empty array if none
	 * @since 2.5
	 */
	String[] getDependenciesForBean(String beanName);

	
Destroy the given bean instance (usually a prototype instance
obtained from this factory) according to its bean definition.
Any exception that arises during destruction should be caught
and logged instead of propagated to the caller of this method.
Params:
beanName – the name of the bean definition
beanInstance – the bean instance to destroy/**
	 * Destroy the given bean instance (usually a prototype instance
	 * obtained from this factory) according to its bean definition.
	 * <p>Any exception that arises during destruction should be caught
	 * and logged instead of propagated to the caller of this method.
	 * @param beanName the name of the bean definition
	 * @param beanInstance the bean instance to destroy
	 */
	void destroyBean(String beanName, Object beanInstance);

	
Destroy the specified scoped bean in the current target scope, if any.
Any exception that arises during destruction should be caught
and logged instead of propagated to the caller of this method.
Params:
beanName – the name of the scoped bean/**
	 * Destroy the specified scoped bean in the current target scope, if any.
	 * <p>Any exception that arises during destruction should be caught
	 * and logged instead of propagated to the caller of this method.
	 * @param beanName the name of the scoped bean
	 */
	void destroyScopedBean(String beanName);

	
Destroy all singleton beans in this factory, including inner beans that have
been registered as disposable. To be called on shutdown of a factory.
Any exception that arises during destruction should be caught
and logged instead of propagated to the caller of this method.
/**
	 * Destroy all singleton beans in this factory, including inner beans that have
	 * been registered as disposable. To be called on shutdown of a factory.
	 * <p>Any exception that arises during destruction should be caught
	 * and logged instead of propagated to the caller of this method.
	 */
	void destroySingletons();

}