IBM WebSphere Application ServerTM
Release 8

Package com.ibm.ws.extensionhelper

This is the documentation for the for WebSphere Extension Helper.

See:
          Description

Package com.ibm.ws.extensionhelper 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);
}

Version:
1.1.0

IBM WebSphere Application ServerTM
Release 8