| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <document> |
| |
| <properties> |
| <title>Fulcrum Pool Component</title> |
| <author email="epugh@upstate.com">Eric PUgh</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Overview"> |
| |
| <p> |
| 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. |
| </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 constructors with parameters. |
| </p> |
| </section> |
| |
| <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> |
| </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> |
| <javax.xml.parsers.DocumentBuilder> |
| 256 |
| </javax.xml.parsers.DocumentBuilder> |
| <default> |
| 128 |
| </default> |
| </capacity> |
| </pool> |
| |
| <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. 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 = |
| service.getInstance("javax.xml.parsers.DocumentBuilder"); |
| |
| // Parse an XML document. |
| Document doc = parser.parse(myfile); |
| |
| // Return the parser to the pool. |
| service.putInstance(parser); |
| ]]></source> |
| |
| </section> |
| |
| </body> |
| </document> |
