Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> springframework >> beans >> factory >> [ access overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.springframework.beans.factory.access.SingletonBeanFactoryLocator JAVADOC | Sourc code of org.springframework.beans.factory.access.SingletonBeanFactoryLocator SOURCE | Download org.springframework.beans.factory.access.SingletonBeanFactoryLocator DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.springframework.beans.factory.access
Class SingletonBeanFactoryLocator  view SingletonBeanFactoryLocator download SingletonBeanFactoryLocator.java

java.lang.Object
  extended byorg.springframework.beans.factory.access.SingletonBeanFactoryLocator
All Implemented Interfaces:
BeanFactoryLocator
public class SingletonBeanFactoryLocator
extends java.lang.Object
implements BeanFactoryLocator

Keyed-singleton implementation of BeanFactoryLocator, which leverages existing Spring constructs. This is normally accessed through DefaultLocatorFactory, but may also be used directly.

Please see the warning in BeanFactoryLocator's javadoc about appropriate usage of singleton style BeanFactoryLocator implementations. It is the opinion of the Spring team that the use of this class and similar classes is unnecessary except (sometimes) for a small amount of glue code. Excessive usage will lead to code that is more tightly coupled, and harder to modify or test.

In this implementation, a BeanFactory is built up from one or more XML definition file fragments, accessed as resources. The default resource name searched for is 'classpath*:beanRefFactory.xml', with the Spring-standard 'classpath*:' prefix ensuring that if the classpath contains multiple copies of this file (perhaps one in each component jar) they will be combined. To override the default resource name, instead of using the no-arg getInstance() 55 method, use the getInstance(String selector) 55 variant, which will treat the 'selector' argument as the resource name to search for.

The purpose of this 'outer' BeanFactory is to create and hold a copy of one or more 'inner' BeanFactory or ApplicationContext instances, and allow those to be obtained either directly or via an alias. As such, this class provides both singleton style access to one or more BeanFactories/ApplicationContexts, and also a level of indirection, allowing multiple pieces of code, which are not able to work in a Dependency Injection fashion, to refer to and use the same target BeanFactory/ApplicationContext instance(s), by different names.

Consider an example application scenario:

In an ideal scenario, these would be combined to create one ApplicationContext, or created as three hierarchical ApplicationContexts, by one piece of code somewhere at application startup (perhaps a Servlet filter), from which all other code in the application would flow, obtained as beans from the context(s). However when third party code enters into the picture, things can get problematic. If the third party code needs to create user classes, which should normally be obtained from a Spring BeanFactory/ApplicationContext, but can handle only newInstance() style object creation, then some extra work is required to actually access and use object from a BeanFactory/ApplicationContext. One solutions is to make the class created by the third party code be just a stub or proxy, which gets the real object from a BeanFactory/ApplicationContext, and delegates to it. However, it is is not normally workable for the stub to create the BeanFactory on each use, as depending on what is inside it, that can be an expensive operation. Additionally, there is a fairly tight coupling between the stub and the name of the definition resource for the BeanFactory/ApplicationContext. This is where SingletonBeanFactoryLocator comes in. The stub can obtain a SingletonBeanFactoryLocator instance, which is effectively a singleton, and ask it for an appropriate BeanFactory. A subsequent invocation (assuming the same class loader is involved) by the stub or another piece of code, will obtain the same instance. The simple aliasing mechanism allows the context to be asked for by a name which is appropriate for (or describes) the user. The deployer can match alias names to actual context names.

Another use of SingletonBeanFactoryLocator, is to demand-load/use one or more BeanFactories/ApplicationContexts. Because the definiiton can contain one of more BeanFactories/ApplicationContexts, which can be independent or in a hierarchy, if they are set to lazy-initialize, they will only be created when actually requested for use.

Given the above-mentioned three ApplicationContexts, consider the simplest SingletonBeanFactoryLocator usage scenario, where there is only one single beanRefFactory.xml definition file: 

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
 
 <beans>
 
   <bean id="com.mycompany.myapp"
         class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <list>
         <value>com/mycompany/myapp/util/applicationContext.xml</value>
         <value>com/mycompany/myapp/dataaccess/applicationContext.xml</value>
         <value>com/mycompany/myapp/dataaccess/services.xml</value>
       </list>
     </constructor-arg>
   </bean>
 
 </beans>
The client code is as simple as: 
 BeanFactoryLocator bfl = SingletonBeanFactoryLocator.getInstance();
 BeanFactoryReference bf = bfl.useBeanFactory("com.mycompany.myapp");
 // now use some bean from factory 
 MyClass zed = bf.getFactory().getBean("mybean");
Another relatively simple variation of the beanRefFactory.xml definition file could be: 
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
 
 <beans>
 
   <bean id="com.mycompany.myapp.util" lazy-init="true"
         class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <value>com/mycompany/myapp/util/applicationContext.xml</value>
     </constructor-arg>
   </bean>
 
   <!-- child of above -->
   <bean id="com.mycompany.myapp.dataaccess" lazy-init="true"
         class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <list><value>com/mycompany/myapp/dataaccess/applicationContext.xml</value></list>
     </constructor-arg>
     <constructor-arg>
       <ref bean="com.mycompany.myapp.util"/>
     </constructor-arg>
   </bean>
 
   <!-- child of above -->
   <bean id="com.mycompany.myapp.services" lazy-init="true"
         class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <list><value>com/mycompany/myapp/dataaccess.services.xml</value></value>
     </constructor-arg>
     <constructor-arg>
       <ref bean="com.mycompany.myapp.dataaccess"/>
     </constructor-arg>
   </bean>
 
   <!-- define an alias -->
   <bean id="com.mycompany.myapp.mypackage"
         class="java.lang.String">
     <constructor-arg>
       <value>com.mycompany.myapp.services</value>
     </constructor-arg>
   </bean>
 
 </beans>

In this example, there is a hierarchy of three contexts created. The (potential) advantage is that if the lazy flag is set to true, a context will only be created if it's actually used. If there is some code that is only needed some of the time, this mechanism can save some resources. Additionally, an alias to the last context has been created. Aliases allow usage of the idiom where client code asks for a context with an id which represents the package or module the code is in, and the actual definition file(s) for the SingletonBeanFactoryLocator maps that id to a real context id.

A final example is more complex, with a beanRefFactory.xml for every module. All the files are automatically combined to create the final definition.

beanRefFactory.xml file inside jar for util module: 

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
 
 <beans>
   <bean id="com.mycompany.myapp.util" lazy-init="true"
        class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <value>com/mycompany/myapp/util/applicationContext.xml</value>
     </constructor-arg>
   </bean>
 </beans>
beanRefFactory.xml file inside jar for data-access module:
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
 
 <beans>
   <!-- child of util -->
   <bean id="com.mycompany.myapp.dataaccess" lazy-init="true"
        class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <list><value>com/mycompany/myapp/dataaccess/applicationContext.xml</value></list>
     </constructor-arg>
     <constructor-arg>
       <ref bean="com.mycompany.myapp.util"/>
     </constructor-arg>
   </bean>
 </beans>
beanRefFactory.xml file inside jar for services module: 
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
 
 <beans>
   <!-- child of data-access -->
   <bean id="com.mycompany.myapp.services" lazy-init="true"
        class="org.springframework.context.support.ClassPathXmlApplicationContext">
     <constructor-arg>
       <list><value>com/mycompany/myapp/dataaccess/services.xml</value></list>
     </constructor-arg>
     <constructor-arg>
       <ref bean="com.mycompany.myapp.dataaccess"/>
     </constructor-arg>
   </bean>
 </beans>
beanRefFactory.xml file inside jar for mypackage module. This doesn't create any of its own contexts, but allows the other ones to be referred to be a name known to this module: 
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
 
 <beans>
   <!-- define an alias for "com.mycompany.myapp.services" -->
   <alias name="com.mycompany.myapp.services" alias="com.mycompany.myapp.mypackage"/>
 </beans>

Nested Class Summary
private static class SingletonBeanFactoryLocator.BeanFactoryGroup
           
 
Field Summary
static java.lang.String BEANS_REFS_XML_NAME
           
private  java.util.Map bfgInstancesByKey
           
private  java.util.Map bfgInstancesByObj
           
private static java.util.Map instances
           
protected static org.apache.commons.logging.Log logger
           
private  java.lang.String resourceName
           
 
Constructor Summary
protected SingletonBeanFactoryLocator()
          Constructor which uses the default "beanRefFactory.xml", as the name of the definition file(s).
protected SingletonBeanFactoryLocator(java.lang.String resourceName)
          Constructor which uses the the specified name as the name of the definition file(s).
 
Method Summary
protected  org.springframework.beans.factory.BeanFactory createDefinition(java.lang.String resourceName, java.lang.String factoryKey)
          Actually creates definition in the form of a BeanFactory, given a resource name which supports standard Spring Resource prefixes ('classpath:', 'classpath*:', etc.) This is split out as a separate method so that subclasses can override the actual type used (to be an ApplicationContext, for example).
protected  void destroyDefinition(org.springframework.beans.factory.BeanFactory groupDef, java.lang.String resourceName)
          Destroy definition in separate method so subclass may work with other definition types.
static BeanFactoryLocator getInstance()
          Returns an instance which uses the default "classpath*:beanRefFactory.xml", as the name of the definition file(s).
static BeanFactoryLocator getInstance(java.lang.String selector)
          Returns an instance which uses the the specified selector, as the name of the definition file(s).
protected  void initializeDefinition(org.springframework.beans.factory.BeanFactory groupDef)
          Instantiate singletons and do any other normal initialization of the factory.
 BeanFactoryReference useBeanFactory(java.lang.String factoryKey)
          Use the BeanFactory (or derived class such as ApplicationContext) specified by the factoryKey parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BEANS_REFS_XML_NAME

public static final java.lang.String BEANS_REFS_XML_NAME
See Also:
Constant Field Values

logger

protected static final org.apache.commons.logging.Log logger

instances

private static java.util.Map instances

bfgInstancesByKey

private final java.util.Map bfgInstancesByKey

bfgInstancesByObj

private final java.util.Map bfgInstancesByObj

resourceName

private final java.lang.String resourceName
Constructor Detail

SingletonBeanFactoryLocator

protected SingletonBeanFactoryLocator()
Constructor which uses the default "beanRefFactory.xml", as the name of the definition file(s). All resources returned by the definition classloader's getResources() method with this name will be combined to create a definition.

SingletonBeanFactoryLocator

protected SingletonBeanFactoryLocator(java.lang.String resourceName)
Constructor which uses the the specified name as the name of the definition file(s). All resources returned by the definition classloader's getResources() method with this name will be combined to create a definition definition.

Method Detail

getInstance

public static BeanFactoryLocator getInstance()
                                      throws org.springframework.beans.FatalBeanException
Returns an instance which uses the default "classpath*:beanRefFactory.xml", as the name of the definition file(s). All resources returned by calling the current thread's context classloader's getResources() method with this name will be combined to create a definition, which is just a BeanFactory.

getInstance

public static BeanFactoryLocator getInstance(java.lang.String selector)
                                      throws org.springframework.beans.FatalBeanException
Returns an instance which uses the the specified selector, as the name of the definition file(s). In the case of a name with a Spring 'classpath*:' prefix, or with no prefix, which is treated the same, the current thread's context classloader's getResources() method will be called with this value to get all resources having that name. These resources will then be combined to form a definition. In the case where the name uses a Spring 'classpath:' prefix, or a standard URL prefix, then only one resource file will be loaded as the definition.

useBeanFactory

public BeanFactoryReference useBeanFactory(java.lang.String factoryKey)
                                    throws org.springframework.beans.BeansException
Description copied from interface: BeanFactoryLocator
Use the BeanFactory (or derived class such as ApplicationContext) specified by the factoryKey parameter. The definition is possibly loaded/created as needed.

Specified by:
useBeanFactory in interface BeanFactoryLocator

createDefinition

protected org.springframework.beans.factory.BeanFactory createDefinition(java.lang.String resourceName,
                                                                         java.lang.String factoryKey)
                                                                  throws org.springframework.beans.BeansException
Actually creates definition in the form of a BeanFactory, given a resource name which supports standard Spring Resource prefixes ('classpath:', 'classpath*:', etc.) This is split out as a separate method so that subclasses can override the actual type used (to be an ApplicationContext, for example).

This method should not instantiate any singletons. That function is performed by initializeDefinition() 55 , which should also be overridden if this method is.

initializeDefinition

protected void initializeDefinition(org.springframework.beans.factory.BeanFactory groupDef)
                             throws org.springframework.beans.BeansException
Instantiate singletons and do any other normal initialization of the factory. Subclasses that override createDefinition() 55 should also override this method.

destroyDefinition

protected void destroyDefinition(org.springframework.beans.factory.BeanFactory groupDef,
                                 java.lang.String resourceName)
                          throws org.springframework.beans.BeansException
Destroy definition in separate method so subclass may work with other definition types.

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> springframework >> beans >> factory >> [ access overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.springframework.beans.factory.access.SingletonBeanFactoryLocator JAVADOC | Sourc code of org.springframework.beans.factory.access.SingletonBeanFactoryLocator SOURCE | Download org.springframework.beans.factory.access.SingletonBeanFactoryLocator DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD