Java > Open Source Codes > org > springframework > beans > factory > access > SingletonBeanFactoryLocator


1 /*
2  * Copyright 2002-2007 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.access;
18
19 import java.io.IOException ;
20 import java.util.HashMap ;
21 import java.util.Map ;
22
23 import org.apache.commons.logging.Log;
24 import org.apache.commons.logging.LogFactory;
25
26 import org.springframework.beans.BeansException;
27 import org.springframework.beans.FatalBeanException;
28 import org.springframework.beans.factory.BeanDefinitionStoreException;
29 import org.springframework.beans.factory.BeanFactory;
30 import org.springframework.beans.factory.config.ConfigurableBeanFactory;
31 import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
32 import org.springframework.beans.factory.support.DefaultListableBeanFactory;
33 import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
34 import org.springframework.core.io.Resource;
35 import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
36 import org.springframework.core.io.support.ResourcePatternResolver;
37
38 /**
39  * <p>Keyed-singleton implementation of BeanFactoryLocator, which accesses shared
40  * Spring factory instances.</p>
41  *
42  * <p>Please see the warning in BeanFactoryLocator's javadoc about appropriate usage
43  * of singleton style BeanFactoryLocator implementations. It is the opinion of the
44  * Spring team that the use of this class and similar classes is unnecessary except
45  * (sometimes) for a small amount of glue code. Excessive usage will lead to code
46  * that is more tightly coupled, and harder to modify or test.</p>
47  *
48  * <p>In this implementation, a BeanFactory is built up from one or more XML
49  * definition file fragments, accessed as resources. The default resource name
50  * searched for is 'classpath*:beanRefFactory.xml', with the Spring-standard
51  * 'classpath*:' prefix ensuring that if the classpath contains multiple copies
52  * of this file (perhaps one in each component jar) they will be combined. To
53  * override the default resource name, instead of using the no-arg
54  * {@link #getInstance()} method, use the {@link #getInstance(String selector)}
55  * variant, which will treat the 'selector' argument as the resource name to
56  * search for.</p>
57  *
58  * <p>The purpose of this 'outer' BeanFactory is to create and hold a copy of one
59  * or more 'inner' BeanFactory or ApplicationContext instances, and allow those
60  * to be obtained either directly or via an alias. As such, this class provides
61  * both singleton style access to one or more BeanFactories/ApplicationContexts,
62  * and also a level of indirection, allowing multiple pieces of code, which are
63  * not able to work in a Dependency Injection fashion, to refer to and use the
64  * same target BeanFactory/ApplicationContext instance(s), by different names.<p>
65  *
66  * <p>Consider an example application scenario:
67  *
68  * <ul>
69  * <li><code>com.mycompany.myapp.util.applicationContext.xml</code> -
70  * ApplicationContext definition file which defines beans for 'util' layer.
71  * <li><code>com.mycompany.myapp.dataaccess-applicationContext.xml</code> -
72  * ApplicationContext definition file which defines beans for 'data access' layer.
73  * Depends on the above.
74  * <li><code>com.mycompany.myapp.services.applicationContext.xml</code> -
75  * ApplicationContext definition file which defines beans for 'services' layer.
76  * Depends on the above.
77  * </ul>
78  *
79  * <p>In an ideal scenario, these would be combined to create one ApplicationContext,
80  * or created as three hierarchical ApplicationContexts, by one piece of code
81  * somewhere at application startup (perhaps a Servlet filter), from which all other
82  * code in the application would flow, obtained as beans from the context(s). However
83  * when third party code enters into the picture, things can get problematic. If the
84  * third party code needs to create user classes, which should normally be obtained
85  * from a Spring BeanFactory/ApplicationContext, but can handle only newInstance()
86  * style object creation, then some extra work is required to actually access and
87  * use object from a BeanFactory/ApplicationContext. One solutions is to make the
88  * class created by the third party code be just a stub or proxy, which gets the
89  * real object from a BeanFactory/ApplicationContext, and delegates to it. However,
90  * it is is not normally workable for the stub to create the BeanFactory on each
91  * use, as depending on what is inside it, that can be an expensive operation.
92  * Additionally, there is a fairly tight coupling between the stub and the name of
93  * the definition resource for the BeanFactory/ApplicationContext. This is where
94  * SingletonBeanFactoryLocator comes in. The stub can obtain a
95  * SingletonBeanFactoryLocator instance, which is effectively a singleton, and
96  * ask it for an appropriate BeanFactory. A subsequent invocation (assuming the
97  * same class loader is involved) by the stub or another piece of code, will obtain
98  * the same instance. The simple aliasing mechanism allows the context to be asked
99  * for by a name which is appropriate for (or describes) the user. The deployer can
100  * match alias names to actual context names.
101  *
102  * <p>Another use of SingletonBeanFactoryLocator, is to demand-load/use one or more
103  * BeanFactories/ApplicationContexts. Because the definiiton can contain one of more
104  * BeanFactories/ApplicationContexts, which can be independent or in a hierarchy, if
105  * they are set to lazy-initialize, they will only be created when actually requested
106  * for use.
107  *
108  * <p>Given the above-mentioned three ApplicationContexts, consider the simplest
109  * SingletonBeanFactoryLocator usage scenario, where there is only one single
110  * <code>beanRefFactory.xml</code> definition file:
111  *
112  * <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?>
113  * &lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans_2_0.dtd">
114  *
115  * &lt;beans>
116  *
117  * &lt;bean id="com.mycompany.myapp"
118  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
119  * &lt;constructor-arg>
120  * &lt;list>
121  * &lt;value>com/mycompany/myapp/util/applicationContext.xml&lt;/value>
122  * &lt;value>com/mycompany/myapp/dataaccess/applicationContext.xml&lt;/value>
123  * &lt;value>com/mycompany/myapp/dataaccess/services.xml&lt;/value>
124  * &lt;/list>
125  * &lt;/constructor-arg>
126  * &lt;/bean>
127  *
128  * &lt;/beans>
129  * </pre>
130  *
131  * The client code is as simple as:
132  *
133  * <pre class="code">
134  * BeanFactoryLocator bfl = SingletonBeanFactoryLocator.getInstance();
135  * BeanFactoryReference bf = bfl.useBeanFactory("com.mycompany.myapp");
136  * // now use some bean from factory
137  * MyClass zed = bf.getFactory().getBean("mybean");
138  * </pre>
139  *
140  * Another relatively simple variation of the <code>beanRefFactory.xml</code> definition file could be:
141  *
142  * <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?>
143  * &lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans_2_0.dtd">
144  *
145  * &lt;beans>
146  *
147  * &lt;bean id="com.mycompany.myapp.util" lazy-init="true"
148  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
149  * &lt;constructor-arg>
150  * &lt;value>com/mycompany/myapp/util/applicationContext.xml&lt;/value>
151  * &lt;/constructor-arg>
152  * &lt;/bean>
153  *
154  * &lt;!-- child of above -->
155  * &lt;bean id="com.mycompany.myapp.dataaccess" lazy-init="true"
156  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
157  * &lt;constructor-arg>
158  * &lt;list>&lt;value>com/mycompany/myapp/dataaccess/applicationContext.xml&lt;/value>&lt;/list>
159  * &lt;/constructor-arg>
160  * &lt;constructor-arg>
161  * &lt;ref bean="com.mycompany.myapp.util"/>
162  * &lt;/constructor-arg>
163  * &lt;/bean>
164  *
165  * &lt;!-- child of above -->
166  * &lt;bean id="com.mycompany.myapp.services" lazy-init="true"
167  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
168  * &lt;constructor-arg>
169  * &lt;list>&lt;value>com/mycompany/myapp/dataaccess.services.xml&lt;/value>&lt;/value>
170  * &lt;/constructor-arg>
171  * &lt;constructor-arg>
172  * &lt;ref bean="com.mycompany.myapp.dataaccess"/>
173  * &lt;/constructor-arg>
174  * &lt;/bean>
175  *
176  * &lt;!-- define an alias -->
177  * &lt;bean id="com.mycompany.myapp.mypackage"
178  * class="java.lang.String">
179  * &lt;constructor-arg>
180  * &lt;value>com.mycompany.myapp.services&lt;/value>
181  * &lt;/constructor-arg>
182  * &lt;/bean>
183  *
184  * &lt;/beans>
185  * </pre>
186  *
187  * <p>In this example, there is a hierarchy of three contexts created. The (potential)
188  * advantage is that if the lazy flag is set to true, a context will only be created
189  * if it's actually used. If there is some code that is only needed some of the time,
190  * this mechanism can save some resources. Additionally, an alias to the last context
191  * has been created. Aliases allow usage of the idiom where client code asks for a
192  * context with an id which represents the package or module the code is in, and the
193  * actual definition file(s) for the SingletonBeanFactoryLocator maps that id to
194  * a real context id.
195  *
196  * <p>A final example is more complex, with a <code>beanRefFactory.xml</code> for every module.
197  * All the files are automatically combined to create the final definition.
198  *
199  * <p><code>beanRefFactory.xml</code> file inside jar for util module:
200  *
201  * <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?>
202  * &lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans_2_0.dtd">
203  *
204  * &lt;beans>
205  * &lt;bean id="com.mycompany.myapp.util" lazy-init="true"
206  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
207  * &lt;constructor-arg>
208  * &lt;value>com/mycompany/myapp/util/applicationContext.xml&lt;/value>
209  * &lt;/constructor-arg>
210  * &lt;/bean>
211  * &lt;/beans>
212  * </pre>
213  *
214  * <code>beanRefFactory.xml</code> file inside jar for data-access module:<br>
215  *
216  * <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?>
217  * &lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans_2_0.dtd">
218  *
219  * &lt;beans>
220  * &lt;!-- child of util -->
221  * &lt;bean id="com.mycompany.myapp.dataaccess" lazy-init="true"
222  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
223  * &lt;constructor-arg>
224  * &lt;list>&lt;value>com/mycompany/myapp/dataaccess/applicationContext.xml&lt;/value>&lt;/list>
225  * &lt;/constructor-arg>
226  * &lt;constructor-arg>
227  * &lt;ref bean="com.mycompany.myapp.util"/>
228  * &lt;/constructor-arg>
229  * &lt;/bean>
230  * &lt;/beans>
231  * </pre>
232  *
233  * <code>beanRefFactory.xml</code> file inside jar for services module:
234  *
235  * <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?>
236  * &lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans_2_0.dtd">
237  *
238  * &lt;beans>
239  * &lt;!-- child of data-access -->
240  * &lt;bean id="com.mycompany.myapp.services" lazy-init="true"
241  * class="org.springframework.context.support.ClassPathXmlApplicationContext">
242  * &lt;constructor-arg>
243  * &lt;list>&lt;value>com/mycompany/myapp/dataaccess/services.xml&lt;/value>&lt;/list>
244  * &lt;/constructor-arg>
245  * &lt;constructor-arg>
246  * &lt;ref bean="com.mycompany.myapp.dataaccess"/>
247  * &lt;/constructor-arg>
248  * &lt;/bean>
249  * &lt;/beans>
250  * </pre>
251  *
252  * <code>beanRefFactory.xml</code> file inside jar for mypackage module. This doesn't
253  * create any of its own contexts, but allows the other ones to be referred to be
254  * a name known to this module:
255  *
256  * <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?>
257  * &lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans_2_0.dtd">
258  *
259  * &lt;beans>
260  * &lt;!-- define an alias for "com.mycompany.myapp.services" -->
261  * &lt;alias name="com.mycompany.myapp.services" alias="com.mycompany.myapp.mypackage"/&gt;
262  * &lt;/beans>
263  * </pre>
264  *
265  * @author Colin Sampaleanu
266  * @author Juergen Hoeller
267  * @see org.springframework.context.access.ContextSingletonBeanFactoryLocator
268  * @see org.springframework.context.access.DefaultLocatorFactory
269  */
270 public class SingletonBeanFactoryLocator implements BeanFactoryLocator {
271
272     private static final String BEANS_REFS_XML_NAME = "classpath*:beanRefFactory.xml";
273
274     protected static final Log logger = LogFactory.getLog(SingletonBeanFactoryLocator.class);
275
276     // the keyed singleton instances
277 private static Map instances = new HashMap ();
278
279
280     /**
281      * Returns an instance which uses the default "classpath*:beanRefFactory.xml",
282      * as the name of the definition file(s). All resources returned by calling the
283      * current thread's context classloader's getResources() method with this name
284      * will be combined to create a definition, which is just a BeanFactory.
285      */
286     public static BeanFactoryLocator getInstance() throws FatalBeanException {
287         return getInstance(BEANS_REFS_XML_NAME);
288     }
289
290     /**
291      * Returns an instance which uses the the specified selector, as the name of the
292      * definition file(s). In the case of a name with a Spring 'classpath*:' prefix,
293      * or with no prefix, which is treated the same, the current thread's context
294      * classloader's getResources() method will be called with this value to get all
295      * resources having that name. These resources will then be combined to form a
296      * definition. In the case where the name uses a Spring 'classpath:' prefix, or
297      * a standard URL prefix, then only one resource file will be loaded as the
298      * definition.
299      * @param selector the name of the resource(s) which will be read and combine to
300      * form the definition for the SingletonBeanFactoryLocator instance. The one file
301      * or multiple fragments with this name must form a valid BeanFactory definition.
302      */
303     public static BeanFactoryLocator getInstance(String selector) throws FatalBeanException {
304         // For backwards compatibility, we prepend 'classpath*:' to the selector name if there
305 // is no other prefix (i.e. classpath*:, classpath:, or some URL prefix.
306 if (selector.indexOf(':') == -1) {
307             selector = ResourcePatternResolver.CLASSPATH_ALL_URL_PREFIX + selector;
308         }
309
310         synchronized (instances) {
311             if (logger.isTraceEnabled()) {
312                 logger.trace("SingletonBeanFactoryLocator.getInstance(): instances.hashCode=" +
313                         instances.hashCode() + ", instances=" + instances);
314             }
315             BeanFactoryLocator bfl = (BeanFactoryLocator) instances.get(selector);
316             if (bfl == null) {
317                 bfl = new SingletonBeanFactoryLocator(selector);
318                 instances.put(selector, bfl);
319             }
320             return bfl;
321         }
322     }
323
324
325     // We map BeanFactoryGroup objects by String keys, and by the definition object.
326 private final Map bfgInstancesByKey = new HashMap ();
327
328     private final Map bfgInstancesByObj = new HashMap ();
329
330     private final String resourceName;
331
332
333     /**
334      * Constructor which uses the default "beanRefFactory.xml", as the name of the
335      * definition file(s). All resources returned by the definition classloader's
336      * getResources() method with this name will be combined to create a definition.
337      */
338     protected SingletonBeanFactoryLocator() {
339         this.resourceName = BEANS_REFS_XML_NAME;
340     }
341
342     /**
343      * Constructor which uses the the specified name as the name of the
344      * definition file(s). All resources returned by the definition classloader's
345      * getResources() method with this name will be combined to create a definition
346      * definition.
347      */
348     protected SingletonBeanFactoryLocator(String resourceName) {
349         this.resourceName = resourceName;
350     }
351
352     public BeanFactoryReference useBeanFactory(String factoryKey) throws BeansException {
353         synchronized (this.bfgInstancesByKey) {
354             BeanFactoryGroup bfg = (BeanFactoryGroup) this.bfgInstancesByKey.get(this.resourceName);
355
356             if (bfg != null) {
357                 bfg.refCount++;
358             }
359             else {
360                 // This group definition doesn't exist, we need to try to load it.
361 if (logger.isTraceEnabled()) {
362                     logger.trace("Factory group with resource name [" + this.resourceName +
363                             "] requested. Creating new instance.");
364                 }
365                 
366                 // Create the BeanFactory but don't initialize it.
367 BeanFactory groupContext = createDefinition(this.resourceName, factoryKey);
368
369                 // Record its existence now, before instantiating any singletons.
370 bfg = new BeanFactoryGroup();
371                 bfg.definition = groupContext;
372                 bfg.refCount = 1;
373                 this.bfgInstancesByKey.put(this.resourceName, bfg);
374                 this.bfgInstancesByObj.put(groupContext, bfg);
375
376                 // Now initialize the BeanFactory. This may cause a re-entrant invocation
377 // of this method, but since we've already added the BeanFactory to our
378 // mappings, the next time it will be found and simply have its
379 // reference count incremented.
380 try {
381                     initializeDefinition(groupContext);
382                 }
383                 catch (BeansException ex) {
384                     throw new BootstrapException("Unable to initialize group definition. " +
385                         "Group resource name [" + this.resourceName + "], factory key [" + factoryKey + "]", ex);
386                 }
387             }
388
389             final BeanFactory groupContext = bfg.definition;
390
391             String beanName = factoryKey;
392             Object bean;
393             try {
394                 bean = groupContext.getBean(beanName);
395                 if (bean instanceof String ) {
396                     logger.warn("You're using the deprecated alias-through-String-bean feature, " +
397                             "which will be removed as of Spring 2.1. It is recommended to replace this " +
398                             "with an <alias> tag (see SingletonBeanFactoryLocator javadoc).");
399                     beanName = (String ) bean;
400                     bean = groupContext.getBean(beanName);
401                 }
402             }
403             catch (BeansException ex) {
404                 throw new BootstrapException("Unable to return specified BeanFactory instance: factory key [" +
405                         factoryKey + "], from group with resource name [" + this.resourceName + "]", ex);
406             }
407
408             if (!(bean instanceof BeanFactory)) {
409                 throw new BootstrapException("Bean '" + beanName + "' is not a BeanFactory: factory key [" +
410                         factoryKey + "], from group with resource name [" + this.resourceName + "]");
411             }
412
413             final BeanFactory beanFactory = (BeanFactory) bean;
414
415             return new BeanFactoryReference() {
416                 
417                 BeanFactory groupContextRef;
418                 
419                 // constructor
420 {
421                     this.groupContextRef = groupContext;
422                 }
423                 
424                 public BeanFactory getFactory() {
425                     return beanFactory;
426                 }
427
428                 // Note that it's legal to call release more than once!
429 public void release() throws FatalBeanException {
430                     synchronized (bfgInstancesByKey) {
431                         BeanFactory savedRef = this.groupContextRef;
432                         if (savedRef != null) {
433                             this.groupContextRef = null;
434                             BeanFactoryGroup bfg = (BeanFactoryGroup) bfgInstancesByObj.get(savedRef);
435                             if (bfg != null) {
436                                 bfg.refCount--;
437                                 if (bfg.refCount == 0) {
438                                     destroyDefinition(savedRef, resourceName);
439                                     bfgInstancesByKey.remove(resourceName);
440                                     bfgInstancesByObj.remove(savedRef);
441                                 }
442                             }
443                             else {
444                                 // This should be impossible.
445 logger.warn("Tried to release a SingletonBeanFactoryLocator group definition " +
446                                         "more times than it has actually been used. Resource name [" + resourceName + "]");
447                             }
448                         }
449                     }
450                 }
451             };
452         }
453     }
454
455     /**
456      * Actually creates definition in the form of a BeanFactory, given a resource name
457      * which supports standard Spring Resource prefixes ('classpath:', 'classpath*:', etc.)
458      * This is split out as a separate method so that subclasses can override the actual
459      * type used (to be an ApplicationContext, for example).
460      * <p>This method should not instantiate any singletons. That function is performed
461      * by {@link #initializeDefinition initializeDefinition()}, which should also be
462      * overridden if this method is.
463      */
464     protected BeanFactory createDefinition(String resourceName, String factoryKey) throws BeansException {
465         DefaultListableBeanFactory factory = new DefaultListableBeanFactory();
466         XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(factory);
467         ResourcePatternResolver resourcePatternResolver = new PathMatchingResourcePatternResolver();
468
469         try {
470             Resource[] configResources = resourcePatternResolver.getResources(resourceName);
471             if (configResources.length == 0) {
472                 throw new FatalBeanException("Unable to find resource for specified definition. " +
473                         "Group resource name [" + this.resourceName + "], factory key [" + factoryKey + "]");
474             }
475             reader.loadBeanDefinitions(configResources);
476         }
477         catch (IOException ex) {
478             throw new BeanDefinitionStoreException(
479                     "Error accessing bean definition resource [" + this.resourceName + "]", ex);
480         }
481         catch (BeanDefinitionStoreException ex) {
482             throw new FatalBeanException("Unable to load group definition: " +
483                     "group resource name [" + this.resourceName + "], factory key [" + factoryKey + "]", ex);
484         }
485
486         return factory;
487     }
488     
489     /**
490      * Instantiate singletons and do any other normal initialization of the factory.
491      * Subclasses that override {@link #createDefinition createDefinition()} should
492      * also override this method.
493      * @param groupDef the factory returned by {@link #createDefinition createDefinition()}
494      */
495     protected void initializeDefinition(BeanFactory groupDef) throws BeansException {
496         if (groupDef instanceof ConfigurableListableBeanFactory) {
497             ((ConfigurableListableBeanFactory) groupDef).preInstantiateSingletons();
498         }
499     }
500
501     /**
502      * Destroy definition in separate method so subclass may work with other definition types.
503      */
504     protected void destroyDefinition(BeanFactory groupDef, String resourceName) throws BeansException {
505         if (groupDef instanceof ConfigurableBeanFactory) {
506             if (logger.isTraceEnabled()) {
507                 logger.trace("Factory group with resource name '" + resourceName +
508                         "' being released, as there are no more references to it.");
509             }
510             ((ConfigurableBeanFactory) groupDef).destroySingletons();
511         }
512     }
513
514
515     /**
516      * We track BeanFactory instances with this class.
517      */
518     private static class BeanFactoryGroup {
519
520         private BeanFactory definition;
521
522         private int refCount = 0;
523     }
524
525 }
526

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags