Enterprise Information Portal APIs

Package com.ibm.gcs.db.util

Provides an API that uses JDBC to enable applications to access and process data in a data source at the transaction level.

See:
          Description

Class Summary
ConnectionManager The ConnectionManager serves 3 functions: Reads values from a database properties file specifying the database where the url tables are located.
PreparedTransaction A PreparedTransaction extends the functionality of a Transaction by providing support for java.sql.PreparedStatements.
SQLString This class converts Java-type strings to SQL-type strings by escaping special characters.
Transaction A Transaction represents a set of SQL statements to be executed as a unit.
 

Exception Summary
ImplementationException  
InitializationException  
TransactionException  
 

Package com.ibm.gcs.db.util Description

Provides an API that uses JDBC to enable applications to access and process data in a data source at the transaction level. The classes in this package use the JDBC API (java.sql) to enable single and multi-threaded applications to manage one or more shared connections with a datasource when executing sets of SQL statements in the context of atomic transactions.

What the com.ibm.gcs.db.util package contains

The com.ibm.gcs.db.util package provides APIs for the management of JDBC connections and transactions as follows:

Connection Management

The ConnectionManager class manages a common set of static connections to be used by all threads of an application. The main purpose of this class is to act as a monitor that allows multiple threads to share common connections. An application obtains a java.sql.Connection object from a ConnectionManager object when it needs to access the data source.  It returns the java.sql.Connection object to the ConnectionManger object after it completes its task  In this way, the ConnectionManager enables an application to keep one or more connections open. As a result, the application threads do not have to open new connections everytime they access the database.  In addition, the ConnectionManager may be used when an application must limit the number of connections it makes to the data source.  Finally, the ConnectionManager is the class that creates the actual connections.  Hence, it provides the API to specify how to make this connection.

Transaction Execution

The Transaction and PreparedTransaction classes are convenience classes that make it easier for applications to execute sequences of SQL statements in single transaction units. The APIs hide the intricacies of JDBC from the application.  Hence, rather than using the java.sql.* API (which requires the appliction to deal with creating statements, closing statements, processing result sets with cursors, making connections, etc.), an application uses a Transaction object to execute a SQL statement in a few simple statements (as follows):

	Transaction t = new Transaction();
	t.executeUpdate( "UPDATE table SET a='b'" );
	t.commit();

The transaction classes use the ConnectionManager to get the DB connection and sends the SQL UPDATE, INSERT, or SELECT statement using the java.sql.* API.  In addition, they map the result sets returned by the DB to Java core objects and handle all the JDBC processing and cleanup. 

In addition, the Transaction objects provides applications with the mechanism to execute a sequence of SQL statements as a single transaciton unit.  The application may pass around a Transaction object as a parameter, enabling invoked methods to add SQL statements to the Transaction.  The entire set of SQL statements added to the object may be committed or aborted at any point in this process.

The SQLString class prepares a Java String to be sent to the DB by escaping necessary characters.  It also provides commonly used SQL strings (such as SELECT, INSERT, etc.) as constants so that applications may avoid expensive string construction operations.  [This class is specific to DB2 SQL syntax.  Should figure out how to make it application independent.] 

Throwing Exceptions

The TransactionException class is used by the Transaction objects to throw exceptions when SQL exceptions occur. 

Related Documentation

Package java.sql

 


EIP Web Crawler APIs

(c) Copyright International Business Machines Corporation 1996, 2002. IBM Corp. All rights reserved.