001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.beans.factory;
018:
019: import java.util.Map;
020:
021: import org.springframework.beans.BeansException;
022:
023: /**
024: * Extension of the {@link BeanFactory} interface to be implemented by bean factories
025: * that can enumerate all their bean instances, rather than attempting bean lookup
026: * by name one by one as requested by clients. BeanFactory implementations that
027: * preload all their bean definitions (such as XML-based factories) may implement
028: * this interface.
029: *
030: * <p>If this is a {@link HierarchicalBeanFactory}, the return values will <i>not</i>
031: * take any BeanFactory hierarchy into account, but will relate only to the beans
032: * defined in the current factory. Use the {@link BeanFactoryUtils} helper class
033: * to consider beans in ancestor factories too.
034: *
035: * <p>The methods in this interface will just respect bean definitions of this factory.
036: * They will ignore any singleton beans that have been registered by other means like
037: * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory}'s
038: * <code>registerSingleton</code> method, with the exception of
039: * <code>getBeanNamesOfType</code> and <code>getBeansOfType</code> which will check
040: * such manually registered singletons too. Of course, BeanFactory's <code>getBean</code>
041: * does allow transparent access to such special beans as well. However, in typical
042: * scenarios, all beans will be defined by external bean definitions anyway, so most
043: * applications don't need to worry about this differentation.
044: *
045: * <p><b>NOTE:</b> With the exception of <code>getBeanDefinitionCount</code>
046: * and <code>containsBeanDefinition</code>, the methods in this interface
047: * are not designed for frequent invocation. Implementations may be slow.
048: *
049: * @author Rod Johnson
050: * @author Juergen Hoeller
051: * @since 16 April 2001
052: * @see HierarchicalBeanFactory
053: * @see BeanFactoryUtils
054: */
055: public interface ListableBeanFactory extends BeanFactory {
056:
057: /**
058: * Check if this bean factory contains a bean definition with the given name.
059: * <p>Does not consider any hierarchy this factory may participate in,
060: * and ignores any singleton beans that have been registered by
061: * other means than bean definitions.
062: * @param beanName the name of the bean to look for
063: * @return if this bean factory contains a bean definition with the given name
064: * @see #containsBean
065: */
066: boolean containsBeanDefinition(String beanName);
067:
068: /**
069: * Return the number of beans defined in the factory.
070: * <p>Does not consider any hierarchy this factory may participate in,
071: * and ignores any singleton beans that have been registered by
072: * other means than bean definitions.
073: * @return the number of beans defined in the factory
074: */
075: int getBeanDefinitionCount();
076:
077: /**
078: * Return the names of all beans defined in this factory.
079: * <p>Does not consider any hierarchy this factory may participate in,
080: * and ignores any singleton beans that have been registered by
081: * other means than bean definitions.
082: * @return the names of all beans defined in this factory,
083: * or an empty array if none defined
084: */
085: String[] getBeanDefinitionNames();
086:
087: /**
088: * Return the names of beans matching the given type (including subclasses),
089: * judging from either bean definitions or the value of <code>getObjectType</code>
090: * in the case of FactoryBeans.
091: * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
092: * check nested beans which might match the specified type as well.
093: * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
094: * will get initialized. If the object created by the FactoryBean doesn't match,
095: * the raw FactoryBean itself will be matched against the type.
096: * <p>Does not consider any hierarchy this factory may participate in.
097: * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code>
098: * to include beans in ancestor factories too.
099: * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
100: * by other means than bean definitions.
101: * <p>This version of <code>getBeanNamesForType</code> matches all kinds of beans,
102: * be it singletons, prototypes, or FactoryBeans. In most implementations, the
103: * result will be the same as for <code>getBeanNamesOfType(type, true, true)</code>.
104: * <p>Bean names returned by this method should always return bean names <i>in the
105: * order of definition</i> in the backend configuration, as far as possible.
106: * @param type the class or interface to match, or <code>null</code> for all bean names
107: * @return the names of beans (or objects created by FactoryBeans) matching
108: * the given object type (including subclasses), or an empty array if none
109: * @see FactoryBean#getObjectType
110: * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class)
111: */
112: String[] getBeanNamesForType(Class type);
113:
114: /**
115: * Return the names of beans matching the given type (including subclasses),
116: * judging from either bean definitions or the value of <code>getObjectType</code>
117: * in the case of FactoryBeans.
118: * <p><b>NOTE: This method introspects top-level beans only.</b> It does <i>not</i>
119: * check nested beans which might match the specified type as well.
120: * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
121: * which means that FactoryBeans will get initialized. If the object created by the
122: * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
123: * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
124: * (which doesn't require initialization of each FactoryBean).
125: $ * <p>Does not consider any hierarchy this factory may participate in.
126: * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code>
127: * to include beans in ancestor factories too.
128: * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
129: * by other means than bean definitions.
130: * <p>Bean names returned by this method should always return bean names <i>in the
131: * order of definition</i> in the backend configuration, as far as possible.
132: * @param type the class or interface to match, or <code>null</code> for all bean names
133: * @param includePrototypes whether to include prototype beans too
134: * or just singletons (also applies to FactoryBeans)
135: * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
136: * <i>objects created by FactoryBeans</i> (or by factory methods with a
137: * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
138: * eagerly initialized to determine their type: So be aware that passing in "true"
139: * for this flag will initialize FactoryBeans and "factory-bean" references.
140: * @return the names of beans (or objects created by FactoryBeans) matching
141: * the given object type (including subclasses), or an empty array if none
142: * @see FactoryBean#getObjectType
143: * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
144: */
145: String[] getBeanNamesForType(Class type, boolean includePrototypes,
146: 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: */
176: Map getBeansOfType(Class 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 includePrototypes whether to include prototype 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: */
211: Map getBeansOfType(Class type, boolean includePrototypes,
212: boolean allowEagerInit) throws BeansException;
213:
214: }
|