001/*
002 * Copyright 2002-2015 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.util.Iterator;
020
021import org.springframework.beans.BeansException;
022import org.springframework.beans.factory.ListableBeanFactory;
023import org.springframework.beans.factory.NoSuchBeanDefinitionException;
024
025/**
026 * Configuration interface to be implemented by most listable bean factories.
027 * In addition to {@link ConfigurableBeanFactory}, it provides facilities to
028 * analyze and modify bean definitions, and to pre-instantiate singletons.
029 *
030 * <p>This subinterface of {@link org.springframework.beans.factory.BeanFactory}
031 * is not meant to be used in normal application code: Stick to
032 * {@link org.springframework.beans.factory.BeanFactory} or
033 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
034 * use cases. This interface is just meant to allow for framework-internal
035 * plug'n'play even when needing access to bean factory configuration methods.
036 *
037 * @author Juergen Hoeller
038 * @since 03.11.2003
039 * @see org.springframework.context.support.AbstractApplicationContext#getBeanFactory()
040 */
041public interface ConfigurableListableBeanFactory
042                extends ListableBeanFactory, AutowireCapableBeanFactory, ConfigurableBeanFactory {
043
044        /**
045         * Ignore the given dependency type for autowiring:
046         * for example, String. Default is none.
047         * @param type the dependency type to ignore
048         */
049        void ignoreDependencyType(Class<?> type);
050
051        /**
052         * Ignore the given dependency interface for autowiring.
053         * <p>This will typically be used by application contexts to register
054         * dependencies that are resolved in other ways, like BeanFactory through
055         * BeanFactoryAware or ApplicationContext through ApplicationContextAware.
056         * <p>By default, only the BeanFactoryAware interface is ignored.
057         * For further types to ignore, invoke this method for each type.
058         * @param ifc the dependency interface to ignore
059         * @see org.springframework.beans.factory.BeanFactoryAware
060         * @see org.springframework.context.ApplicationContextAware
061         */
062        void ignoreDependencyInterface(Class<?> ifc);
063
064        /**
065         * Register a special dependency type with corresponding autowired value.
066         * <p>This is intended for factory/context references that are supposed
067         * to be autowirable but are not defined as beans in the factory:
068         * e.g. a dependency of type ApplicationContext resolved to the
069         * ApplicationContext instance that the bean is living in.
070         * <p>Note: There are no such default types registered in a plain BeanFactory,
071         * not even for the BeanFactory interface itself.
072         * @param dependencyType the dependency type to register. This will typically
073         * be a base interface such as BeanFactory, with extensions of it resolved
074         * as well if declared as an autowiring dependency (e.g. ListableBeanFactory),
075         * as long as the given value actually implements the extended interface.
076         * @param autowiredValue the corresponding autowired value. This may also be an
077         * implementation of the {@link org.springframework.beans.factory.ObjectFactory}
078         * interface, which allows for lazy resolution of the actual target value.
079         */
080        void registerResolvableDependency(Class<?> dependencyType, Object autowiredValue);
081
082        /**
083         * Determine whether the specified bean qualifies as an autowire candidate,
084         * to be injected into other beans which declare a dependency of matching type.
085         * <p>This method checks ancestor factories as well.
086         * @param beanName the name of the bean to check
087         * @param descriptor the descriptor of the dependency to resolve
088         * @return whether the bean should be considered as autowire candidate
089         * @throws NoSuchBeanDefinitionException if there is no bean with the given name
090         */
091        boolean isAutowireCandidate(String beanName, DependencyDescriptor descriptor)
092                        throws NoSuchBeanDefinitionException;
093
094        /**
095         * Return the registered BeanDefinition for the specified bean, allowing access
096         * to its property values and constructor argument value (which can be
097         * modified during bean factory post-processing).
098         * <p>A returned BeanDefinition object should not be a copy but the original
099         * definition object as registered in the factory. This means that it should
100         * be castable to a more specific implementation type, if necessary.
101         * <p><b>NOTE:</b> This method does <i>not</i> consider ancestor factories.
102         * It is only meant for accessing local bean definitions of this factory.
103         * @param beanName the name of the bean
104         * @return the registered BeanDefinition
105         * @throws NoSuchBeanDefinitionException if there is no bean with the given name
106         * defined in this factory
107         */
108        BeanDefinition getBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;
109
110        /**
111         * Return a unified view over all bean names managed by this factory.
112         * <p>Includes bean definition names as well as names of manually registered
113         * singleton instances, with bean definition names consistently coming first,
114         * analogous to how type/annotation specific retrieval of bean names works.
115         * @return the composite iterator for the bean names view
116         * @since 4.1.2
117         * @see #containsBeanDefinition
118         * @see #registerSingleton
119         * @see #getBeanNamesForType
120         * @see #getBeanNamesForAnnotation
121         */
122        Iterator<String> getBeanNamesIterator();
123
124        /**
125         * Clear the merged bean definition cache, removing entries for beans
126         * which are not considered eligible for full metadata caching yet.
127         * <p>Typically triggered after changes to the original bean definitions,
128         * e.g. after applying a {@link BeanFactoryPostProcessor}. Note that metadata
129         * for beans which have already been created at this point will be kept around.
130         * @since 4.2
131         * @see #getBeanDefinition
132         * @see #getMergedBeanDefinition
133         */
134        void clearMetadataCache();
135
136        /**
137         * Freeze all bean definitions, signalling that the registered bean definitions
138         * will not be modified or post-processed any further.
139         * <p>This allows the factory to aggressively cache bean definition metadata.
140         */
141        void freezeConfiguration();
142
143        /**
144         * Return whether this factory's bean definitions are frozen,
145         * i.e. are not supposed to be modified or post-processed any further.
146         * @return {@code true} if the factory's configuration is considered frozen
147         */
148        boolean isConfigurationFrozen();
149
150        /**
151         * Ensure that all non-lazy-init singletons are instantiated, also considering
152         * {@link org.springframework.beans.factory.FactoryBean FactoryBeans}.
153         * Typically invoked at the end of factory setup, if desired.
154         * @throws BeansException if one of the singleton beans could not be created.
155         * Note: This may have left the factory with some beans already initialized!
156         * Call {@link #destroySingletons()} for full cleanup in this case.
157         * @see #destroySingletons()
158         */
159        void preInstantiateSingletons() throws BeansException;
160
161}