IBM WebSphere Application ServerTM
Release 6

Package  com.ibm.ws.extensionhelper

Interface Summary
ExtensionHelperInterface to provide some commonly used patterns for WebSphere developers in a server environment.
TransactionControlHelper service provides functionality for different aspect of WebSphere Transactions.
TxHandleA TransactionControl handle.
DatabaseHelperThe DatabaseHelper is a simple utility interface for looking-up a datasource, retrieving a connection and performing SQL statement retrieval based on key replacements.



Package Description

This is the documentation for the for WebSphere Extension Helper. This API set exposes two commonly used components to a WebSphere server developer:

The service is accessible in JNDI using the ExtensionHelper.JNDI_NAME constant value. Once the service is retrieved, the factory methods can be used to retrieve a TransactionControl or DatabaseHelper instance.

Example:

InitialContext ctx = new InitialContext();
ExtensionHelper eh = (ExtensionHelper) ctx.lookcup(ExtensionHelper.JNDI_NAME);

DatabaseHelper

The DatabaseHelper utility provides the following functions

  1. Allows retrieving connections from a datasource with a global JNDI name using specified resource reference attributes that are normally defined in at the application level.
  2. Allows retrieval of SQL strings with replacement text from a property file.
  3. Alows simplified database type detection
  4. Provides a method for detecting if tables exist.

Example for retrieving a DatabaseHelper instance from the ExtensionHelper:

// Retrieve the ExtensionHelper service
InitialContext ctx = new InitialContext();
ExtensionHelper eh = (ExtensionHelper)
ctx.lookup(ExtensionHelper.JNDI_NAME);
// Construct a replacement map for replacing keys in SQL strings
HashMap replacementMap = new HashMap();
replacementMap.put("<username>", "John");
replacementMap.put("<country>", "USA");
// Provide the DatabaseHelper map with all of the properties needed to create a DatabaseHelper.
HashMap map = new HashMap();
map.put(DatabaseHelper.KEY_DATASOURCE_JNDI_NAME, "jdbc/test");          // required
map.put(DatabaseHelper.KEY_DATASOURCE_USERNAME, "dbadmin");             // optional
map.put(DatabaseHelper.KEY_DATASOURCE_PASSWORD, "pwd");                 // optional
map.put(DatabaseHelper.KEY_STATEMENTS_FILE, "jdbc.statement.file");     // optional
map.put(DatabaseHelper.KEY_TABLE_PREFIX,"USA");                         // optional
map.put(DatabaseHelper.KEY_REPLACEMENT_MAP, replacementMap);            // optional
map.put(DatabaseHelper.RESREF_AUTH, DatabaseHelper.AUTH_APPLICATION);                   // optional
map.put(DatabaseHelper.RESREF_SHARING, DatabaseHelper.SHARING_SHAREABLE);               // optional
map.put(DatabaseHelper.RESREF_TRANSACTION, DatabaseHelper.TRANSACTION_READ_COMMITTED);  // optional
// Retrieve the DatabaseHelper 
DatabaseHelper dbHelper = eh.getDatabaseHelper(map);
// Retrieve a SQL connection
Connection con = dbHelper.getConnection();
// Get a named SQL statement for this database type.
String sql = dbHelper.getSQLStatement("FindAddressByTaxID", "USA");
PreparedStatement ps = con.prepareStatement(sql);
ps.setInt(1, 12345);
if(dbHelper.getDatabaseType().equals(DatabaseHelper.DBTYPE_DB2ZSERIES))
{
    ps.setInt(2, 4000);
}
// Execute the prepared statement...
// Use the connection and return it.
dbHelper.returnConnection(con);

Example KEY_STATEMENTS_FILE:

# SQL Statements are stored in standard Java properties files.
# The property KEY is the statement key and the property VALUE is the SQL statement.
# The statement key is in the format:
# <statementkey>   ::= <tablekey>_<dbtype>_<statementtype>
# <tablekey>       ::= <any valid java.util.Properties key>
# <dbtype>         ::= DEFAULT | <any DatabaseHelper.DBYTPE constant>
# <statementtype>  ::= <any valid java.util.Properties key>   
# The SQL statement can consist of any valid SQL statement as long as it is also
# a valid java.util.Properties value.  The <table_prefix> replacement string 
# is used to identify a set of tables at runtime and is specified on the 
# DatabaseHelper.getSQLStatement() method.  Additional replacement keys can
# be added to the SQL statement.  The replacement values are specified 
# using the DatabaseHelper.KEY_REPLACEMENT_MAP key when retrieving a 
# DatabaseHelper using the ExtensionHelper.getDatabaseHelper() method.
Customers_DEFAULT_FindAddressByTaxID=SELECT * FROM <table_prefix>CUST WHERE TAXID=?
Customers_DB2ZSERIES_FindAddressByTaxID=SELECT * FROM <table_prefix>CUST WHERE TAXID=? and PARTITION=?
Customers_DEFAULT_UpdateAddressByTaxID=UPDATE <table_prefix>CUST SET ADDRESS1=?, ADDRESS2=?, CITY=?, STATE=?, ZIP=? WHERE TAXID=?
Customers_DB2ZSERIES_UpdateAddressByTaxID=UPDATE <table_prefix>CUST SET ADDRESS1=?, ADDRESS2=?, CITY=?, STATE=?, ZIP=? WHERE TAXID=? and PARTITION=?

TransactionControl

The TransactionControl utility provides a way for interacting with the WebSphere transaction manager without using J2EE Transaction API's. It also give the ability to encompass a unit of work in either a global or local transaction and to allow nesting different units of work (suspending and resuming).

Example for retrieving and using a TransactionControl instance from the ExtensionHelper:

// Retrieve the ExtensionHelper service
InitialContext ctx = new InitialContext();
ExtensionHelper eh = (ExtensionHelper)
ctx.lookup(ExtensionHelper.JNDI_NAME);
// Retieve a TransactionControl instance
TransactionControl tc = eh.getTransactionControl();
// Guarantee that we have a global transaction, execute some work
// and commit or rollback the transaction.  If you want
// to force a new global transaction (suspend any existing tran)
// or force a new local transaction, then use the preinvoke(boolean,boolean) method.
TxHandle txh = tc.preinvoke();
try {
    // Do some work ... 
    
    // Commit the transaction
    tc.postinvoke(txh);
} catch (Throwable fatalException) {
    // Rollback the transaction
    tc.handleException(txh);
}

IBM WebSphere Application ServerTM
Release 6