This is an automated email from the ASF dual-hosted git repository. gk pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/turbine-fulcrum-pool.git
commit 7cc01d8df7e8c117fc0c7b398997b2dfa2f19d7e Author: Thomas Vandahl <[email protected]> AuthorDate: Tue Aug 5 16:32:32 2008 +0000 (Hopefully) improve documentation git-svn-id: https://svn.apache.org/repos/asf/turbine/fulcrum/trunk/pool@682777 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/index.xml | 150 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 87 insertions(+), 63 deletions(-) diff --git a/xdocs/index.xml b/xdocs/index.xml index f50c7f1..62d3c0b 100644 --- a/xdocs/index.xml +++ b/xdocs/index.xml @@ -29,98 +29,122 @@ <section name="Overview"> -<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"> + <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> - First, here is the role configuration. This component requires the FactoryService - component. + 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 constructors with parameters. </p> + </section> -<source> -<![CDATA[ + <section name="Configuration"> + <subsection name="Role Configuration"> + <p> + This component requires the FactoryService component. + </p> + <source><![CDATA[ <role name="org.apache.fulcrum.pool.PoolService" shorthand="pool" default-class="org.apache.fulcrum.pool.DefaultPoolService"/> - <role name="org.apache.fulcrum.factory.FactoryService" shorthand="factory" default-class="org.apache.fulcrum.factory.DefaultFactoryService"/> -]]> -</source> - - <p> - Now comes the basic configuration of the component. Here will will - configure the various bundles. - </p> -<source> - -<![CDATA[ + ]]></source> + </subsection> + + <subsection name="Component Configuration"> + <table> + <tr> + <th>Item</th> + <th>Datatype</th> + <th>Cardinality</th> + <th>Description</th> + </tr> + <tr> + <td>capacity</td> + <td>Complex</td> + <td>[0|1]</td> + <td> + The parent element for defining pool capacities. Sub-elements define + capacities for certain class names. You can define one + <code>default</code> pool that will be used if no others + match. If not specified, a default capacity of 128 is used. See + the configuration example below. + </td> + </tr> + </table> + </subsection> + + <subsection name="Component Configuration Example"> + <source><![CDATA[ <pool> - <capacity default="256"/> + <capacity> + <javax.xml.parsers.DocumentBuilder> + 256 + </javax.xml.parsers.DocumentBuilder> + <default> + 128 + </default> + </capacity> </pool> - <factory/> -]]> -</source> - + <factory> + ... + </factory> + ]]></source> + </subsection> </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> + <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. Instances + 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. + </p> <source><![CDATA[ +// Access the service singleton. +PoolService service = (PoolService)container.lookup(PoolService.ROLE); + // Get a pooled DOM parser. DocumentBuilder parser = - TurbinePool.getInstance("javax.xml.parsers.DocumentBuilder"); + service.getInstance("javax.xml.parsers.DocumentBuilder"); // Parse an XML document. Document doc = parser.parse(myfile); // Return the parser to the pool. -TurbinePool.putInstance(parser); +service.putInstance(parser); ]]></source> </section>
