Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.osesb.objectpools.configuration
Class KeyedObjectPoolConfiguration

java.lang.Object
  extended by org.osesb.configuration.XMLConfiguration
      extended by org.osesb.objectpools.configuration.KeyedObjectPoolConfiguration

public class KeyedObjectPoolConfiguration
extends XMLConfiguration

The framework uses the Apache Pool Package (org.apache.commons.pool) to:

The object pools defined in org.osesb.objectpools are configured in two sections of a XML configuration file. The first section <pool-configuration> configures the pool itself, the second section configures the objects in the pool. While the pool configuration is mostly the same across object pool implementations, the pooled object configuration(s) are specific to the object being pooled. For example, 1) JMS connection properties for pooled JMS clients, and 2) SAX parser properties for pooled SAX parsers.

This classs, KeyedObjectPoolConfiguration is used to configure a pool of heterogeneous objects, where each object is managed by a seperate pool that is identified by a pool key. The example, below, illustrates the configuration for a pool of SAX parsers with different namespaceAware properties.

This Class uses ObjectPoolConfiguration for the pool configuration and creates a Map of XMLConfigurations for the pooled objects.

The framework uses the Apache Pool Package (org.apache.commons.pool) to:

The object pools defined in org.osesb.objectpools are configured in two sections of a XML configuration file. The first section <pool-configuration> configures the pool itself, the second section configures the objects in the pool. While the pool configuration is mostly the same across object pool implementations, the pooled object configuration(s) are specific to the object being pooled. For example, 1) JMS connection properties for pooled JMS clients, and 2) SAX parser properties for pooled SAX parsers.

The Apache Pool Package defines two types of pools:

This Class, KeyedObjectPoolConfiguration, is the configuration for heterogeneous pools that use the Apache GenericKeyedObjectPool class. This Class encapsulates the pool configuration using an ObjectPoolConfiguration and encapsulates the pooled object configurations using a XMLConfigurationIterator.

Object pool configurations must be stand-alone configuration files. Although the XML Configuration framework supports XPath expressions to content model root elements, object pool configurations cannot be included in another configuration file and then referenced using XPath.

The example, below, is a configuration for a pool of heterogeneous SAX parsers, with different namespaceAware and validating properties. SAXKeyedPoolFactory uses a configuration like this to construct the pool. This Class, KeyedObjectPoolConfiguration, encapsulates the <pool-configuration> content model using an ObjectPoolConfiguration and encapsulates the JAXPParserConfiguration(s) using a XMLConfigurationIterator 

<key-pooled-sax-parsers>
          <pool-configuration>
              <!-- an optional name for the pool -->
              <poolName>osESB Keyed SAX Parser Pool</poolName>
              <!-- a heartbeatInterval for the pool in 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>
          <!-- non-validating, namespaceaware is false -->
          <jaxp-configuration poolKey="namespaceaware-false">
              <!-- the class that is pooled, not required for XML Parser pools -->
              <pooled-class></pooled-class>
              <!-- 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>false</namespaceAware>
              <validating>false</validating>
              <!-- null for dtd -->
              <schemaLanguage>http://www.w3.org/2001/XMLSchema</schemaLanguage>
          </jaxp-configuration>
          <!-- non-validating, namespaceaware is true -->
          <jaxp-configuration poolKey="namespaceaware-true">
              <!-- the class that is pooled, not required for XML Parser pools -->
              <pooled-class></pooled-class>
              <!-- 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>
          <jaxp-configuration poolKey="validating">
              <!-- the class that is pooled, not required for XML Parser pools -->
              <pooled-class></pooled-class>
              <!-- 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>true</validating>
              <!-- null for dtd -->
              <schemaLanguage>http://www.w3.org/2001/XMLSchema</schemaLanguage>
          </jaxp-configuration>
      </key-pooled-sax-parsers>

Keyed object pool implementations use this configuration to create object pools. Object pools are in the org.osesb.objectpools package.

Since:
Version .9

Field Summary
protected  ObjectPoolConfiguration poolConfiguration
          The configuration for the pool.
protected  XMLConfigurationIterator pooledObjectConfigurations
          The XMLConfiguration(s) for the pooled objects.
 
Fields inherited from class org.osesb.configuration.XMLConfiguration
configFilePath, configurationProperties, constructedFromConfigFile, contentModelElement, ftpClientConfiguration, jaxrpcClientConfiguration, jdbcConfiguration, jmsClientConfiguration, log, rootConfigurationAttributes, smtpClientConfiguration, systemProperties, thisClassName
 
Constructor Summary
KeyedObjectPoolConfiguration(ObjectPoolConfiguration poolConfiguration)
          Creates a new instance of KeyedObjectPoolConfiguration with just an ObjectPoolConfiguration.
KeyedObjectPoolConfiguration(java.lang.String configFile, java.lang.String xpathExpression, java.lang.String poolContentModelTagName, java.lang.String pooledObjectContentModelTagName)
          Creates a new instance of KeyedObjectPoolConfiguration.
