org.osesb.objectpools
Class SAXPoolFactory

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

public class SAXPoolFactory
extends ObjectPoolFactory

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

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

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 SAX parser pool. The configuration contains a pool content model, which defines the characteristics of the pool and a jaxp-sax content model, which defines the properties for the SAX parser (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.

The framework does not include a default configuration for a homogeneous pool of SAX parsers. This is because the framework's default SAX parser pool is a keyed, heterogeneous pool of SAX parsers with different namespaceAware and validating properties. This factory's getPool() method loads a SAX parser pool according to the following plan:

1. The configuration file given by the System property named ObjectPoolConstants.SAXPOOLCONFIGFILE_PROPERTY.
2. The configuration file given by the ObjectPoolConstants.SAXPOOLCONFIGFILE_PROPERTY entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE.

A configuration for a homogeneous pool of jaxp DOM DocumentBuilders or SAX parsers parsers looks like:

<pooled-jaxp-parser>
          <!-- The pool configuration. These are the properties for jakarta-commons-pooling. -->
          <pool-configuration>
              <!-- an optional name for the pool -->
              <poolName>osESB Test Non-Keyed 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 or SAX parser configuration -->
          <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-jaxp-parser>
 

To use this Class:

1. Set ObjectPoolConstants.SAXPOOLCONFIGFILE_PROPERTY to the path of a configuration file for the pool. SAXPOOLCONFIGFILE_PROPERTY is set as a System property or as an entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE.
2. Call SAXPoolFactory.getInstance() to get the singleton instance of this factory.
3. Call getPool(), which creates, if necessary, the single instance of the homogeneous, SAX parser pool that will exist for the ClassLoader that loads this factory.
4. Call the pool methods getObject() to obtain a SAX parser from the pool and returnObject() to return a SAX parser to the pool.

Since:

Version .9

Nested Class Summary

protected static class

SAXPoolFactory.JAXPSAXPoolableObjectFactory 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 SAX Parsers in the pool.
protected static ObjectPoolConfiguration	poolConfiguration The configuration for the object pool.
protected static SAXPoolFactory	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

SAXPoolFactory() Singleton pattern - cannot be instantiated directly.

Method Summary

static ObjectPoolFactory	getInstance() Singleton pattern - - returns the instance of this class.
ObjectPool	getPool() There is no default configuration file for a homogeneous pool of SAX parsers.
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 SAXPoolFactory poolFactoryInstance

Singleton pattern - thread-safe construction.

jaxpConfiguration

protected static JAXPParserConfiguration jaxpConfiguration

The configuration for the JAXP SAX Parsers in the pool.

Constructor Detail

SAXPoolFactory

protected SAXPoolFactory()

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

There is no default configuration file for a homogeneous pool of SAX parsers. This is because the framework's default SAX parser pool is a keyed, heterogeneous pool of SAX parsers with different namespaceAware and validating properties. So, load the SAXPoolFactory configuration file according to the following plan:

1. The configuration file given by the System property named ObjectPoolConstants.SAXPOOLCONFIGFILE_PROPERTY.
2. The configuration file given by the ObjectPoolConstants.SAXPOOLCONFIGFILE_PROPERTY entry in a properties file named ObjectPoolConstants.OBJECTPOOLCONFIGURATIONS_PROPERTIES_FILE.

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 -