You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@turbine.apache.org by tv...@apache.org on 2008/08/05 18:32:32 UTC
svn commit: r682777 - in /turbine/fulcrum/trunk: factory/xdocs/index.xml
factory/xdocs/tasks.xml localization/xdocs/index.xml pool/xdocs/index.xml
Author: tv
Date: Tue Aug 5 09:32:32 2008
New Revision: 682777
URL: http://svn.apache.org/viewvc?rev=682777&view=rev
Log:
(Hopefully) improve documentation
Modified:
turbine/fulcrum/trunk/factory/xdocs/index.xml
turbine/fulcrum/trunk/factory/xdocs/tasks.xml
turbine/fulcrum/trunk/localization/xdocs/index.xml
turbine/fulcrum/trunk/pool/xdocs/index.xml
Modified: turbine/fulcrum/trunk/factory/xdocs/index.xml
URL: http://svn.apache.org/viewvc/turbine/fulcrum/trunk/factory/xdocs/index.xml?rev=682777&r1=682776&r2=682777&view=diff
==============================================================================
--- turbine/fulcrum/trunk/factory/xdocs/index.xml (original)
+++ turbine/fulcrum/trunk/factory/xdocs/index.xml Tue Aug 5 09:32:32 2008
@@ -22,7 +22,8 @@
<properties>
<title>Factory Component</title>
- <author email="epugh@upstate.com">Eric PUgh</author>
+ <author email="epugh@upstate.com">Eric Pugh</author>
+ <author email="tv@apache.org">Thomas Vandahl</author>
</properties>
<body>
@@ -47,42 +48,72 @@
</section>
<section name="Configuration">
-
- <p>
- First, here is the role configuration.
- </p>
-
-<source>
-<![CDATA[
- <role
+ <subsection name="Role Configuration">
+ <source><![CDATA[
+ <role
name="org.apache.fulcrum.factory.FactoryService"
shorthand="factory"
default-class="org.apache.fulcrum.factory.DefaultFactoryService"/>
-]]>
-</source>
-
- <p>
- There is configuration values for classloaders, still need to add.
- </p>
-<source>
-
-<![CDATA[
- <factory/>
-]]>
-</source>
+ ]]></source>
+ </subsection>
+ <subsection name="Component Configuration">
+ <table>
+ <tr>
+ <th>Item</th>
+ <th>Datatype</th>
+ <th>Cardinality</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>classloader</td>
+ <td>String</td>
+ <td>[0..n]</td>
+ <td>
+ A class loader. Class loaders will be tried in sequence when
+ trying to create an object instance.
+ </td>
+ </tr>
+ <tr>
+ <td>object-factory</td>
+ <td>Complex</td>
+ <td>[0|1]</td>
+ <td>
+ The parent element for object factories. Sub-elements define
+ factories for certain class names. You can define one
+ <code>default</code> factory that will be used if no others
+ match. See the configuration example below.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+
+ <subsection name="Component Configuration Example">
+ <source><![CDATA[
+ <factory>
+ <classloader>java.net.URLClassLoader</classloader>
+ <object-factory>
+ <javax.xml.parsers.DocumentBuilder>
+ org.foo.xml.DomBuilderFactory
+ </javax.xml.parsers.DocumentBuilder>
+ <default>
+ org.some.default.Factory
+ </default>
+ </object-factory>
+ </factory>
+ ]]></source>
+ </subsection>
</section>
<section name="Usage">
+ <p>
+ 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>
-<p>
-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[
+ <source><![CDATA[
package org.foo.xml;
import javax.xml.parsers.DocumentBuilder;
@@ -170,22 +201,19 @@
}
]]></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>
+ The customized DOM parser factory must be specified in the component
+ configuration like in the configuration example above before it can
+ be used.
+ </p>
-<p>
-A DOM parser can now be instantiated with the following code fragment:
-</p>
+ <p>
+ A DOM parser can now be instantiated with the following code fragment:
+ </p>
-<source><![CDATA[
+ <source><![CDATA[
// Access the service singleton.
-FactoryService service = (FactoryService)
- TurbineServices.getInstance().getService(FactoryService.SERVICE_NAME);
+FactoryService service = (FactoryService)container.lookup(FactoryService.ROLE);
// Create a new DOM parser.
DocumentBuilder parser =
@@ -193,6 +221,5 @@
]]></source>
</section>
-
</body>
</document>
Modified: turbine/fulcrum/trunk/factory/xdocs/tasks.xml
URL: http://svn.apache.org/viewvc/turbine/fulcrum/trunk/factory/xdocs/tasks.xml?rev=682777&r1=682776&r2=682777&view=diff
==============================================================================
--- turbine/fulcrum/trunk/factory/xdocs/tasks.xml (original)
+++ turbine/fulcrum/trunk/factory/xdocs/tasks.xml Tue Aug 5 09:32:32 2008
@@ -34,7 +34,7 @@
<p>
<ul>
<li>
- Need to test using the configuratio values. Currently it just uses the default Classloader.
+ Need to test using the configuration values. Currently it just uses the default Classloader.
</li>
<li>
Document using different classloaders.
Modified: turbine/fulcrum/trunk/localization/xdocs/index.xml
URL: http://svn.apache.org/viewvc/turbine/fulcrum/trunk/localization/xdocs/index.xml?rev=682777&r1=682776&r2=682777&view=diff
==============================================================================
--- turbine/fulcrum/trunk/localization/xdocs/index.xml (original)
+++ turbine/fulcrum/trunk/localization/xdocs/index.xml Tue Aug 5 09:32:32 2008
@@ -34,9 +34,86 @@
for use in Turbine but it can be used in any container compatible
with Avalon's ECM container.
</p>
+ <p>
+ There two implementations
+ <ul>
+ <li>SimpleLocalizationService and</li>
+ <li>LocalizationService</li>
+ </ul>
+ The <code>SimpleLocalizationService</code> provides basic localization functions
+ for generic applications whereas the <code>LocalizationService</code> adds support
+ for web applications and depends on a servlet container environment.
+ </p>
</section>
- <section name="Configuration">
+ <section name="SimpleLocalizationService">
+ <subsection name="Role Configuration">
+ <source><![CDATA[
+ <role
+ name="org.apache.fulcrum.localization.SimpleLocalizationService"
+ shorthand="localization"
+ default-class="org.apache.fulcrum.localization.SimpleLocalizationServiceImpl"/>
+ ]]></source>
+ </subsection>
+
+ <subsection name="Component Configuration">
+ <table>
+ <tr>
+ <th>Item</th>
+ <th>Datatype</th>
+ <th>Cardinality</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>bundles</td>
+ <td>Complex</td>
+ <td>[1]</td>
+ <td>
+ The list of configured bundles.
+ </td>
+ </tr>
+ <tr>
+ <td>bundles@locale-default-language</td>
+ <td>String</td>
+ <td>[0|1]</td>
+ <td>
+ The default language to use if none is specified. If this attribute
+ is absent, the JVM default language will be used.
+ </td>
+ </tr>
+ <tr>
+ <td>bundles@locale-default-country</td>
+ <td>String</td>
+ <td>[0|1]</td>
+ <td>
+ The default country to use if none is specified. If this attribute
+ is absent, the JVM default country will be used.
+ </td>
+ </tr>
+ <tr>
+ <td>bundles/bundle</td>
+ <td>String</td>
+ <td>[1..n]</td>
+ <td>
+ The name of the bundle
+ </td>
+ </tr>
+ </table>
+ </subsection>
+
+ <subsection name="Component Configuration Example">
+ <source><![CDATA[
+ <localization>
+ <bundles locale-default-language="en" locale-default-country="US">
+ <bundle>org.apache.fulcrum.localization.BarBundle</bundle>
+ <bundle>org.apache.fulcrum.localization.FooBundle</bundle>
+ </bundles>
+ </localization>
+ ]]></source>
+ </subsection>
+ </section>
+
+ <section name="LocalizationService">
<subsection name="Role Configuration">
<source><![CDATA[
<role
@@ -63,6 +140,24 @@
</td>
</tr>
<tr>
+ <td>bundles@locale-default-language</td>
+ <td>String</td>
+ <td>[0|1]</td>
+ <td>
+ The default language to use if none is specified. If this attribute
+ is absent, the JVM default language will be used.
+ </td>
+ </tr>
+ <tr>
+ <td>bundles@locale-default-country</td>
+ <td>String</td>
+ <td>[0|1]</td>
+ <td>
+ The default country to use if none is specified. If this attribute
+ is absent, the JVM default country will be used.
+ </td>
+ </tr>
+ <tr>
<td>bundles/bundle</td>
<td>String</td>
<td>[1..n]</td>
@@ -76,7 +171,7 @@
<subsection name="Component Configuration Example">
<source><![CDATA[
<localization>
- <bundles>
+ <bundles locale-default-language="en" locale-default-country="US">
<bundle>org.apache.fulcrum.localization.BarBundle</bundle>
<bundle>org.apache.fulcrum.localization.FooBundle</bundle>
</bundles>
Modified: turbine/fulcrum/trunk/pool/xdocs/index.xml
URL: http://svn.apache.org/viewvc/turbine/fulcrum/trunk/pool/xdocs/index.xml?rev=682777&r1=682776&r2=682777&view=diff
==============================================================================
--- turbine/fulcrum/trunk/pool/xdocs/index.xml (original)
+++ turbine/fulcrum/trunk/pool/xdocs/index.xml Tue Aug 5 09:32:32 2008
@@ -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>
+ ]]></source>
+ </subsection>
- <p>
- Now comes the basic configuration of the component. Here will will
- configure the various bundles.
- </p>
-<source>
+ <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>
-<![CDATA[
+ <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>