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