Package com.ibm.ws.extensionhelper
This is the documentation for the for WebSphere Extension Helper.
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:
- Ability to participate in Global/Local Transaction.
- Utility to handle various Databases in a consistent manner.
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
- 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.
- Allows retrieval of SQL strings with replacement text from a property file.
- Alows simplified database type detection
- 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); }