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;
018
019import java.lang.annotation.Annotation;
020import java.util.Map;
021
022import org.springframework.beans.BeansException;
023import org.springframework.core.ResolvableType;
024
025/**
026 * Extension of the {@link BeanFactory} interface to be implemented by bean factories
027 * that can enumerate all their bean instances, rather than attempting bean lookup
028 * by name one by one as requested by clients. BeanFactory implementations that
029 * preload all their bean definitions (such as XML-based factories) may implement
030 * this interface.
031 *
032 * <p>If this is a {@link HierarchicalBeanFactory}, the return values will <i>not</i>
033 * take any BeanFactory hierarchy into account, but will relate only to the beans
034 * defined in the current factory. Use the {@link BeanFactoryUtils} helper class
035 * to consider beans in ancestor factories too.
036 *
037 * <p>The methods in this interface will just respect bean definitions of this factory.
038 * They will ignore any singleton beans that have been registered by other means like
039 * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}'s
040 * {@code registerSingleton} method, with the exception of
041 * {@code getBeanNamesOfType} and {@code getBeansOfType} which will check
042 * such manually registered singletons too. Of course, BeanFactory's {@code getBean}
043 * does allow transparent access to such special beans as well. However, in typical
044 * scenarios, all beans will be defined by external bean definitions anyway, so most
045 * applications don't need to worry about this differentiation.
046 *
047 * <p><b>NOTE:</b> With the exception of {@code getBeanDefinitionCount}
048 * and {@code containsBeanDefinition}, the methods in this interface
049 * are not designed for frequent invocation. Implementations may be slow.
050 *
051 * @author Rod Johnson
052 * @author Juergen Hoeller
053 * @since 16 April 2001
054 * @see HierarchicalBeanFactory
055 * @see BeanFactoryUtils
056 */
057public interface ListableBeanFactory extends BeanFactory {
058
059        /**
060         * Check if this bean factory contains a bean definition with the given name.
061         * <p>Does not consider any hierarchy this factory may participate in,
062         * and ignores any singleton beans that have been registered by
063         * other means than bean definitions.
064         * @param beanName the name of the bean to look for
065         * @return if this bean factory contains a bean definition with the given name
066         * @see #containsBean
067         */
068        boolean containsBeanDefinition(String beanName);
069
070        /**
071         * Return the number of beans defined in the factory.
072         * <p>Does not consider any hierarchy this factory may participate in,
073         * and ignores any singleton beans that have been registered by
074         * other means than bean definitions.
075         * @return the number of beans defined in the factory
076         */
077        int getBeanDefinitionCount();
078
079        /**
080         * Return the names of all beans defined in this factory.
081         * <p>Does not consider any hierarchy this factory may participate in,
082         * and ignores any singleton beans that have been registered by
083         * other means than bean definitions.
084         * @return the names of all beans defined in this factory,
085         * or an empty array if none defined
086         */
087        String[] getBeanDefinitionNames();
088
089        /**
090         * Return the names of beans matching the given type (including subclasses),
091         * judging from either bean definitions or the value of {@code getObjectType}
092         * in the case of FactoryBeans.
093         * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
094         * check nested beans which might match the specified type as well.
095         * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
096         * will get initialized. If the object created by the FactoryBean doesn't match,
097         * the raw FactoryBean itself will be matched against the type.
098         * <p>Does not consider any hierarchy this factory may participate in.
099         * Use BeanFactoryUtils' {@code beanNamesForTypeIncludingAncestors}
100         * to include beans in ancestor factories too.
101         * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
102         * by other means than bean definitions.
103         * <p>This version of {@code getBeanNamesForType} matches all kinds of beans,
104         * be it singletons, prototypes, or FactoryBeans. In most implementations, the
105         * result will be the same as for {@code getBeanNamesForType(type, true, true)}.
106         * <p>Bean names returned by this method should always return bean names <i>in the
107         * order of definition</i> in the backend configuration, as far as possible.
108         * @param type the class or interface to match, or {@code null} for all bean names
109         * @return the names of beans (or objects created by FactoryBeans) matching
110         * the given object type (including subclasses), or an empty array if none
111         * @since 4.2
112         * @see #isTypeMatch(String, ResolvableType)
113         * @see FactoryBean#getObjectType
114         * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, ResolvableType)
115         */
116        String[] getBeanNamesForType(ResolvableType type);
117
118        /**
119         * Return the names of beans matching the given type (including subclasses),
120         * judging from either bean definitions or the value of {@code getObjectType}
121         * in the case of FactoryBeans.
122         * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
123         * check nested beans which might match the specified type as well.
124         * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
125         * will get initialized. If the object created by the FactoryBean doesn't match,
126         * the raw FactoryBean itself will be matched against the type.
127         * <p>Does not consider any hierarchy this factory may participate in.
128         * Use BeanFactoryUtils' {@code beanNamesForTypeIncludingAncestors}
129         * to include beans in ancestor factories too.
130         * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
131         * by other means than bean definitions.
132         * <p>This version of {@code getBeanNamesForType} matches all kinds of beans,
133         * be it singletons, prototypes, or FactoryBeans. In most implementations, the
134         * result will be the same as for {@code getBeanNamesForType(type, true, true)}.
135         * <p>Bean names returned by this method should always return bean names <i>in the
136         * order of definition</i> in the backend configuration, as far as possible.
137         * @param type the class or interface to match, or {@code null} for all bean names
138         * @return the names of beans (or objects created by FactoryBeans) matching
139         * the given object type (including subclasses), or an empty array if none
140         * @see FactoryBean#getObjectType
141         * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class)
142         */
143        String[] getBeanNamesForType(Class<?> type);
144
145        /**
146         * Return the names of beans matching the given type (including subclasses),
147         * judging from either bean definitions or the value of {@code getObjectType}
148         * in the case of FactoryBeans.
149         * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
150         * check nested beans which might match the specified type as well.
151         * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
152         * which means that FactoryBeans will get initialized. If the object created by the
153         * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
154         * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
155         * (which doesn't require initialization of each FactoryBean).
156         * <p>Does not consider any hierarchy this factory may participate in.
157         * Use BeanFactoryUtils' {@code beanNamesForTypeIncludingAncestors}
158         * to include beans in ancestor factories too.
159         * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
160         * by other means than bean definitions.
161         * <p>Bean names returned by this method should always return bean names <i>in the
162         * order of definition</i> in the backend configuration, as far as possible.
163         * @param type the class or interface to match, or {@code null} for all bean names
164         * @param includeNonSingletons whether to include prototype or scoped beans too
165         * or just singletons (also applies to FactoryBeans)
166         * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
167         * <i>objects created by FactoryBeans</i> (or by factory methods with a
168         * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
169         * eagerly initialized to determine their type: So be aware that passing in "true"
170         * for this flag will initialize FactoryBeans and "factory-bean" references.
171         * @return the names of beans (or objects created by FactoryBeans) matching
172         * the given object type (including subclasses), or an empty array if none
173         * @see FactoryBean#getObjectType
174         * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
175         */
176        String[] getBeanNamesForType(Class<?> type, boolean includeNonSingletons, boolean allowEagerInit);
177
178        /**
179         * Return the bean instances that match the given object type (including
180         * subclasses), judging from either bean definitions or the value of
181         * {@code getObjectType} in the case of FactoryBeans.
182         * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
183         * check nested beans which might match the specified type as well.
184         * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
185         * will get initialized. If the object created by the FactoryBean doesn't match,
186         * the raw FactoryBean itself will be matched against the type.
187         * <p>Does not consider any hierarchy this factory may participate in.
188         * Use BeanFactoryUtils' {@code beansOfTypeIncludingAncestors}
189         * to include beans in ancestor factories too.
190         * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
191         * by other means than bean definitions.
192         * <p>This version of getBeansOfType matches all kinds of beans, be it
193         * singletons, prototypes, or FactoryBeans. In most implementations, the
194         * result will be the same as for {@code getBeansOfType(type, true, true)}.
195         * <p>The Map returned by this method should always return bean names and
196         * corresponding bean instances <i>in the order of definition</i> in the
197         * backend configuration, as far as possible.
198         * @param type the class or interface to match, or {@code null} for all concrete beans
199         * @return a Map with the matching beans, containing the bean names as
200         * keys and the corresponding bean instances as values
201         * @throws BeansException if a bean could not be created
202         * @since 1.1.2
203         * @see FactoryBean#getObjectType
204         * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class)
205         */
206        <T> Map<String, T> getBeansOfType(Class<T> type) throws BeansException;
207
208        /**
209         * Return the bean instances that match the given object type (including
210         * subclasses), judging from either bean definitions or the value of
211         * {@code getObjectType} in the case of FactoryBeans.
212         * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
213         * check nested beans which might match the specified type as well.
214         * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
215         * which means that FactoryBeans will get initialized. If the object created by the
216         * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
217         * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
218         * (which doesn't require initialization of each FactoryBean).
219         * <p>Does not consider any hierarchy this factory may participate in.
220         * Use BeanFactoryUtils' {@code beansOfTypeIncludingAncestors}
221         * to include beans in ancestor factories too.
222         * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
223         * by other means than bean definitions.
224         * <p>The Map returned by this method should always return bean names and
225         * corresponding bean instances <i>in the order of definition</i> in the
226         * backend configuration, as far as possible.
227         * @param type the class or interface to match, or {@code null} for all concrete beans
228         * @param includeNonSingletons whether to include prototype or scoped beans too
229         * or just singletons (also applies to FactoryBeans)
230         * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
231         * <i>objects created by FactoryBeans</i> (or by factory methods with a
232         * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
233         * eagerly initialized to determine their type: So be aware that passing in "true"
234         * for this flag will initialize FactoryBeans and "factory-bean" references.
235         * @return a Map with the matching beans, containing the bean names as
236         * keys and the corresponding bean instances as values
237         * @throws BeansException if a bean could not be created
238         * @see FactoryBean#getObjectType
239         * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
240         */
241        <T> Map<String, T> getBeansOfType(Class<T> type, boolean includeNonSingletons, boolean allowEagerInit)
242                        throws BeansException;
243
244        /**
245         * Find all names of beans which are annotated with the supplied {@link Annotation}
246         * type, without creating corresponding bean instances yet.
247         * <p>Note that this method considers objects created by FactoryBeans, which means
248         * that FactoryBeans will get initialized in order to determine their object type.
249         * @param annotationType the type of annotation to look for
250         * @return the names of all matching beans
251         * @since 4.0
252         * @see #findAnnotationOnBean
253         */
254        String[] getBeanNamesForAnnotation(Class<? extends Annotation> annotationType);
255
256        /**
257         * Find all beans which are annotated with the supplied {@link Annotation} type,
258         * returning a Map of bean names with corresponding bean instances.
259         * <p>Note that this method considers objects created by FactoryBeans, which means
260         * that FactoryBeans will get initialized in order to determine their object type.
261         * @param annotationType the type of annotation to look for
262         * @return a Map with the matching beans, containing the bean names as
263         * keys and the corresponding bean instances as values
264         * @throws BeansException if a bean could not be created
265         * @since 3.0
266         * @see #findAnnotationOnBean
267         */
268        Map<String, Object> getBeansWithAnnotation(Class<? extends Annotation> annotationType) throws BeansException;
269
270        /**
271         * Find an {@link Annotation} of {@code annotationType} on the specified bean,
272         * traversing its interfaces and super classes if no annotation can be found on
273         * the given class itself.
274         * @param beanName the name of the bean to look for annotations on
275         * @param annotationType the type of annotation to look for
276         * @return the annotation of the given type if found, or {@code null} otherwise
277         * @throws NoSuchBeanDefinitionException if there is no bean with the given name
278         * @since 3.0
279         * @see #getBeanNamesForAnnotation
280         * @see #getBeansWithAnnotation
281         */
282        <A extends Annotation> A findAnnotationOnBean(String beanName, Class<A> annotationType)
283                        throws NoSuchBeanDefinitionException;
284
285}