KeyedObjectPoolConfiguration(java.lang.String configFile, java.lang.String xpathExpression, java.lang.String poolContentModelTagName, java.lang.String pooledObjectContentModelTagName, java.lang.Class xmlConfigurationClass)
          Creates a new instance of KeyedObjectPoolConfiguration.
 
Method Summary
 long getHeartbeatInterval()
          Returns optional the heartbeatInterval, which defines the number of seconds between "health" messages that a pool may write or send to a log provider, like log4j.
 ObjectPoolConfiguration getPoolConfiguration()
          Returns the configuration for the pool.
 java.lang.String getPooledClassName(java.lang.String poolKey)
          Returns the className of the pooled object from the configuration.
 XMLConfiguration getPooledObjectConfiguration(java.lang.String poolKey)
          Returns the XMLConfiguration for one of the pooled objects by poolKey.
 XMLConfigurationIterator getPooledObjectConfigurations()
          Returns the configuration for the pooled objects.
 java.lang.String[] getPoolKeys()
          Return the pool keys as a String[].
 java.lang.String getPoolName()
          Returns the optional name for this pool.
protected  void loadPooledObjectConfigurations(java.lang.String pooledObjectContentModelTagName, java.lang.Class xmlConfigurationClass)
          Loads pooledObjectConfigurations, with the pooled object configurations, keyed by the poolKey attribute of the individual content models.
static void main(java.lang.String[] args)
          Main method for testing.
 void setPooledClassName(java.lang.String poolKey, java.lang.String pooledClassName)
          Sets the className of the pooled object.
 java.lang.String toString()
          Returns the String representation of this KeyedObjectPoolConfiguration.
 
Methods inherited from class org.osesb.configuration.XMLConfiguration
checkXMLConfigurationClass, clear, doEncryptionInstructions, getBooleanConfigurationProperty, getBooleanRootConfigurationAttribute, getConfigFilePath, getConfigurationAttribute, getConfigurationAttributes, getConfigurationElement, getConfigurationElements, getConfigurationProperties, getConfigurationProperty, getConfigurationProperty, getContentModelElement, getDebugFlag, getDocument, getEncryptionInstructions, getFTPClientConfiguration, getIntConfigurationProperty, getIntRootConfigurationAttribute, getJAXRPCClientConfiguration, getJDBCConfiguration, getJMSClientConfiguration, getLongConfigurationProperty, getLongRootConfigurationAttribute, getName, getRootConfigurationAttribute, getRootConfigurationAttributes, getSMTPClientConfiguration, getSystemProperties, getSystemProperty, isConfigurationElementEmpty, loadConfiguration, loadExternalConfiguration, loadFTPClientConfiguration, loadJAXRPCClientConfiguration, loadJDBCConfiguration, loadJMSClientConfiguration, loadPropertiesFromContentModel, loadSMTPClientConfiguration, loadSystemProperties, mergeConfigurationProperties, setConfigFilePath, setConfigurationProperty, setDebugFlag, setFTPClientConfiguration, setJAXRPCClientConfiguration, setJDBCConfiguration, setJMSClientConfiguration, setName, setRootConfigurationAttribute, setSMTPClientConfiguration, setSystemProperties, setSystemProperty, writeConfigurationFile, writeConfigurationFile
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

poolConfiguration

protected ObjectPoolConfiguration poolConfiguration
The configuration for the pool. These are the properties needed by the Apache Pool Package (org.apache.commons.pool).

pooledObjectConfigurations

protected XMLConfigurationIterator pooledObjectConfigurations
The XMLConfiguration(s) for the pooled objects.

Constructor Detail

KeyedObjectPoolConfiguration

public KeyedObjectPoolConfiguration(java.lang.String configFile,
                                    java.lang.String xpathExpression,
                                    java.lang.String poolContentModelTagName,
                                    java.lang.String pooledObjectContentModelTagName)
                             throws java.lang.Exception
Creates a new instance of KeyedObjectPoolConfiguration.

Parameters:
configFile - The path to the XML configuration file, which is specified as a resource path or as a file system path that is relative to the path specified by the ConfigurationConstants.CONFIG_PATH_SYSTEMPROPERTY System Property.
xpathExpression - A XPath expression that evaluates to the element that marks the beginning of the configuration. as the last Element in the path.
poolContentModelTagName - The Tag Name of the Element that contains the content model for the pool. These are the Apache Pool properties. If following the framework convention for ObjectPoolConfiguration(s), poolContentModelTagName should have a value of 'pool-configuration'.
pooledObjectContentModelTagName - The tag name of the Element that contains the repeating configurations for the pooled objects.
Throws:
java.lang.Exception - if there is a problem reading or parsing the configuration file.

KeyedObjectPoolConfiguration

public KeyedObjectPoolConfiguration(java.lang.String configFile,
                                    java.lang.String xpathExpression,
                                    java.lang.String poolContentModelTagName,
                                    java.lang.String pooledObjectContentModelTagName,
                                    java.lang.Class xmlConfigurationClass)
                             throws java.lang.Exception
