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.