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