ListableBeanFactory


1   /*
2    * Copyright 2002-2006 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.util.Map  ;
20  
21  import org.springframework.beans.BeansException;
22  
23  /**
24   * Extension of the BeanFactory interface to be implemented by bean factories
25   * that can enumerate all their bean instances, rather than attempting bean lookup
26   * by name one by one as requested by clients. BeanFactory implementations that
27   * preload all their beans (for example, DOM-based XML factories) may implement
28   * this interface. This interface is discussed in "Expert One-on-One J2EE Design
29   * and Development", by Rod Johnson.
30   *
31   * <p>If this is a HierarchicalBeanFactory, the return values will <i>not</i> take
32   * any BeanFactory hierarchy into account, but will relate only to the beans defined
33   * in the current factory. Use the BeanFactoryUtils helper class to consider beans
34   * 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   * ConfigurableBeanFactory's <code>registerSingleton</code> method, with the exception
39   * of <code>getBeanNamesOfType</code> and <code>getBeansOfType</code> which will check
40   * such manually registered singletons too. Of course, BeanFactory's <code>getBean</code>
41   * does allow transparent access to such special beans as well. However, in typical
42   * scenarios, all beans will be defined by external bean definitions anyway, so most
43   * applications don't need to worry about this differentation.
44   *
45   * <p>With the exception of <code>getBeanDefinitionCount</code> and
46   * <code>containsBeanDefinition</code>, the methods in this interface are
47   * not designed for frequent invocation. Implementations may be slow.
48   *
49   * @author Rod Johnson
50   * @author Juergen Hoeller
51   * @since 16 April 2001
52   * @see HierarchicalBeanFactory
53   * @see BeanFactoryUtils
54   * @see org.springframework.beans.factory.config.ConfigurableBeanFactory#registerSingleton
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       */
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       */
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       */
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>Does consider objects created by FactoryBeans, which means that FactoryBeans
93       * will get initialized. If the object created by the FactoryBean doesn't match,
94       * the raw FactoryBean itself will be matched against the type.
95       * <p>Does not consider any hierarchy this factory may participate in.
96       * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code>
97       * to include beans in ancestor factories too.
98       * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
99       * by other means than bean definitions.
100      * <p>This version of getBeanNamesForType matches all kinds of beans, be it
101      * singletons, prototypes, or FactoryBeans. In most implementations, the
102      * result will be the same as for <code>getBeanNamesOfType(type, true, true)</code>.
103      * <p>Bean names returned by this method should always return bean names <i>in the
104      * order of definition</i> in the backend configuration, as far as possible.
105      * @param type the class or interface to match, or <code>null</code> for all bean names
106      * @return the names of beans (or objects created by FactoryBeans) matching
107      * the given object type (including subclasses), or an empty array if none
108      * @see FactoryBean#getObjectType
109      * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class)
110      */
111     String  [] getBeanNamesForType(Class   type);
112 
113     /**
114      * Return the names of beans matching the given type (including subclasses),
115      * judging from either bean definitions or the value of <code>getObjectType</code>
116      * in the case of FactoryBeans.
117      * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
118      * which means that FactoryBeans will get initialized. If the object created by the
119      * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
120      * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
121      * (which doesn't require initialization of each FactoryBean).
122 $    * <p>Does not consider any hierarchy this factory may participate in.
123      * Use BeanFactoryUtils' <code>beanNamesForTypeIncludingAncestors</code>
124      * to include beans in ancestor factories too.
125      * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
126      * by other means than bean definitions.
127      * <p>Bean names returned by this method should always return bean names <i>in the
128      * order of definition</i> in the backend configuration, as far as possible.
129      * @param type the class or interface to match, or <code>null</code> for all bean names
130      * @param includePrototypes whether to include prototype beans too
131      * or just singletons (also applies to FactoryBeans)
132      * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
133      * <i>objects created by FactoryBeans</i> (or by factory methods with a
134      * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
135      * eagerly initialized to determine their type: So be aware that passing in "true"
136      * for this flag will initialize FactoryBeans and "factory-bean" references.
137      * @return the names of beans (or objects created by FactoryBeans) matching
138      * the given object type (including subclasses), or an empty array if none
139      * @see FactoryBean#getObjectType
140      * @see BeanFactoryUtils#beanNamesForTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
141      */
142     String  [] getBeanNamesForType(Class   type, boolean includePrototypes, boolean allowEagerInit);
143 
144     /**
145      * Return the bean instances that match the given object type (including
146      * subclasses), judging from either bean definitions or the value of
147      * <code>getObjectType</code> in the case of FactoryBeans.
148      * <p>Does consider objects created by FactoryBeans, which means that FactoryBeans
149      * will get initialized. If the object created by the FactoryBean doesn't match,
150      * the raw FactoryBean itself will be matched against the type.
151      * <p>Does not consider any hierarchy this factory may participate in.
152      * Use BeanFactoryUtils' <code>beansOfTypeIncludingAncestors</code>
153      * to include beans in ancestor factories too.
154      * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
155      * by other means than bean definitions.
156      * <p>This version of getBeansOfType matches all kinds of beans, be it
157      * singletons, prototypes, or FactoryBeans. In most implementations, the
158      * result will be the same as for <code>getBeansOfType(type, true, true)</code>.
159      * <p>The Map returned by this method should always return bean names and
160      * corresponding bean instances <i>in the order of definition</i> in the
161      * backend configuration, as far as possible. This will usually mean that
162      * either JDK 1.4 or Commons Collections needs to be available.
163      * @param type the class or interface to match, or <code>null</code> for all concrete beans
164      * @return a Map with the matching beans, containing the bean names as
165      * keys and the corresponding bean instances as values
166      * @throws BeansException if a bean could not be created
167      * @since 1.1.2
168      * @see FactoryBean#getObjectType
169      * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class)
170      */
171     Map   getBeansOfType(Class   type) throws BeansException;
172 
173     /**
174      * Return the bean instances that match the given object type (including
175      * subclasses), judging from either bean definitions or the value of
176      * <code>getObjectType</code> in the case of FactoryBeans.
177      * <p>Does consider objects created by FactoryBeans if the "allowEagerInit" flag is set,
178      * which means that FactoryBeans will get initialized. If the object created by the
179      * FactoryBean doesn't match, the raw FactoryBean itself will be matched against the
180      * type. If "allowEagerInit" is not set, only raw FactoryBeans will be checked
181      * (which doesn't require initialization of each FactoryBean).
182      * <p>Does not consider any hierarchy this factory may participate in.
183      * Use BeanFactoryUtils' <code>beansOfTypeIncludingAncestors</code>
184      * to include beans in ancestor factories too.
185      * <p>Note: Does <i>not</i> ignore singleton beans that have been registered
186      * by other means than bean definitions.
187      * <p>The Map returned by this method should always return bean names and
188      * corresponding bean instances <i>in the order of definition</i> in the
189      * backend configuration, as far as possible. This will usually mean that
190      * either JDK 1.4 or Commons Collections needs to be available.
191      * @param type the class or interface to match, or <code>null</code> for all concrete beans
192      * @param includePrototypes whether to include prototype beans too
193      * or just singletons (also applies to FactoryBeans)
194      * @param allowEagerInit whether to initialize <i>lazy-init singletons</i> and
195      * <i>objects created by FactoryBeans</i> (or by factory methods with a
196      * "factory-bean" reference) for the type check. Note that FactoryBeans need to be
197      * eagerly initialized to determine their type: So be aware that passing in "true"
198      * for this flag will initialize FactoryBeans and "factory-bean" references.
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      * @see FactoryBean#getObjectType
203      * @see BeanFactoryUtils#beansOfTypeIncludingAncestors(ListableBeanFactory, Class, boolean, boolean)
204      */
205     Map   getBeansOfType(Class   type, boolean includePrototypes, boolean allowEagerInit)
206         throws BeansException;
207 
208 }
209
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags