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:39:34 UTC
cvs commit: jakarta-turbine/docs services.html
ilkka 01/04/12 12:39:34
Modified: docs/services factory-service.html pool-service.html
docs services.html
Log:
Added documentation for Factory Service and Pool Service
Revision Changes Path
1.8 +181 -4 jakarta-turbine/docs/services/factory-service.html
Index: factory-service.html
===================================================================
RCS file: /home/cvs/jakarta-turbine/docs/services/factory-service.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- factory-service.html 2001/04/12 12:30:25 1.7
+++ factory-service.html 2001/04/12 19:39:28 1.8
@@ -141,10 +141,20 @@
<tr><td>
<blockquote>
<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>
</blockquote>
</td></tr>
</table>
@@ -230,9 +240,176 @@
<tr><td>
<blockquote>
<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>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+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;
+ }
+}
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+The customized DOM parser factory must be specified in Turbine Resources before it can be used:
</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+services.FactoryService.factory.javax.xml.parsers.DocumentBuilder=org.foo.xml.DomBuilderFactory
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+A DOM parser can now be instantiated with the following code fragment:
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+ // 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");
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
</blockquote>
</td></tr>
</table>
1.8 +59 -1 jakarta-turbine/docs/services/pool-service.html
Index: pool-service.html
===================================================================
RCS file: /home/cvs/jakarta-turbine/docs/services/pool-service.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- pool-service.html 2001/04/12 12:30:25 1.7
+++ pool-service.html 2001/04/12 19:39:29 1.8
@@ -141,7 +141,32 @@
<tr><td>
<blockquote>
<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>
</blockquote>
</td></tr>
</table>
@@ -179,6 +204,21 @@
.
.
.
+# -------------------------------------------------------------------
+#
+# 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
+
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
@@ -200,7 +240,15 @@
</td></tr>
<tr><td>
<blockquote>
- <div align="left">
+ <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>
+ <div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
@@ -211,6 +259,16 @@
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
+ // 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);
+
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
1.26 +1 -1 jakarta-turbine/docs/services.html
Index: services.html
===================================================================
RCS file: /home/cvs/jakarta-turbine/docs/services.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- services.html 2001/04/12 12:30:21 1.25
+++ services.html 2001/04/12 19:39:33 1.26
@@ -221,7 +221,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>
---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-dev-help@jakarta.apache.org