com.ibm.websphere.rsadapter
Class WSCallHelper

java.lang.Object
  |
  +--com.ibm.websphere.rsadapter.WSCallHelper

public class WSCallHelper

extends java.lang.Object

Provides static methods for invoking non-standard methods on objects wrapped by WebSphere. For example, the jdbcCall method can be used to invoke vendor specific non-JDBC methods on the underlying JDBC objects wrapped by WebSphere.

Method Summary

static java.lang.Object	call(java.lang.Object target, java.lang.String methName, java.lang.Object[] params, java.lang.Class[] types) A shortcut method for reflection.
static DataStoreHelper	createDataStoreHelper(java.lang.String dsClassName) Create a new instance of the DataStoreHelper for the specified DataSource class.
static DataStoreHelper	getDataStoreHelper(javax.sql.DataSource ds) Retrieves the DataStoreHelper associated with the specified WebSphere DataSource.
static boolean	isShareable(java.sql.Connection conn) Determines whether a WebSphere Connection is shareable or not.
static java.lang.Object	jdbcCall(java.lang.Class underlyingObjectType, java.lang.Object caller, java.lang.String methName, java.lang.Object[] args, java.lang.Class[] argTypes) Calls a non-standard-JDBC method, specific to the JDBC provider implementation class, on the underlying JDBC object corresponding to a WebSphere JDBC wrapper.
static void	setConnectionError(java.lang.Object connHandle) Signals WebSphere that an application-detected fatal error has occured on the specified Connection handle so that WebSphere may remove it from the pool, or purge the entire pool, as determined by the purge policy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

call

public static java.lang.Object call(java.lang.Object target,
                                    java.lang.String methName,
                                    java.lang.Object[] params,
                                    java.lang.Class[] types)
                             throws java.lang.NoSuchMethodException,
                                    java.lang.SecurityException,
                                    java.lang.IllegalAccessException,
                                    java.lang.IllegalArgumentException,
                                    java.lang.reflect.InvocationTargetException

A shortcut method for reflection.

Parameters:

target - the object to invoke a method on.

methName - the name of the method.

params - an ordered list of the parameters passed to the method.

types - an ordered list of the parameter types on the method signature.

Returns:

The Object returned by the specified method, or null if it returns nothing. In the case where the value normally returned is a primitive, it is returned in its corresponding wrapper class.

Throws:

java.lang.NoSuchMethodException - if a matching method is not found or if the name is ""or "".

java.lang.SecurityException - if access to the information is denied.

java.lang.IllegalAccessException - if the underlying method is inaccessible.

java.lang.IllegalArgumentException - if the number of actual and formal parameters differ, or if an unwrapping conversion fails.

java.lang.reflect.InvocationTargetException - if the underlying method throws an exception.

NullPointerException - if the specified object is null and the method is an instance method.

ExceptionInInitializerError - if the initialization provoked by this method fails.

See Also:

java.lang.Class.getMethod, java.lang.reflect.Method.invoke

createDataStoreHelper

public static DataStoreHelper createDataStoreHelper(java.lang.String dsClassName)
                                             throws javax.resource.ResourceException

Create a new instance of the DataStoreHelper for the specified DataSource class.

Parameters:

dsClassName - the name of the DataSource class.

Returns:

the DataStoreStoreHelper or null if none is found.

Throws:

ResourceException - if an error occurs creating the DataStoreHelper.

getDataStoreHelper

public static final DataStoreHelper getDataStoreHelper(javax.sql.DataSource ds)

Retrieves the DataStoreHelper associated with the specified WebSphere DataSource.

Parameters:

ds - a WebSphere DataSource.

Returns:

the DataStoreHelper

isShareable

public static final boolean isShareable(java.sql.Connection conn)
                                 throws java.sql.SQLException

Determines whether a WebSphere Connection is shareable or not.

Parameters:

conn - the Connection.

Returns:

