You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by il...@apache.org on 2001/04/12 21:38:51 UTC

cvs commit: jakarta-turbine/xdocs/services pool-service.xml factory-service.xml

ilkka       01/04/12 12:38:51

  Modified:    xdocs    services.xml
               xdocs/services pool-service.xml factory-service.xml
  Log:
  Added documentation for Factory Service and Pool Service
  
  Revision  Changes    Path
  1.12      +1 -1      jakarta-turbine/xdocs/services.xml
  
  Index: services.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-turbine/xdocs/services.xml,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- services.xml	2001/04/12 01:11:16	1.11
  +++ services.xml	2001/04/12 19:38:43	1.12
  @@ -94,7 +94,7 @@
   </li></p>
   
   <p><li>
  -<a href="services/pool-service.html">Pool Service</a> - <b>[TO DO]</b> A service for the pooling of instantiated Objects, allowing for the recycling and disposal of Objects in the pool..
  +<a href="services/pool-service.html">Pool Service</a> - A service for the pooling of instantiated Objects, allowing for the recycling and disposal of Objects in the pool.
   </li></p>
   
   <p><li>
  
  
  
  1.3       +62 -0     jakarta-turbine/xdocs/services/pool-service.xml
  
  Index: pool-service.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-turbine/xdocs/services/pool-service.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- pool-service.xml	2001/04/08 18:35:59	1.2
  +++ pool-service.xml	2001/04/12 19:38:47	1.3
  @@ -11,8 +11,36 @@
   <section name="Pool Service">
   
   <p>
  +The Pool Service extends the functionality of the Factory Service by adding 
  +support for pooling objects intantiated from the given class name or
  +Class object reference. Pooling of objects stabilizes memory consumption and 
  +reduces garbage collection making response times in server applications 
  +more predictable.
   </p>
   
  +<p>
  +When a new instance is requested from the service, it first checks its pool 
  +if one is available. If the the pool is empty, a new object will be instantiated 
  +from the given class. If the class is specified by its name, the request to create 
  +an instance will be forwarded to the Factory Service.
  +</p>
  +
  +<p>
  +For pooled objects implementing the Recyclable interface, a recycle method 
  +will be called, when they are taken from the pool, and a dispose method, 
  +when they are returned to the pool. Implementations of the methods should 
  +clear and initialize the pooled instances correspondingly. Objects 
  +that do not implement the interface can also be pooled, if they do not 
  +need to perform any specific actions during pooling. A RecyclableSupport class 
  +can be extended to get a minimal implementation of the interface.
  +</p>
  +
  +<p>
  +An ArrayCtorRecyclable interface extends the Recyclable interface providing
  +a more efficient recycle method with less reflection for recycling frequently
  +used objects having constuctors with parameters.   
  +</p>
  +
   </section>
   
   <section name="Configuration">
  @@ -34,14 +62,48 @@
   .
   .
   .
  +# -------------------------------------------------------------------
  +# 
  +#  P O O L  S E R V I C E
  +#
  +# -------------------------------------------------------------------
  +
  +# Default capacity of pools of the Object pooling service.
  +#
  +# Default: 128
  +services.PoolService.pool.capacity = 128
  +
  +# Class specific capacities used instead of the default if specified.
  +#
  +#services.PoolService.pool.capacity.org.apache.turbine.services.rundata.DefaultTurbineRunData=512
  +
   ]]></source>
   
   </section>
   
   <section name="Usage">
   
  +<p>
  +The Pool Service can be called instead of the Factory Service, when instantiating
  +objects that are needed repeatedly e.g. for processing client requests. Intances
  +of RunData implementations, ParameterParser and CookieParser implementations, 
  +Pull Service tools, etc, are typical examples of pooled objects. Used objects
  +must be returned to the Pool Service for recycling. The TurbinePool class is a 
  +static accessor for common methods of the Pool Service:
  +</p>
  +
   <source><![CDATA[
   
  +    // Get a pooled DOM parser.
  +    DocumentBuilder parser = 
  +        TurbinePool.getInstance("javax.xml.parsers.DocumentBuilder");
  +        
  +    // Parse an XML document.
  +    Document doc = parser.parse(myfile);
  +    
  +    // Return the parser to the pool.
  +    TurbinePool.putInstance(parser);
  +    
   ]]></source>
   
   </section>
  
  
  
  1.4       +133 -4    jakarta-turbine/xdocs/services/factory-service.xml
  
  Index: factory-service.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-turbine/xdocs/services/factory-service.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- factory-service.xml	2001/04/08 18:35:58	1.3
  +++ factory-service.xml	2001/04/12 19:38:48	1.4
  @@ -11,11 +11,22 @@
   <section name="Factory Service">
   
   <p>
  -The Factory Service instantiates objects using specified
  -class loaders. If none is specified, the default one
  +The Factory Service instantiates objects from the given class name
  +using either the given class loader or an applicable one found from the class
  +loader repository. If neither one is specified, the default class loader
   will be used.
   </p>
   
  +<p>
  +The service provides the following benefits compared to Class.forName():
  +</p>
  +<ul>
  +<li>support for parameters in constructors,</li>
  +<li>internal class loader repository, which can be specified in resources,</li>
  +<li>optional class specific factories, which can be used for customized instantiation, and</li>
  +<li>integration with the Pool Service supporting recycling of instances created by the service.</li>
  +</ul>
  +
   </section>
   
   <section name="Configuration">
  @@ -70,9 +81,127 @@
   <section name="Usage">
   
   <p>
  -The TurbineFactoryService is currently only used internally by the
  -TurbinePoolService.
  +In Turbine, the Factory Service is currently only used internally by the Pool Service.
  +Applications can also use the service instead of Class.forName() and for unifying
  +initialization, configuration and access to vendor specific object factories. 
  +The following is a simplified example of a customized DOM parser factory:
   </p>
  +
  +<source><![CDATA[
  +
  +package org.foo.xml;
  +
  +import javax.xml.parsers.DocumentBuilder;
  +import javax.xml.parsers.DocumentBuilderFactory;
  +import javax.xml.parsers.ParserConfigurationException;
  +
  +import org.apache.turbine.util.TurbineException;
  +import org.apache.turbine.services.factory.Factory;
  +
  +/**
  + * A factory for instantiating DOM parsers. 
  + */
  +public class DomBuilderFactory implements Factory
  +{
  +    /**
  +     * The implementation of the factory.
  +     */
  +    private DocumentBuilderFactory factory;
  +
  +    /**
  +     * Initializes the factory.
  +     */
  +    public void init(String className)
  +        throws TurbineException
  +    {
  +        factory = DocumentBuilderFactory.newInstance();
  +    }
  +
  +    /**
  +     * Gets a DocumentBuilder instance.
  +     */
  +    public Object getInstance()
  +        throws TurbineException
  +    {
  +        try
  +        {
  +            return factory.newDocumentBuilder();
  +        }
  +        catch (ParserConfigurationException x)
  +        {
  +            throw new TurbineException(x);
  +        }
  +    }
  +
  +    /**
  +     * Gets a DocumentBuilder instance.
  +     * The given loader is ignored.
  +     */
  +    public Object getInstance(ClassLoader loader)
  +        throws TurbineException
  +    {
  +        return getInstance();
  +    }
  +
  +    /**
  +     * Gets a DocumentBuilder instance.
  +     * Constructor parameters are ignored.
  +     */
  +    public Object getInstance(Object[] params,
  +                              String[] signature)
  +        throws TurbineException
  +    {
  +        return getInstance();
  +    }
  +
  +    /**
  +     * Gets a DocumentBuilder instance.
  +     * The given loader and constructor parameters are ignored.
  +     */
  +    public Object getInstance(ClassLoader loader,
  +                              Object[] params,
  +                              String[] signature)
  +        throws TurbineException
  +    {
  +        return getInstance();
  +    }
  +
  +    /**
  +     * Returns false as given class loaders are not supported.
  +     */
  +    public boolean isLoaderSupported()
  +    {
  +        return false;
  +    }
  +}
  +
  +]]></source>
  +
  +<p>
  +The customized DOM parser factory must be specified in Turbine Resources before it can be used:
  +</p>
  +
  +<source><![CDATA[
  +
  +services.FactoryService.factory.javax.xml.parsers.DocumentBuilder=org.foo.xml.DomBuilderFactory
  +
  +]]></source>
  +
  +<p>
  +A DOM parser can now be instantiated with the following code fragment:
  +</p>
  +
  +<source><![CDATA[
  +
  +    // Access the service singleton.
  +    FactoryService service = (FactoryService) 
  +        TurbineServices.getInstance().getService(FactoryService.SERVICE_NAME);
  +    
  +    // Create a new DOM parser. 
  +    DocumentBuilder parser = 
  +        service.getInstance("javax.xml.parsers.DocumentBuilder");
  +
  +]]></source>
   
   </section>
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-dev-help@jakarta.apache.org