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}