org.osesb.objectpools
Class DOMPoolFactory

java.lang.Object
  org.osesb.objectpools.ObjectPoolFactory
      org.osesb.objectpools.DOMPoolFactory

public class DOMPoolFactory
extends ObjectPoolFactory

This class is a factory for homogeneous object pools of JAXP compliant DOM Parsers (DocumentBuilder), all with the same configuration. This class is is a thread-safe singleton, so only one instance of DOMPoolFactory and its associated ObjectPool instance will exist per class loader.

Pools of DOM parsers (DocumentBuilders) are useful in multi-threaded environments, such as MDBs, where there are multiple threads using DOM parsers. Instead of repeatedly creating parsers, java Classes call getObject() on a pool of DOM Parsers and call returnObject() when finished parsing.

PooledParserAccessHelper is a helper class for accessing pooled SAX and DOM parsers.

This class uses org.apache.commons.pool.impl.GenericObjectPool as the pool implementation. It is a good model for creating other homogeneous object pools, which are pools that contain the same kinds of objects.

There is a known issue with validating against XML schemas using parsers from a pool implemented using the org.apache.commons.pool package. See org.osesb.objectpools.test.ThreadedPooledValidatingSAXParserTest. For now, the framework uses non-pooled SAX parsers for:

• jaxp v1.2 style validation, where the schema sources are set using parser properties.
• Validation using a org.xml.sax.EntityResolver to resolve schema declarations to locations in the configured instance of the XML repository.

This factory uses a configuration file to load a DOM DocumentBuilder pool. The configuration contains a pool content model, which defines the characteristics of the pool and a jaxp-dom content model, which defines the properties for the DocumentBuilder ( e.g. namespaceAware).

Object pool configurations must be stand-alone configuration files with all configurations specified in-line.

Object pool configurations cannot be embedded in another configuration file and then referenced externally using XPath. In addition, all pooled object configurations must be specified in-line and cannot use the 'configFile' attribute to redirect the configuration to an external file.

This factory's getPool() method loads the configured instance of the DOM DocumentBuilder pool using the following plan to load the DOMPoolFactory configuration file:

1. The configuration file given by the System property named ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY.
2. The configuration file given by the ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE.
3. The default configuration file given by ObjectPoolConstants.DEFAULT_POOLEDDOMPARSER_CONFIGFILE.

The configuration for the framework's default DOM DocumentBuilder pool is config/pooled-dom-parser-config.xml, which looks like:

<!-- standard framework configuration for a pool of DOM DocumentBuilder(s)  -->
      <pooled-dom-parser>
          <!-- The pool configuration. These are the properties for jakarta-commons-pooling. -->
          <pool-configuration>
              <!-- an optional name for the pool -->
              <poolName>osESB Non-Keyed DOM Parser Pool</poolName>
              <!-- display a pool heartbeat message every heartbeatInterval seconds -->
              <heartbeatInterval>300</heartbeatInterval>
              <!-- debugFlag -->
              <debugFlag>true</debugFlag>
              <!-- parameters that are specific to the pool implementation go here -->
              <!-- these are the config properties for jakarta-commons-pooling -->
              <!-- GenericObjectPool Config -->
              <maxIdle></maxIdle>
              <!-- No limit to the number of objects -->
              <maxActive>-1</maxActive>
              <maxWait>-1</maxWait>
              <!-- Grow the pool when a borrowobject() fails -->
              <whenExhaustedAction>2</whenExhaustedAction>
              <testOnBorrow>false</testOnBorrow>
              <testOnReturn>false</testOnReturn>
              <testWhileIdle>false</testWhileIdle>
              <!-- check for idle objects every 6 minutes (normally) -->
              <timeBetweenEvictionRunsMillis>360000</timeBetweenEvictionRunsMillis>
              <numTestsPerEvictionRun></numTestsPerEvictionRun>
              <!-- evict objects idle more than 5 minutes (normally) -->
              <minEvictableIdleTimeMillis>300000</minEvictableIdleTimeMillis>
              <!-- display pool startup message -->
              <displayStartupMessageFlag>true</displayStartupMessageFlag>
          </pool-configuration>
          <!-- the pooled DocumentBuilder configuration using JAXP -->
          <jaxp-configuration>
              <!-- use parser factory defaults - ignore parser property elements -->
              <useDefaultParserConfigurationFlag>false</useDefaultParserConfigurationFlag>
              <!-- do not use parser factory defaults - set these properties excplicitly -->
              <!-- used when validating against schems -->
              <!-- namespaceAware should always be true, validating or not -->
              <namespaceAware>true</namespaceAware>
              <validating>false</validating>
              <!-- null for dtd -->
              <schemaLanguage>http://www.w3.org/2001/XMLSchema</schemaLanguage>
          </jaxp-configuration>
      </pooled-dom-parser>
 

To use this Class:

