YAPoolMan
User's Guide
|
||||
|
1.1 Summary |
|
||
|
||||
|
2.1 STEP ONE: YAPoolMan JAR file and your database driver |
|
||
3.0 Usage |
||||
|
3.1 JDBC: JNDI and DataSource usage |
|
||
|
||||
|
4.1 Enabling and Disabling JMX |
|
||
|
||||
|
6.1 The poolman.xml configuration file in detail |
|
||
1.0 Overview |
||||
|
YAPoolMan is an embeddable object pooling and caching library. It optimizes resource usage by managing reusable instances across multiple requests. It can be used to pool any Java Class type, and contains specialized features -- such as a JDBC DataSource and JDBC Driver implementations for JDBC resource pooling. It is designed to be embeddable, so it instantiates its underlying server lazily (that is, upon receipt of the first request) rather than requiring an explicit root configuration and startup semantics. Programmers can get pooled object from pool by calling its specific API. The pool is retrieved using: o PoolManager o JNDI naming service. However, you must
explicitly start YAPoolMan if you want to use the second way. XXXXXXXXXXX add multi
server and handler XXXXXXX The JDBC connection pooling is just same as normal object pooling, while it has some more specific programmatic views, i.e. API's, or behaves slightly different. The differing API's all provide exactly the same underlying functionality, the variety of views exist merely to satisfy different programming styles and designs. The JDBC-related views are: · JDBC Driver implementation · JDBC DataSource implementation through JNDI service, unlike normal object pooling which has JNDI service binding the pool itself, JDBC pooling will bind the DataSource instead And in this
implementation, dynamic proxy of physical connection is used to ensure that
all open statement will be closed when connection is returned. Multiple database
connection and object pools, their
factories and JMX are configured via the From a high level, usage of YAPoolMan involves the following: 1. Installing the YAPoolMan JAR into the appropriate CLASSPATH and verifying that all dependent JAR's (such as an XML parser and the required Java JAR's from Sun) are also available; 2. Configuring the 3. Accessing the pool in your code through one of the programmatic API views described above; 4. Runtime operation, including JMX-based administration and monitoring of pool metrics For web applications, you can either put the jar into common library, which will ensure that only one instance of YAPoolMan will started; you it can be put into each web applicationæ¯ lib directory, i.e. WEB-INF/lib directory. This way, each web context can have their own YAPoolMan instance and configuration file. |
|
||
|
||||
|
1.2 Object pooling and modern virtual machines It is important to note that general Java instance pooling in advanced virtual machines is typically unnecessary. Modern virtual machines contain low-level resource optimization that app-level pooling may circumvent and interfere with. However, Java types that make use of underlying system resources -- such as file descriptors, and socket connections -- should still be pooled. In these cases, it is not simply the Java instance creation process in question, it is a larger resource management issue that spans beyond merely the VM. Thus socket pooling, thread pooling, and connection pooling remain a necessity even in systems deployed on advanced modern VM's. |
|
||
|
||||
|
YAPoolMan contains the following high level features (see the poolman.xml resource for detailed info): · JDBC: JDBC Driver and DataSource is supported, and since dynamic proxy is used, changing of JDBC standard will not force YAPoolMan to change the code accordingly, which is true for original YAPoolMan implementation. Pools automatically attempt to bind their DataSources to JNDI. · Custom XML-based pool types: Pool any Class type, not just JDBC connections, using XML -- without writing a line of code. The config file is read from xml file into java objects using Jakarta Commons-Digester. · Seperation of Pool and Factory: Pool no longer creates objects, factory takes the responsibility. Factories are configured for each pool. · JMX: Administer live pools through a web browser, via the JMX Reference Implementation HTML agent, or be registered to any running JMX MBean Server. · Lazy Initialization: To better suit embeddability use cases, pools aren't created until they are first requested. This feature can be disabled programmatically. Not true when using JNDI to access the pool. · Multiple servers: Factory can create object among several server settings. For example, there is a database server having two connecting nodes in the cluster, you can have the factory creating connections connecting to either node. æ¥eight of the server can be used to balance the load. Servers can also be grouped into different priority, marked as busy standby or fail standby. · Multitude of configurable parameters: All pool parameters and definitions are exposed via standard XML. · Automatic resource collection: Pooled objects automatically return to their pools after a configurable user timeout value. · Emergency objects: Factories can temporarily be allowed to exceed their maximum limit under duress, and will automatically shrink back to their bounds as load decreases. ·
Aspect like proxy handler: proxy handler is set, dynamic proxy of the native object
will be used instead, the proxy handler can be used to change the behavior
before the proxy invocation, after the invocation and when exception occurs. ·
Native JNDI support: simplified JNDI implementation is used when no default
InitailContext available.
|
|
||
|
||||
|
YAPoolMan implements the JDBC
API as virtual driver and data source. It supports use of the Java Management
Extension (JMX) for service management, and ships with the JMX Reference
Implementation. It also makes use of Jakarta Commons-Digester to parse its
XML. |
|
||
|
||||
|
1.5 File and package structure The distribution contains the following directories: Directory: root level Directory: docs Directory: dist Directory: dist/samples Directory: dist/docs Directory: dist/docs/javadocs Directory: dist/lib Directory: lib Directory: src/java Directory: src/testsuite Directory: src/samples |
|
||
2.0 InstallationInstallation involves adding the appropriate JARs to the CLASSPATH, configuring poolman.xml, copying it to current working directory or adding the directory containing poolman.xml to the CLASSPATH, and testing the install. |
||||
|
2.1 STEP ONE: Add YAPoolMan JAR and your Database Driver to the CLASSPATH You have three options for installing the YAPoolMan JAR file and your database driver: (1) System-wide
option: Explicitly add the (2) VM-wide option: To automatically include the JAR whenever Java is
used, copy the (3) Application option: To include the JARs in a specific application, such as a web application, follow the packaging rules of the app. For instance, if you're using it in a web application, include the JARs in WEB-INF/lib (see the notes on Using YAPoolMan in web apps). |
|
||
|
||||
|
2.2 STEP TWO: Install third-party JAR files The following additional JAR's or valid subsititues for them must be available to your CLASSPATH according to one of the three options outlined abovein step one. All of these JAR's can be found in the "lib" directory of the distribution. ·
Jakarta
Commons-Logging: This is the
Apache/Jakarta logging library that provides common interface among Log4J, Logging
of JDK 1.4, or any other implementation. YAPoolMan makes use of it for all
logging tasks. Location: ·
Jakarta
Commons-Digester: This is the
Apache/Jakarta xml file digester library used to load xml configuration file.
Location: ·
Jakarta
Commons-Collections: This Apache/Jakarta enhanced Collection is picked up
for the implementation of BinaryHeap, a Priority Queue helps factory and pool
which object choose. Location: ·
Jakarta
Commons-BeanUtils: This
Apache/Jakarta util provides bean related functionality and is used by other
Jakarta Commons library. Location: · ·
JMX
Reference Implementation from SUN: Required only when JMX is enabled.
Location: ·
·
JUnit
Testing Framework: If you wish to
run the YAPoolMan test suite, you must have JUnit available. Location: |
|
||
|
||||
|
2.3 STEP THREE: Configure and install poolman.xml Configure: The "poolman.xml" file contains the XML-defined
details of the pools you wish to create. A template for this file is located
in the "lib" directory of the distribution: Install: Be sure that poolman.xml is put into current
working directory, or the directory containing it is in all relevant
CLASSPATH entries. For example, if you save your Web App Install: If you are embedding YAPoolMan within a web application, put poolman.xml in the WEB-INF/classes directory (see the notes for web app usage). |
|
||
|
||||
|
Once the appropriate
CLASSPATH updates have been made and the
For example, if you have
named a database "testdb" in your
If YAPoolMan has been configured correctly, results should appear for each of the sample methods. If not, the reported error should provide a hint about the problem. You can also reference web.xml in samples directory to see how to deploy poolman.xml in JSP/servlet engine. (see The YAPoolMan web application). |
|
||
|
||||
|
2.5 Upgrading from PoolMan 2.x release Modify poolman.xml file This file has been completely changed, you have to modify it manually. Please reference the document and sample xml file before you make the change. A DTD file is provided to assist if you have xml editors such as XMLSpy. Modify your code The SQLManager, SQLUtil
has been removed, any code using this class should be re-written or you can
provide your own SQLUtil implementation. The good news is that after setting up poolman.xml and put yapoolman.jar into class path, any code that uses previous versions of YAPoolMan should continue to function. Other means of accessing the DataSource, the Driver and the pool should continue to function even better than before.
|
|
||
3.0 Usage |
||||
|
3.1 JDBC: JNDI and DataSource usage The preferred method of
accessing JDBC Connections is through a DataSource object. DataSource usage
should replace the original Driver usage in all J2EE code. Standard Java
Naming and Directory Interface (JNDI) server practice is to bootstrap the
naming provider through a When a connection pool is created, that pool will attempt to bind itself to the naming provider. When a pool is stopped, it unbinds itself. The name under which the
pool is bound is specified in the Code Samples EXAMPLE 1: Below is a code snip illustrating client DataSource usage: Context ctx = new InitialContext(params); DataSource
ds = (DataSource) ctx.lookup("java:db/testdb"); Connection con = ds.getConnection(); // your code to make use of the connection here con.close();
|
|
||
|
||||
|
The original standard means of accessing JDBC connections is through the local DriverManager, which locates JDBC Drivers appropriate for a particular connection request. YAPoolMan does contain a virtual JDBC Driver that wraps underlying drivers, so it can be accessed in this way. Here is a relevant code
snip detailing this approach. It should be familiar, as it is simply an
example of YAPoolMan plugged into the standard pre-DataSource JDBC API. The
important element is the Driver name
("com.codestudio.sql.YAPoolMan") and the URL passed to the
DriverManager ("jdbc:poolman://" + database name as specified in
the
If a user forgets to
close a Connection, YAPoolMan will eventually take it back automatically if
it has been sent back for time longer than poolman.xml |
|
||
|
||||
|
3.3 Pooling non-JDBC objects: The Object Objects of any Java Class
type with a default no-args constructor may be pooled through the object
pool. These pools can be created and configured through Here is a usage example:
Again, generic pooled objects must have a default no-args constructor. |
|
||
|
||||
|
3.4 Implement your own PooledObject As 3.3 demonstrated, an object
pool can be used serve normal objects. However, since only the default
constructor can be used to instantiate the object, it is hardly useful to
handle complex objects requires various information to initiate, e.g. JDBC
connection. Thus, you should wrap the object interested in a PooledObject. JdbcConnectionWrapper is a good example to
demonstrate how to use PooledObject to deal with such kind of objects. First, you must decide
how many parameters it needs to initiate itself. As a JDBC connection, you
must define url, username and password. For a corba connection, you may need
iorFile and interfaceName. So you can define the factory setting in
poolman.xm file:
<factory> <objectType>java.lang.StringBuffer</objectType> <server> <name>server1</name> <param> <name>iorFile</name> <value>/corba/ior/server1.ior</value> </param> <param> <name>interfaceName</name> <value>my.package.IBusiness</value> </param> </server>
</factory> And then you can extend
BasePooledObject and implements the following method: ·
open(): to
open the connection using the serverInfo provided. serverInfo is an Hashtable
containing all name/value pairs defined in poolman.xml for that server. In
this corba case, they are iorFile, interfaceName and their values
/corba/ior/server1.ior, my.package.IBusiness respectively. ·
closeAllResources():
to close the physical connection. In this case, by calling _release() of
org.omg.CORBA.Object ·
clean(): to
clean all temporary information and get ready for the connection to serve
another user ·
validate(): to
check the status of the connection. In this case, you can call _non_existent() |
|
||
|
||||
|
3.5 Implement your own ProxyHandler Sometime you need more
control when your pooled object is used. For a JDBC connection implemented in
this project, tracking the opened statement is important. So whenever a public void beforeExecute(PooledObject pooledObject, Method method, Object[] args) throws ProxyHandlerException Called before
the invocation. If an |
|
|
|
|
3.8 Starting YAPoolMan as a server Typically, YAPoolMan does not create its pools and make them available to calling clients until it receives its first request. It is possible to avoid using this lazy initialization, however. To create the pools explicitly before a user request, essentially starting YAPoolMan's underlying embedded server as a first-class server instance, invoke the following line of code:
|
|
|
3.9 Other Poolable Connections In this package, there are some pre-created connections can be pooled in Object Pool. They are CICS, MQSeries, JMS and Corba. Refer the javadoc of package net.sf.yapoolman.util to get more information. |
|
4.0 Administration |
||
|
4.1 Enabling and Disabling JMX To enable JMX, set the |
|
|
||
|
The Java Management Extension (JMX) is a J2EE-optional package aimed at providing a standard management API for all manageable components. It uses the concept of MBeans, or managed beans, to define any manageable resource in a JavaBeans-like manner. In the simplest scenario, every JMX MBean provides get/set methods for exposed attributes. A layer removed from JMX, YAPoolMan makes use of a JavaBean metadata architecture; every pool is defined by a metadata object. It is this metadata object that JMX manages for YAPoolMan -- one MBean per YAPoolMan metadata object. Thus JMX doesn't directly administer pools, it administers the metadata for the pools. This allows other non-JMX management systems to be plugged into the YAPoolMan library. When YAPoolMan loads its
pools, it calls upon a bootstrap service to parse the Subsequent changes in any MBean attribute result in a change in the pool's metadata, and will take effect immediately. |
|
|
||
|
The JMX Reference
Implementation includes an HTML agent that can be used to administer MBeans. In
YAPoolMan, this agent is configured like the pools -- through Once YAPoolMan has loaded
its pools -- either after the first caller request or after invoking the
The agent will NOT be available until YAPoolMan has been started (you will receive a 404 error if it has not yet started). For more information on JMX and this HTML agent, please see Resources. Important Notes: 1. You should comment-out the HTML agent entries in 2. Note that changes made through the HTML agent will
not propogate to the |
|
5.0 Integration: Embeddable YAPoolManIn general, YAPoolMan is
automatically embeddable due to its lazy-initialization architecture. It will
be started in the same process as its first invoking caller. Assuming the
parent product includes the necessary YAPoolMan entries and dependencies in its
CLASSPATH settings (detailed in Installation), YAPoolMan
will be accessible as an embedded component regardless of which view --
DataSource, Driver, PoolManager, ObjectPool, JdbcPool -- is used. |
||
6.0 Resources
|
||
|
6.1 The poolman.xml file in detail See PoolManXML.html for detail. |
|
|
||
|
6.2 The YAPoolMan web application ·
The YAPoolMan web
application, packaged in the |
|
|
||
|
6.3 Recommended tutorials and relevant specifications
|
|
|