PoolMan XML Quick Reference

YAPoolMan XML Quick Reference
YAPoolMan version 1.0

· Overview

· PoolMan XML Elements

· JMX Elements

· DataSource XML Elements

· Object Pool XML Elements

· Factory XML Elements

· Server XML Elements

· poolman.xml sample

Overview

YAPoolMan xml config file contains information to control all aspect of the pool service. It is read into memory using Jakarta Commons-Digester. Every complex element has its own Java object represent, and the xml element name matches the class property name . You can also reference the JavaDoc of these classes for usage. A DTD file is also available to make write the config file easy using tools such as XMLSpy.

PoolManager Configuration Root

XML Element	Java Class
<poolman>	net.sf.yapoolman.config.PoolManInfo
Defines setting for the Pool Manager

XML Element	Description	Default
<jmx>?	Jmx setting
<global>	True to make a global pool manager, or create a pool manager at context level	false
<dataSource>*	JDBC connection pool setting
<objectPool>*	Object Pool setting

<top>

JMX XML Elements

XML Element	Java Class
<jmx>?	net.sf.yapoolman.config.JmxInfo
Defines setting for the JMX

XML Element	Description	Default
<serverName>?	MBeanServer name to register the services. If server can not be found, a new server will be created.	yapoolman
< domainName>?	domain name used to publish services.	DefaultDomain
< enabled >*	determine whether the JMX support should be enabled	false
< agentPort >?	the port number that Sun HTML adaptor will be listened to, default is -1, which means do not start the agent	-1

<top>

Datasource XML Elements

XML Element	Java Class
<dataSource>*	net.sf.yapoolman.config.JdbcPoolInfo
Defines setting for the jdbc pool. Because this class extends from object pool, all objectPool settings can be used and thus not described here. There’s one difference, jdbc pool treats the JNDI name as the name to bind data source service, while object pool use it to bind the pool itself.

XML Element	Description	Default
<dbName>	The name of the JDBC Connection pool, same as <name> of objectPool
<driver>?	The Class of the underlying Driver implementation EXAMPLE: org.postgresql.Driver
<url>?	The URL that describes the database (vendor-specific) EXAMPLE: jdbc:postgresql://localhost:5432/empire
<username>	A user name valid for the database
<password>	The corresponding password valid for the user name
<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.	READ_COMMITTED
<autoCommit>?	Whether to set connection auto commit before the connection is given to user	false
<connectionTimeout>?	Same as <objectTimeout> of objectPool	1200
<initPoolSql>?	A SQL String to be executed as soon as the pool is instantiated
<initialConnectionSql>?	A SQL String to be executed every time a Connection is pulled from the pool.
<validationSql>?	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.
<removeOnExceptions>?	Whether a SQLException even causes the Connection on which it occurred to be removed from the pool. The proxy handler will check the sql code of each exception, only negative value will be treat severe enough to remove the connection.	False
<initialConnections>?	The number of connections to create when the pool is instantiated. Same as <initObjects> of objectPool	1
<maximumSize>?	The maximum number of objects that can possibly be maintained in the pool.	Integer.MAX_VALUE

<top>

ObjectPool XML Elements

XML Element	Java Class
<objectPool>*	net.sf.yapoolman.config.PoolInfo
Defines setting for the object pool. Because this class is the base class of jdbc pool, all its setting can be used by jdbc pool.

XML Element	Description	Default
<name>	The name of the pool.
<jndiName>?	JNDI name to bind to JNDI service.
<initialObjects>?	The number of initial objects instances to create upon pool instantiation.	1
<objectTimeout>?	The length of time, in seconds, that each object has to live before being destroyed and removed from the pool.	1200
<userTimeout>?	The lenth of time, in seconds, that a client has to keep an object before it can automatically returned to its pool.	600
<requestTimeout>?	how long, in seconds, a user can wait for an available object when request from pool.	60
<maximumUseCount>?	how many times a pooled object can be used - check in/check out. After reach that time, it will be destroyed	No limit
<checkInterval>?	how long, in seconds, the check thread will check the status of pooled ojects. Any value less than 1 will be ignored, and any value greater than 600 will be treated as 600	60
<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.	5
<proxyHandler>?	class name of the proxy handler. If it is set, the pool will return the dynamic proxy having interfaces as indicated by proxyInterfaces. The handler will be called before and after the proxy invication, and process the exception caught. The proxy is created for the native object, which means, if the object the factory created is not an instance of PooledObject, it is treat as native, or, the pooledObject.getNative() will be called to retrieve the native object.
<proxyInterfaces>?	the interfaces of the dynamic proxy, separated by comma. The first interface's class loader will be used to create the proxy. Must provided if proxyHandler is set
<sticky>?	whether keep focus on the objects recently used, which means, a pooled object most recently gets used will be more likely being served again. Otherwise, an object have longer waiting time in pool will have higher priority to serve. Default is true.
<logger>?	log name or category
<factory>?	factory setting, see Factory XML Elements