1. To override the default pool configuration file, set the System property defined by org.osesb.objectpools.ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY to the pool configuration file or set a DOMPOOLCONFIGFILE_PROPERTY entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE.
2. Call DOMPoolFactory.getInstance() to get the singleton instance of this factory.
3. Call getPool(), which creates, if necessary, the single instance of the homogeneous, DOM DocumentBuilder pool that will exist for the ClassLoader that loads this factory.
4. Call the pool methods getObject() to obtain a DocumentBuilder from the pool and returnObject() to return a DocumentBuilder to the pool.

Generally, framework components do not directly invoke methods on this factory or the pool that it returns. Instead, framework components that use pooled DocumentBuilder(s) invoke methods in org.osesb.objectpools.PooledParserAccessHelper to parse XML or to obtain DocumentBuilders for creating XML.

Note: A pooled DocumentBuilder cannot be used to validate documents using jaxp v1.2-style validation because the schemaSource is specified as an attribute of the DocumentBuilderFactory. This is in contrast to SAX which sets a schemaSource property on the parser. The objects returned by the DOM pool that is managed by this factory are DocumentBuilder(s), not DocumentBuilderFactory(s). Therefore, there is no way to set the schemaSource on the objects returned from the DOM pool. This is why the framework does not include a keyed DocumentBuilder pool with keys for the namespaceAware and validating features of DOM parsers. See the org.osesb.utilities.xml.validation package, which contains helper Classes for validating using jaxp v1.2 and jaxp v1.3 SAX parsers.

Since:

Version .9

Nested Class Summary

protected static class

DOMPoolFactory.JAXPDOMPoolableObjectFactory Inner class that implements org.apache.commons.pool.PoolableObjectFactory, which is instantiated by the enclosing class and passed to GenericObjectPool's constructor.

Field Summary

protected static JAXPParserConfiguration	jaxpConfiguration The configuration for the JAXP DOM Parsers in the pool.
protected static ObjectPoolConfiguration	poolConfiguration The configuration for the object pool.
protected static DOMPoolFactory	poolFactoryInstance Singleton pattern - thread-safe construction.
protected static ObjectPool	poolInstance The instance of the objectpool we will create.
protected static java.lang.String	thisClassName The full name of this class

Fields inherited from class org.osesb.objectpools.ObjectPoolFactory

log

Constructor Summary

protected

DOMPoolFactory() Singleton pattern - cannot be instantiated directly.

Method Summary

static ObjectPoolFactory	getInstance() Singleton pattern - - returns the instance of this class.
ObjectPool	getPool() Construct (if necessary) and return the single instance of the homogeneous DOM parser pool using the following plan to load the DOMPoolFactory configuration file: The configuration file given by the System property named ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY. The configuration file given by the ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE. The default configuration file given by ObjectPoolConstants.DEFAULT_POOLEDDOMPARSER_CONFIGFILE.
static void	main(java.lang.String[] args) Main method for testing and sandboxing.
void	resetPoolInstance() Close the pool and reset the poolInstance.

Methods inherited from class org.osesb.objectpools.ObjectPoolFactory

getPoolConfig

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

poolInstance

protected static ObjectPool poolInstance

The instance of the objectpool we will create.

poolConfiguration

protected static ObjectPoolConfiguration poolConfiguration

The configuration for the object pool.

thisClassName

protected static java.lang.String thisClassName

The full name of this class

poolFactoryInstance

protected static DOMPoolFactory poolFactoryInstance

Singleton pattern - thread-safe construction.

jaxpConfiguration

protected static JAXPParserConfiguration jaxpConfiguration

The configuration for the JAXP DOM Parsers in the pool.

Constructor Detail

DOMPoolFactory

protected DOMPoolFactory()

Singleton pattern - cannot be instantiated directly.

Method Detail

getInstance

public static ObjectPoolFactory getInstance()

Singleton pattern - - returns the instance of this class. Callers can then call getPool() to get the object pool.

Returns:

the singleton instance of this class.

getPool

public ObjectPool getPool()
                   throws java.lang.Exception

Construct (if necessary) and return the single instance of the homogeneous DOM parser pool using the following plan to load the DOMPoolFactory configuration file:

1. The configuration file given by the System property named ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY.
2. The configuration file given by the ObjectPoolConstants.DOMPOOLCONFIGFILE_PROPERTY entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE.
3. The default configuration file given by ObjectPoolConstants.DEFAULT_POOLEDDOMPARSER_CONFIGFILE.

Specified by:

getPool in class ObjectPoolFactory

Returns:

an instance of the configured homogeneous object pool.

Throws:

java.lang.Exception - if a fatal error is encountered while instantiating the object pool.

resetPoolInstance

public void resetPoolInstance()

Close the pool and reset the poolInstance.

Specified by:

resetPoolInstance in class ObjectPoolFactory

main

public static void main(java.lang.String[] args)

Main method for testing and sandboxing.

Parameters:

args -