PoolMan XML Quick Reference
PoolMan version 2.1

  •   DataSource XML Attributes
  •  Generic Pool XML Attributes
  •  JMX RI Admin Agent Attributes
  •  poolman.xml template


    <poolman>

    DataSource Connection Pool Attributes

    <datasource>

    XML Attribute
    Description
    Required
    <dbname>
    The name of the JDBC Connection pool
    yes
    <jndiName>
    The name used to bind the DataSource to JNDI
    yes
    <driver>
    The Class of the underlying Driver implementation

    EXAMPLE: org.postgresql.Driver

    yes
    <url>
    The URL that describes the database (vendor-specific)

    EXAMPLE: jdbc:postgresql://localhost:5432/empire

    yes
    <username>
    A user name valid for the database
    yes
    <password>
    The corresponding password valid for the user name
    yes
    <nativeResults>
    Whether to use the PoolMan cachable, scrollable, updatable ResultSet implementation or use the ResultSet returned by the underlying driver.

    DEFAULT: false

    no
    <poolPreparedStatements>
    Whether to pool PreparedStatements instead of recreating them with each invocation.

    DEFAULT: true

    no
    <txIsolationLevel>

    The transaction isolation level that should be set on each Connection object as it is created. The value of this element must be one of the following: NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ, SERIALIZABLE. For further explanation of these values, see the Sun javadocs for the isolation level fields in the java.sql.Connection class. These values are not case-sensitive.

    DEFAULT: READ_COMMITTED

    no
    <initialConnections>
    The number of connections to create when the pool is instantiated.

    DEFAULT: 1

    no
    <minimumSize>
    The minimum number of objects to retain in the pool.

    DEFAULT: 0

    no
    <maximumSize>
    The maximum number of objects that can possibly be maintained in the pool.

    DEFAULT: Integer.MAX_VALUE

    no
    <maximumSoft>
    If the maximum size of a pool is reached but requests are still waiting on objects, PoolMan will create new emergency objects if this value is set to true. This will temporarily increase the size of the pool, but the pool will shrink back down to acceptable size automatically when the skimmer activates. If this value is set to false, the requests will sit and wait until an object is available.

    DEFAULT: true

    no
    <connectionTimeout>

    The connection will be destroyed after living for this many seconds.

    DEFAULT: 1200 seconds (20 minutes)

    no
    <userTimeout>

    The length of time in seconds that user has to keep a connection before it is automatically returned to the pool.

    DEFAULT: 20 seconds

    no
    <skimmerFrequency>

    The length of time the pool skimmer waits between reap cycles. Each reap cycle involves evaluating all connections (both checked in and checked out) to determine whether to automatically return them to the pool and whether to destroy them if they have timed out.

    DEFAULT: 420 seconds (7 minutes)

    no
    <shrinkBy>

    Each time the pool is sized down by the skimmer, this value determines the maximum number of objects that can be removed from it in any one reap cycle. It prevents backing off the pool too quickly at peak times.

    DEFAULT: 5

    no
    <validationQuery>

    Each time a connection is requested, it is validated by the pool to ensure that it is active. If this element exists, then it is treated as a SQL query that is executed on the raw Connection (bypassing the cache) in order to ensure the Connection is valid. If this element does NOT exist (meaning it is null), then the Connection.isClosed() method is used to validate it instead. The Connection.isClosed() method is unreliable on some drivers (such as some Oracle drivers), which makes this element necessary for those drivers.

    DEFAULT: null

    no
    <logFile>

    The PATH to a file that this pool will append logging information to.

    DEFAULT: System.out

    no
    <debugging>

    Whether or not verbose logging information will be printed.

    DEFAULT: false

    no
    <cacheEnabled>

    Whether or not the query/ResultSet cache is enabled

    DEFAULT: false

    no
    <cacheSize>

    The maximum number of query/ResultSet pairs the cache can contain.

    DEFAULT: 5

    no
    <cacheRefreshInterval>

    The interval, in seconds, between the cache's reloading of its ResultSets from the database.

    DEFAULT: 30 seconds

    no
    <initialPoolSQL>

    A SQL String to be executed as soon as the pool is instantiated

    DEFAULT: none

    no
    <initialConnectionSQL>

    A SQL String to be executed every time a Connection is pulled from the pool.

    DEFAULT: none

    no
    <removeOnExceptions>

    Whether a SQLException even causes the Connection on which it occurred to be removed from the pool.

    DEFAULT: false

    no


    Generic Object Pool Attributes

    <objectPool>

    XML Attribute
    Description
    Required
    <name>
    The name of the pool.
    yes
    <objectType>
    The Class type of the objects pooled (must have a default no-args constructor).
    yes
    <initialObjects>

    The number of initial objects instances to create upon pool instantiation.

    DEFAULT: 1

    no
    <minimumSize>

    The minimum number of objects to maintain in this pool.

    DEFAULT: 0

    no
    <maximumSize>

    The maximum number of objects to maintain at any one time in this pool.

    DEFAULT: Integer.MAX_VALUE

    no
    <maximumSoft>
    If the maximum size of a pool is reached but requests are still waiting on objects, PoolMan will create new emergency objects if this value is set to true. This will temporarily increase the size of the pool, but the pool will shrink back down to acceptable size automatically when the skimmer activates. If this value is set to false, the requests will sit and wait until an object is available.

    DEFAULT: true

    no
    <objectTimeout>

    The length of time, in seconds, that each object has to live before being destroyed and removed from the pool.

    DEFAULT: 1200 seconds (20 minutes)

    no
    <userTimeout>

    The lenth of time, in seconds, that a client has to keep an object before it can automatically returned to its pool.

    DEFAULT: 20 seconds

    no
    <skimmerFrequency>

    The length of time the pool skimmer waits between reap cycles. Each reap cycle involves evaluating all objects (both checked in and checked out) to determine whether to automatically return them to the pool and whether to destroy them if they have timed out.

    DEFAULT: 660 seconds (11 minutes)

    no
    <shrinkBy>

    Each time the pool is sized down by the skimmer, this value determines the maximum number of objects that can be removed from it in any one reap cycle. It prevents backing off the pool too quickly at peak times.

    DEFAULT: 5

    no
    <logFile>

    The PATH to a file that this pool will append logging information to.

    DEFAULT: System.out

    no
    <debugging>

    Whether or not verbose logging information will be printed.

    DEFAULT: false

    no


    Administrative JMX Agent Attributes

    <admin-agent>

    <class>

    The Class of the HTML Agent implementation

    yes
    <name>

    The JMX ObjectName of the agent

    yes
    <maxClients>

    The maximum number of simultaneous browser-based users the Agent will support

    yes
    <port>

    The port number on which the HTML Agent will run

    yes

    </poolman>



    poolman.xml template

    <?xml version="1.0" encoding="UTF-8"?>

    <poolman>

    <!-- =============================================================== -->
    <!-- If the management-mode is JMX, then JMX will be used to deploy  -->
    <!-- all of the DataSource pools and object pools, and the JMX admin -->
    <!-- will be started for HTTP-based administration of pools. JMX     -->
    <!-- is somewhat heavy for applications that necessarily require it, -->
    <!-- and its internal ClassLoaders occasionally create conflicts.    -->
    <!-- Thus it can be commented out and not used.                      -->
    <!-- POSSIBLE VALUES: jmx, local                                     -->
    <!-- DEFAULT: local (JMX not used)                                   -->
    <!-- =============================================================== -->
    <management-mode>local</management-mode>

    <!-- ========================================================== -->
    <!-- These entries illustrate configuration of generic non-JDBC -->
    <!-- object pooling.                                            -->
    <!-- ========================================================== -->
    <objectPool>
    <name>mypool</name>
    <objectType>java.lang.StringBuffer</objectType>
    <initialObjects>10</initialObjects>
    <minimumSize>1</minimumSize>
    <maximumSize>10</maximumSize>
    <objectTimeout>6</objectTimeout>
    <userTimeout>12</userTimeout>
    <skimmerFrequency>300</skimmerFrequency>
    <shrinkBy>2</shrinkBy>
    <logFile>c:\code\src\poolman\lib\pool.log</logFile>
    <debugging>true</debugging>
    </objectPool>


    <!-- ========================================================== -->
    <!-- These entries are an example of JDBC Connection pooling.   -->
    <!-- Many of the parameters are optional. Consult the           -->
    <!-- UsersGuide.html doument for guidance and element           -->
    <!-- definitions.                                               -->
    <!-- ========================================================== -->

    <datasource>

    <!-- ============================== -->
    <!-- Physical Connection Attributes -->
    <!-- ============================== -->

    <!-- Standard JDBC Driver info -->
    <dbname>testdb</dbname>
    <jndiName>jndi-testdb</jndiName>
    <driver>org.postgresql.Driver</driver>
    <url>jdbc:postgresql://seamus:5432/empire</url>
    <username>poolman</username>
    <password>p00lm4n</password>

    <!-- Transaction Isolation Level, an optional value that, -->
    <!-- if present, must be one of the following:            -->
    <!-- NONE                                                 -->
    <!-- READ_COMMITTED                                       -->
    <!-- READ_UNCOMMITTED                                     -->
    <!-- REPEATABLE_READ                                      -->
    <!-- SERIALIZABLE                                         -->
    <!-- If the value is misspelled or ommitted, the default  -->
    <!-- will be applied. The value is not case-sensitive.    -->
    <!-- DEFAULT: READ_COMMITTED                              -->
    <txIsolationLevel>READ_COMMITTED</txIsolationLevel>


    <!-- If the following element is set to true, then PoolMan's  -->
    <!-- scrollable/updatable ResultSet will not be used, and the -->
    <!-- underlying driver's ResultSet will be used instead. This -->
    <!-- provides a performance gain in certain rare instances at -->
    <!-- the expense of functionality.                            -->
    <!-- DEFAULT: false                                           -->
    <nativeResults>false</nativeResults>


    <!-- ======================== -->
    <!-- Pool Behavior Attributes -->
    <!-- ======================== -->

    <!-- Connections created when the pool is instantiated -->
    <!-- DEFAULT: 1                                        -->
    <initialConnections>2</initialConnections>

    <!-- The pool will never shrink below this number -->
    <!-- DEFAULT: 0                                   -->
    <minimumSize>0</minimumSize>

    <!-- The pool will never grow larger than this value -->
    <maximumSize>10</maximumSize>

    <!-- If the maximum size of a pool is reached but requests -->
    <!-- are still waiting on objects, PoolMan will create new -->
    <!-- emergency objects if this value is set to true. This  -->
    <!-- will temporarily increase the size of the pool, but   -->
    <!-- the pool will shrink back down to acceptable size     -->
    <!-- automatically when the skimmer activates. If this     -->
    <!-- value is set to false, the requests will sit and wait -->
    <!-- until an object is available.                         -->
    <!-- DEFAULT: true                                         -->
    <maximumSoft>true</maximumSoft>

    <!-- The connection will be destroyed after living for a   -->
    <!-- duration of this value. IN SECONDS.                   -->
    <!-- DEFAULT: 1200 (20 minutes)                            -->
    <connectionTimeout>600</connectionTimeout>

    <!-- A user will lose a Connection and it will automatically -->
    <!-- return to its pool after the duration greater than or   -->
    <!-- equal to this value. If this value is set to 0 or less, -->
    <!-- no user timeout will be enforced. IN SECONDS.           -->
    <!-- DEFAULT: 20                                             -->
    <userTimeout>12</userTimeout>

    <!-- How frequently each object's connection timeout and  -->
    <!-- user timeout values will be examined for collection. -->
    <!-- IN SECONDS.                                          -->
    <!-- DEFAULT: 420 (7 minutes)                             -->
    <skimmerFrequency>300</skimmerFrequency>

    <!-- Each time the pool is sized down, how many connections -->
    <!-- should be removed from it? This value prevents backing -->
    <!-- off the pool too quickly.                              -->
    <shrinkBy>10</shrinkBy>

    <!-- Each time a connection is requested, it is validated by -->
    <!-- the pool to ensure that it is active. If this element   -->
    <!-- exists, then it is treated as a SQL query that is       -->
    <!-- executed on the raw Connection (bypassing the cache)    -->
    <!-- in order to ensure the Connection is valid. If this     -->
    <!-- element does NOT exist, then the Connection.isClosed()  -->
    <!-- method is used to validate it instead. The              -->
    <!-- Connection.isClosed() method is unreliable on some      -->
    <!-- drivers.                                                -->
    <!-- DEFAULT: null                                           -->
    <validationQuery>SELECT id FROM users</validationQuery>

    <!-- Where should log and debug information be printed? -->
    <!-- DEFAULT: System.out                                -->
    <logFile>c:\code\src\poolman\lib\log.txt</logFile>

    <!-- If set to true, the logger will display verbose info -->
    <!-- DEFAULT: false                                       -->
    <debugging>true</debugging>

    <!-- XA Connection TX Timeout attribute.  -->
    <!-- NOTE: MEASURED IN SECONDS.           -->
    <transactionTimeout>100</transactionTimeout>

    <!-- Query Cache Attributes-->

    <!-- If enabled, queries will be cached. The cache is -->
    <!-- asynchronously updated in the background.        -->
    <!-- DEFAULT: false                                   -->
    <cacheEnabled>true</cacheEnabled>

    <!-- The maximum number of query/ResultSet pairs the -->
    <!-- cache can contain.                              -->
    <!-- DEFAULT: 5                                      -->
    <cacheSize>10</cacheSize>

    <!-- How long the cache waits before re-loading its -->
    <!-- ResultSets from the underlying database.       -->
    <!-- IN SECONDS.                                    -->
    <!-- DEFAULT: 30                                    -->
    <cacheRefreshInterval>120</cacheRefreshInterval>

    <!-- A SQL statement to be executed when the pool is created.-->
    <!-- DEFAULT: none                                           -->
    <!--
    <initialPoolSQL>
    insert into users values(32, 'xml')
    </initialPoolSQL>
    -->

    <!-- A SQL statement to be excuted every time a Connection -->
    <!-- is accessed.                                          -->
    <!-- DEFAULT: none                                         -->
    <!--
    <initialConnectionSQL>
    insert into users values(1010, 'con')
    </initialConnectionSQL>
    -->

    <!-- Whether a SQLException should cause the Connection to -->
    <!-- be removed from the pool and destroyed.               -->
    <!-- DEFAULT: false                                        -->
    <removeOnExceptions>false</removeOnExceptions>

    </datasource>

    <!-- ==================================================== -->
    <!-- Another generic object pool, this one is used by     -->
    <!-- the PoolManServlet application                       -->
    <!-- ==================================================== -->
    <objectPool>
    <name>beanpool</name>
    <objectType>com.codestudio.util.PoolManBean</objectType>
    <initialObjects>6</initialObjects>
    <minimumSize>0</minimumSize>
    <maximumSize>50</maximumSize>
    <objectTimeout>1200</objectTimeout>
    <userTimeout>1200</userTimeout>
    <skimmerFrequency>300</skimmerFrequency>
    <shrinkBy>2</shrinkBy>
    <logFile>c:\code\src\poolman\lib\pool.log</logFile>
    <debugging>true</debugging>
    </objectPool>

    <!-- ========================================= -->
    <!-- Admin via JMX HTML Adapter. Disable this  -->
    <!-- (at least comment it out) for production  -->
    <!-- environments. When enabled, point your    -->
    <!-- web browser to the localhost:[port] to    -->
    <!-- view the JMX html admin agent.            -->
    <!-- This agent is not created if the          -->
    <!-- management-mode element above is set      -->
    <!-- to "local" instead of to "jmx"            -->
    <!-- ========================================= -->
    <admin-agent>
    <class>com.sun.jdmk.comm.HtmlAdaptorServer</class>
    <name>Adaptor:name=html</name>
    <maxClients>10</maxClients>
    <port>8082</port>
    </admin-agent>

    </poolman>