<top>

Factory XML Elements

XML Element	Java Class
<factory>?	net.sf.yapoolman.config.FactoryInfo
Defines setting for the factory, which will create object for pool to serve to end user.

XML Element	Description	Default
<type>?	factory class name, PoolMan will determine your setting and choose the right factory between SimpleFactory - when only one server is defined and MultipleFactory - when more than more server setting are defined. However, you can write your own factory and use it.
<objectType>	object class name which is created by factory, must be provided	Only optional for JDBC
< checkInterval>?	in seconds, determine how long the check thread will wait between each check process. A number greater than 600 seconds will be treated as 600 seconds.	60
< maximumSoft>?	determine whether more objects can be created even when max size is reached	false
<logger>?	logger name/category used by this factory
<servers>?	store all server config information. At least one server should be defined. Server settings are the <server> elements of <servers>.

<top>

Server XML Elements

XML Element	Java Class
<server>*	net.sf.yapoolman.config.ServerInfo
Defines server settings, it is used by factory to create objects.

XML Element	Description	Default
<name>	name of the server. The difference between server name and pool name is that a pool can contain objects of different servers, thus can be treat as the name of the group of the servers
<maxConnection>?	how many connections can be created for the server	Integer.MAX_VALUE
<priority>?	servers with higher priority will always be used unless either they all have problems or they are all reached their max connections.
<weight>	determine the ratio that the factory will pick the server to generate new connections. Weight only used for servers have same priority. For example, server A has weight of 1 and server B has 2, the factory will create 2 connections of server B while 1 connection for server A in every 3 new connections it creates.
<busyStandby>?	the server will only be used when all other servers are busy - reach their max connections	false
<failStandby>?	the server will only be used when all other servers have problem	false
<param>*	name/value pairs which can be used to define other server settings used to create object. <param> has two xml elements, <name> define the key of the pair, and <value> set the value of the pair.

Administrative JMX Agent Elements <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

<top>

poolman.xml template

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

<jmx>

<serverName>YAPoolMan</serverName>

<defaultDomain>poolman</defaultDomain>

<enabled>false</enabled>

</jmx>

<name>mypool</name>

<jndiName>java:pool:mypool</jndiName>

<proxyHandler>my.package.MyProxyHandler</proxyHandler>

<proxyInterface>my.package.IService</proxyInterface>

<logger>net.sf.yapoolman.pool.mypool</logger>

<type>net.sf.yapoolman.factory.SimpleFactory</type>

<objectType>java.lang.StringBuffer</objectType>

<logger>net.sf.yapoolman.pool.mypool.factory</logger>

<name>server1</name>

<busyStandby>false</busyStandby>

<failStandby>false</failStandby>

<param>

<name>server</name>

</param>

<param>

</param>

</server>

<name>server2</name>

<busyStandby>false</busyStandby>

<failStandby>false</failStandby>

<param>

<name>server</name>

</param>

<param>

</param>

</server>

</factory>

</objectPool>

<name>anotherpool</name>

<type>net.sf.yapoolman.factory.SimpleFactory</type>

<objectType>java.lang.StringBuffer</objectType>

<logger>net.sf.yapoolman.pool.mypool.factory</logger>

<name>server1</name>

<param>

<name>server</name>

</param>

<param>

</param>

</server>

</factory>

</objectPool>

<dbName>testdb</dbName>

<jndiName>java:db:testdb</jndiName>

<driver>org.hsqldb.jdbcDriver</driver>

<url>jdbc:hsqldb:.</url>

<txIsolationLevel>READ_COMMITTED</txIsolationLevel>

insert into users values(32, 'xml')

</initialPoolSql>

insert into users values(1010, 'con')

</initialConnectionSql>

<validationSql>SELECT id FROM users</validationSql>

<removeOnExceptions>false</removeOnExceptions>

<name>server1</name>

<param>

<value>java:jdbc:hsqldb:testdb</value>

</param>

</server>

</factory>

</datasource>

</poolman>

<top>

YAPoolMan XML Quick Reference YAPoolMan version 1.0

YAPoolMan XML Quick Reference
YAPoolMan version 1.0