Creates a new instance of KeyedObjectPoolConfiguration.

Parameters:
configFile - The path to the XML configuration file, which is specified as a resource path or as a file system path that is relative to the path specified by the ConfigurationConstants.CONFIG_PATH_SYSTEMPROPERTY System Property.
xpathExpression - A XPath expression that evaluates to the element that marks the beginning of the configuration. as the last Element in the path.
poolContentModelTagName - The Tag Name of the Element that contains the content model for the pool. These are the Apache Pool properties. If following the framework convention for ObjectPoolConfiguration(s), poolContentModelTagName should have a value of 'pool-configuration'.
pooledObjectContentModelTagName - The tag name of the Element that contains the repeating configurations for the pooled objects.
xmlConfigurationClass - The XML Configuration Class for pooledObjectConfigurations, which must be XMLConfiguration or a subclass of XMLConfiguration and that must have a Constructor that takes a single argument of Class org.w3c.dom.Element.
Throws:
java.lang.Exception - if there is a problem reading or parsing the configuration file.

KeyedObjectPoolConfiguration

public KeyedObjectPoolConfiguration(ObjectPoolConfiguration poolConfiguration)
                             throws java.lang.Exception
Creates a new instance of KeyedObjectPoolConfiguration with just an ObjectPoolConfiguration. Initially, the KeyedObjectPoolConfiguration contains no pooled object configurations.

Could be useful in situations where a keyed pool does not create pooled object configurations, at least initially.

So far, this constructor is not used, but was tested during sandboxing for the Thread pool factory, which initially was thought to be a keyed pool without an initial pooled object configuration. So this constructor is an unused remnant of thread pool development.

Parameters:
poolConfiguration - The configuration for the pool.
Throws:
java.lang.Exception - if invoked with a null poolConfiguration.
Method Detail

loadPooledObjectConfigurations

protected final void loadPooledObjectConfigurations(java.lang.String pooledObjectContentModelTagName,
                                                    java.lang.Class xmlConfigurationClass)
                                             throws java.lang.Exception
Loads pooledObjectConfigurations, with the pooled object configurations, keyed by the poolKey attribute of the individual content models.

Note that this method should not be overridden as it is invoked from this class's constructor.

Parameters:
pooledObjectContentModelTagName - The tag name of the Element that contains the repeating conetent models for the pooled objects.
xmlConfigurationClass - The XML Configuration Class for pooledObjectConfigurations, which must be XMLConfiguration or a subclass of XMLConfiguration and that must have a Constructor that takes a single argument of Class org.w3c.dom.Element.
Throws:
java.lang.Exception - if there is a fatal error transversing the DOM Document that contains the configuration content model.

getPoolConfiguration

public ObjectPoolConfiguration getPoolConfiguration()
Returns the configuration for the pool.

Returns:
the configuration for the pool.

getPooledObjectConfigurations

public XMLConfigurationIterator getPooledObjectConfigurations()
Returns the configuration for the pooled objects.

Returns:
the configuration for the pooled objects.

getPoolKeys

public java.lang.String[] getPoolKeys()
Return the pool keys as a String[].

Returns:
the pool key Strings.

getPooledObjectConfiguration

public XMLConfiguration getPooledObjectConfiguration(java.lang.String poolKey)
Returns the XMLConfiguration for one of the pooled objects by poolKey.

Parameters:
poolKey - The key for the pooled object in the heterogeneous pool.
Returns:
the XMLConfiguration for one of the pooled objects by poolKey.

getPooledClassName

public java.lang.String getPooledClassName(java.lang.String poolKey)
Returns the className of the pooled object from the configuration.

Parameters:
poolKey - The key for the pooled object in the heterogeneous pool.
Returns:
the className of the pooled object.

setPooledClassName

public void setPooledClassName(java.lang.String poolKey,
                               java.lang.String pooledClassName)
Sets the className of the pooled object. The className of the pooled object is usually known in advance. This method supports run time determination of an underlying implementation that is returned by a factory. For example, the parser implementaion returned by JAXP is not known until the factory returns a parser object.

Parameters:
poolKey - The key for the pooled object in the heterogeneous pool.
pooledClassName - The className of the pooled object.

getPoolName

public java.lang.String getPoolName()
Returns the optional name for this pool.

Returns:
the pool name.

getHeartbeatInterval

public long getHeartbeatInterval()
Returns optional the heartbeatInterval, which defines the number of seconds between "health" messages that a pool may write or send to a log provider, like log4j.

Returns:
the heartbeatInterval for the pool.

toString

public java.lang.String toString()
Returns the String representation of this KeyedObjectPoolConfiguration.

Overrides:
toString in class XMLConfiguration
Returns:
the String representation of this KeyedObjectPoolConfiguration.

main

public static void main(java.lang.String[] args)
Main method for testing.

Parameters:
args -
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD