Dynamo uses resource pools to minimize the need to create expensive resources. (See the Core Dynamo Services chapter of the ATG Programming Guide for details.) The most commonly used resource pool in most ATG applications is a pool of JDBC database connections. This resource pool, /atg/dynamo/service/jdbc/JTDataSource, is a Nucleus service that creates new connections to a particular database. This component is of class atg.service.jdbc.MonitoredDataSource and subclasses atg.service.resourcepool.ResourcePool. The JTDataSource service is configured with the name of the driver, the name of the database, the user name, password, and so on. It keeps connections around after creating them, so that subsequent requests can reuse existing connections. Because connection objects are expensive to create but cheap to reuse, it makes sense to create a “pool” that can be reused as needed.
For a component to obtain a connection, it must first have a pointer to the connection pool. This pointer is usually assigned in a properties file. From the connection pool, the component checks out a connection. The connection pool responds by returning a free connection, or by creating a new connection if there are no free connection objects available. The component then uses the connection to do whatever operations it requires. When it is done, the component checks in the connection to the connection pool, which then makes the connection available to other objects.
Dynamo implements connection pooling via the DataSource API in Sun’s JDBC 2.0 Optional Package. Connections are obtained and returned to the pool through two methods: the getConnection() method of javax.sql.DataSource and the close() method of java.sql.Connection. Connections are obtained from the DataSource interface. This interface is a connection factory, an object that creates Connections (java.sql.Connection objects). The Connection objects that DataSource returns are not the JDBC Connections returned from the underlying JDBC driver. Instead, they are connection wrappers that allow a connection to be returned to the pool from any place in the code by calling close(). In addition, the wrappers prevent further work from being done through a connection that has already been returned to the pool.
J2EE JDBC supports the Java Transaction API (JTA) via the javax.sql.XADataSource interface. JTA allows multiple resources from differing providers to participate in the same transaction. Using two-phase commits, data integrity across differing services is ensured. Dynamo supplies a DataSource that sits on top of an XADataSource and returns wrapped Connections that are registered appropriately with the associated Transaction Manager. Dynamo’s DataSource must get all its Connections from an XADataSource. Only a true XADataSource produces connections that behave properly in a two-phase commit controlled by JTA. XADataSources should be included in JDBC 2.0 drivers for the various database vendors.
An XADataSource is not yet available for some vendors’ databases. If an XADataSource is not available for the database that you are using, Dynamo provides a FakeXADataSource that fakes JTA into thinking its resources are JTA compliant, even though they are not. Though the FakeXADataSource allows an application to use a JDBC 1.0 driver or a regular DataSource from a JDBC 2.0 driver, it does not behave the same as an actual XADataSource would. Specifically, the connections produced by the FakeXADataSource do not really participate in two-phase commits. Instead, they commit on either the prepare or commit phase of the commit. You specify which phase to commit on through the commitOnPrepare property of the /atg/dynamo/service/jdbc/FakeXADataSource component. In addition, the FakeXADataSource must simulate global transactions across multiple calls to the getConnection() method of javax.sql.DataSource. To do this, the FakeXADataSource enforces the restriction that a thread/transaction can have only one connection out at a time. By enforcing this restriction, the FakeXADataSource can ensure that each call to getConnection() returns the same connection, so that all work may be done within the same database transaction. Once the transaction is committed or rolled back, the connection is cleaned up and returned to the pool for reuse.
The default DataSource connection pool, JTDataSource, uses the FakeXADataSource component, which is configured by default for the SOLID database. If you want to use a database other than SOLID, you must configure the desired connection pool properties.
The easiest way to create and configure connection pools is through the Configuration Manager in the ATG Dynamo Administration UI. See Configuring a Connection Pool through the Admin UI form more information. Alternatively, you can set up and configure a connection pool manually by creating properties files in your localconfig/atg/dynamo/service/jdbc/ directory. See Configuring a Connection Pool Manually for details.