true if this Connection is shareable; false if it is non-shareable.

Throws:

SQLException - if the Connection is closed.

ClassCastException - if the Connection is not a WebSphere Connection wrapper.

jdbcCall

public static final java.lang.Object jdbcCall(java.lang.Class underlyingObjectType,
                                              java.lang.Object caller,
                                              java.lang.String methName,
                                              java.lang.Object[] args,
                                              java.lang.Class[] argTypes)
                                       throws java.sql.SQLException

Calls a non-standard-JDBC method, specific to the JDBC provider implementation class, on the underlying JDBC object corresponding to a WebSphere JDBC wrapper. This method should be used for non-JDBC methods only.

For example, if JDBC provider X provided a non-standard method on its implementation of java.sql.Connection called countOpenStatements() taking two int parameters, and if a WebSphere DataSource was configured for JDBC provider X and used to get a Connection, conn, the following could be used to call the method and read the value returned,

 Object result = WSCallerHelper.jdbcCall(
     null,
     conn,
     "countOpenStatements",
     new Object[] { new Integer(ResultSet.TYPE_FORWARD_ONLY),
                    new Integer(ResultSet.CONCUR_READ_ONLY) },
     new Class[] { int.class, int.class });

 int numOpenStatements = ((Integer) result).intValue();

When to use the 'underlyingObjectType' Parameter

Some WebSphere JDBC wrappers wrap multiple JDBC classes. For example, the WebSphere Connection wrapper contains a java.sql.Connection and either a javax.sql.PooledConnection or a javax.sql.XAConnection. The underlyingObjectType parameter allows for distinguishing between the multiple wrapped objects according to their interface class.

This parameter is only required when invoking a method on WebSphere wrappers containing multiple JDBC objects and requesting to invoke a method on a JDBC interface other than that of the wrapper class. In all other cases a value of null may be used, as in the above example. A second example, where the underlyingObjectType parameter is required follows,

Assume JDBC provider X provides a non-standard method on its implementation of javax.sql.XAConnection called getTransactionStatus(), and a WebSphere DataSource was configured for JDBC provider X and used to get a Connection, conn. Then the following can be used to call the method and read the value returned,

 String status = (String) WSCallerHelper.jdbcCall(
     javax.sql.XAConnection.class,
     conn,
     "getTransactionStatus",
     new Object[] {},
     new Class[] {});

Determining what Properties are Settable on a DataSource

As a general rule, properties which are settable on the GUI during DataSource creation are not settable through the WSCallHelper. The WSCallHelper support is intended for providing the ability to set additional properties, which are not representable on the GUI configuration.

WebSphere will allow you to set, through the GUI, any property type meeting the following criteria,

• is a primitive type or is a wrapper for a primitive type (int, long, char, Integer)
• has a single-parameter String constructor (java.math.BigInteger, java.math.BigDecimal)
• is java.util.Properties

All remaining setters should be available through the WSCallHelper.

Parameters:

underlyingObjectType - The interface class of the underlying JDBC object to use. This value may be null if WebSphere wrapper wraps only one type of JDBC object or the JDBC interface is the same as that of the WebSphere wrapper class.

caller - The WebSphere JDBC wrapper on which to call the method.

methName - name of the method to call.

args - list of method parameters.

argTypes - list of method parameter types.

Returns:

The Object returned by the specified method, or null if it returns nothing. In the case where the value normally returned is a primitive, it is returned in its corresponding wrapper class.

Throws:

SQLException - if the method call is invalid or throws a SQLException itself during execution. SQLException may also be thrown when the method name supplied is a standard JDBC method.

setConnectionError

public static final void setConnectionError(java.lang.Object connHandle)

Signals WebSphere that an application-detected fatal error has occured on the specified Connection handle so that WebSphere may remove it from the pool, or purge the entire pool, as determined by the purge policy.

Parameters:

connHandle - the Connection handle on which the error occurred.