Overview

The Pool Service extends the functionality of the Factory Service by adding support for pooling objects instantiated 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.

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.

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.

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.

Configuration

Role Configuration

This component requires the FactoryService component. 

    <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"/>

Component Configuration

Item Datatype Cardinality Description
capacity Complex [0|1] The parent element for defining pool capacities. Sub-elements define capacities for certain class names. You can define one default pool that will be used if no others match. If not specified, a default capacity of 128 is used. See the configuration example below.

Component Configuration Example

    <pool>
        <capacity>
            <javax.xml.parsers.DocumentBuilder>
                256
            </javax.xml.parsers.DocumentBuilder>
            <default>
                128
            </default>
        </capacity>
    </pool>

    <factory>
        ...
    </factory>

Usage

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. 

// Access the service singleton.
PoolService service = (PoolService)container.lookup(PoolService.ROLE);

// Get a pooled DOM parser.
DocumentBuilder parser =
    service.getInstance("javax.xml.parsers.DocumentBuilder");

// Parse an XML document.
Document doc = parser.parse(myfile);

// Return the parser to the pool.
service.putInstance(parser);