You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@turbine.apache.org by gk...@apache.org on 2021/09/08 12:43:35 UTC
[turbine-fulcrum-pool] 03/49: (Hopefully) improve documentation
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 <tv...@apache.org>
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>