1 /* 2 * Copyright 2002-2009 the original author or authors. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.springframework.beans.factory; 18 19 import java.lang.annotation.Annotation; 20 import java.util.Map; 21 22 import org.springframework.beans.BeansException; 23 24 /** 25 * Extension of the {@link BeanFactory} interface to be implemented by bean factories 26 * that can enumerate all their bean instances, rather than attempting bean lookup 27 * by name one by one as requested by clients. BeanFactory implementations that 28 * preload all their bean definitions (such as XML-based factories) may implement 29 * this interface. 30 * 31 * <p>If this is a {@link HierarchicalBeanFactory}, the return values will <i>not</i> 32 * take any BeanFactory hierarchy into account, but will relate only to the beans 33 * defined in the current factory. Use the {@link BeanFactoryUtils} helper class 34 * to consider beans in ancestor factories too. 35 * 36 * <p>The methods in this interface will just respect bean definitions of this factory. 37 * They will ignore any singleton beans that have been registered by other means like 38 * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}'s 39 * <code>registerSingleton</code> method, with the exception of 40 * <code>getBeanNamesOfType</code> and <code>getBeansOfType</code> which will check 41 * such manually registered singletons too. Of course, BeanFactory's <code>getBean</code> 42 * does allow transparent access to such special beans as well. However, in typical 43 * scenarios, all beans will be defined by external bean definitions anyway, so most 44 * applications don't need to worry about this differentation. 45 * 46 * <p><b>NOTE:</b> With the exception of <code>getBeanDefinitionCount</code> 47 * and <code>containsBeanDefinition</code>, the methods in this interface 48 * are not designed for frequent invocation. Implementations may be slow. 49 * 50 * @author Rod Johnson 51 * @author Juergen Hoeller 52 * @since 16 April 2001 53 * @see HierarchicalBeanFactory 54 * @see BeanFactoryUtils 55 */ 56 public interface ListableBeanFactory extends BeanFactory { 57 58 /** 59 * Check if this bean factory contains a bean definition with the given name. 60 * <p>Does not consider any hierarchy this factory may participate in, 61 * and ignores any singleton beans that have been registered by 62 * other means than bean definitions. 63 * @param beanName the name of the bean to look for 64 * @return if this bean factory contains a bean definition with the given name 65 * @see #containsBean 66 */ containsBeanDefinition(String beanName)67 boolean containsBeanDefinition(String beanName); 68 69 /** 70 * Return the number of beans defined in the factory. 71 * <p>Does not consider any hierarchy this factory may participate in, 72 * and ignores any singleton beans that have been registered by 73 * other means than bean definitions. 74 * @return the number of beans defined in the factory 75 */ getBeanDefinitionCount()76 int getBeanDefinitionCount(); 77 78 /** 79 * Return the names of all beans defined in this factory. 80 * <p>Does not consider any hierarchy this factory may participate in, 81 * and ignores any singleton beans that have been registered by 82 * other means than bean definitions. 83 * @return the names of all beans defined in this factory, 84 * or an empty array if none defined 85 */ getBeanDefinitionNames()86 String[] getBeanDefinitionNames(); 87 88 /** 89 * Return the names of beans matching the given type (including subclasses), 90 * judging from either bean definitions or the value of <code>getObjectType</code> 91 * in the case of FactoryBeans. 92 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i> 93 * check nested beans which might match the specified type as well. 94 * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans 95 * will get initialized. If the object created by the FactoryBean doesn't match, 96 * the raw FactoryBean itself will be matched against the type. 97 * <p>Does not consider any hierarchy this factory may participate in. 98 * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code> 99 * to include beans in ancestor factories too. 100 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered 101 * by other means than bean definitions. 102 * <p>This version of <code>getBeanNamesForType</code> matches all kinds of beans, 103 * be it singletons, prototypes, or FactoryBeans. In most implementations, the 104 * result will be the same as for <code>getBeanNamesOfType(type, true, true)</code>. 105 * <p>Bean names returned by this method should always return bean names <i>in the 106 * order of definition</i> in the backend configuration, as far as possible. 107 * @param type the class or interface to match, or <code>null</code> for all bean names 108 * @return the names of beans (or objects created by FactoryBeans) matching 109 * the given object type (including subclasses), or an empty array if none 110 * @see FactoryBean#getObjectType 111 * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class) 112 */ getBeanNamesForType(Class<?> type)113 String[] getBeanNamesForType(Class<?> type); 114 115 /** 116 * Return the names of beans matching the given type (including subclasses), 117 * judging from either bean definitions or the value of <code>getObjectType</code> 118 * in the case of FactoryBeans. 119 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i> 120 * check nested beans which might match the specified type as well. 121 * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set, 122 * which means that FactoryBeans will get initialized. If the object created by the 123 * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the 124 * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked 125 * (which doesn't require initialization of each FactoryBean). 126 * <p>Does not consider any hierarchy this factory may participate in. 127 * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code> 128 * to include beans in ancestor factories too. 129 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered 130 * by other means than bean definitions. 131 * <p>Bean names returned by this method should always return bean names <i>in the 132 * order of definition</i> in the backend configuration, as far as possible. 133 * @param type the class or interface to match, or <code>null</code> for all bean names 134 * @param includeNonSingletons whether to include prototype or scoped beans too 135 * or just singletons (also applies to FactoryBeans) 136 * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and 137 * <i>objects created by FactoryBeans</i> (or by factory methods with a 138 * "factory-bean" reference) for the type check. Note that FactoryBeans need to be 139 * eagerly initialized to determine their type: So be aware that passing in "true" 140 * for this flag will initialize FactoryBeans and "factory-bean" references. 141 * @return the names of beans (or objects created by FactoryBeans) matching 142 * the given object type (including subclasses), or an empty array if none 143 * @see FactoryBean#getObjectType 144 * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean) 145 */ getBeanNamesForType(Class<?> type, boolean includeNonSingletons, boolean allowEagerInit)146 String[] getBeanNamesForType(Class<?> type, boolean includeNonSingletons, boolean allowEagerInit); 147 148 /** 149 * Return the bean instances that match the given object type (including 150 * subclasses), judging from either bean definitions or the value of 151 * <code>getObjectType</code> in the case of FactoryBeans. 152 * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i> 153 * check nested beans which might match the specified type as well. 154 * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans 155 * will get initialized. If the object created by the FactoryBean doesn't match, 156 * the raw FactoryBean itself will be matched against the type. 157 * <p>Does not consider any hierarchy this factory may participate in. 158 * Use BeanFactoryUtils' <code>beansOfTypeIncludingAncestors</code> 159 * to include beans in ancestor factories too. 160 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered 161 * by other means than bean definitions. 162 * <p>This version of getBeansOfType matches all kinds of beans, be it 163 * singletons, prototypes, or FactoryBeans. In most implementations, the 164 * result will be the same as for <code>getBeansOfType(type, true, true)</code>. 165 * <p>The Map returned by this method should always return bean names and 166 * corresponding bean instances <i>in the order of definition</i> in the 167 * backend configuration, as far as possible. 168 * @param type the class or interface to match, or <code>null</code> for all concrete beans 169 * @return a Map with the matching beans, containing the bean names as 170 * keys and the corresponding bean instances as values 171 * @throws BeansException if a bean could not be created 172 * @since 1.1.2 173 * @see FactoryBean#getObjectType 174 * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class) 175 */ getBeansOfType(Class<T> type)176 <T> Map<String, T> getBeansOfType(Class<T> type) throws BeansException; 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</code> 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 if the "allowEagerInit" flag is set, 185 * which means that FactoryBeans will get initialized. If the object created by the 186 * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the 187 * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked 188 * (which doesn't require initialization of each FactoryBean). 189 * <p>Does not consider any hierarchy this factory may participate in. 190 * Use BeanFactoryUtils' <code>beansOfTypeIncludingAncestors</code> 191 * to include beans in ancestor factories too. 192 * <p>Note: Does <i>not</i> ignore singleton beans that have been registered 193 * by other means than bean definitions. 194 * <p>The Map returned by this method should always return bean names and 195 * corresponding bean instances <i>in the order of definition</i> in the 196 * backend configuration, as far as possible. 197 * @param type the class or interface to match, or <code>null</code> for all concrete beans 198 * @param includeNonSingletons whether to include prototype or scoped beans too 199 * or just singletons (also applies to FactoryBeans) 200 * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and 201 * <i>objects created by FactoryBeans</i> (or by factory methods with a 202 * "factory-bean" reference) for the type check. Note that FactoryBeans need to be 203 * eagerly initialized to determine their type: So be aware that passing in "true" 204 * for this flag will initialize FactoryBeans and "factory-bean" references. 205 * @return a Map with the matching beans, containing the bean names as 206 * keys and the corresponding bean instances as values 207 * @throws BeansException if a bean could not be created 208 * @see FactoryBean#getObjectType 209 * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean) 210 */ getBeansOfType(Class<T> type, boolean includeNonSingletons, boolean allowEagerInit)211 <T> Map<String, T> getBeansOfType(Class<T> type, boolean includeNonSingletons, boolean allowEagerInit) 212 throws BeansException; 213 214 /** 215 * Find all beans whose <code>Class</code> has the supplied {@link java.lang.annotation.Annotation} type. 216 * @param annotationType the type of annotation to look for 217 * @return a Map with the matching beans, containing the bean names as 218 * keys and the corresponding bean instances as values 219 * @throws BeansException if a bean could not be created 220 */ getBeansWithAnnotation(Class<? extends Annotation> annotationType)221 Map<String, Object> getBeansWithAnnotation(Class<? extends Annotation> annotationType) 222 throws BeansException; 223 224 /** 225 * Find a {@link Annotation} of <code>annotationType</code> on the specified 226 * bean, traversing its interfaces and super classes if no annotation can be 227 * found on the given class itself. 228 * @param beanName the name of the bean to look for annotations on 229 * @param annotationType the annotation class to look for 230 * @return the annotation of the given type found, or <code>null</code> 231 */ findAnnotationOnBean(String beanName, Class<A> annotationType)232 <A extends Annotation> A findAnnotationOnBean(String beanName, Class<A> annotationType); 233 234 } 235