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 is used to invoke vendor specific non-JDBC methods on the underlying JDBC objects wrapped by WebSphere.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CALLABLE_STATEMENT Constant indicating a java.sql.CallableStatement parameter.
static int	CONNECTION Constant indicating a java.sql.Connection parameter.
static java.lang.String	CONSTRUCTOR Constant indicating the jdbcPass method is invoking a constructor.
static int	DATA_SOURCE Constant indicating a javax.sql.DataSource parameter.
static int	DATABASE_META_DATA Constant indicating a java.sql.DatabaseMetaData parameter.
static int	IGNORE Constant indicating the corresponding parameter should be ignored.
static int	PREPARED_STATEMENT Constant indicating a java.sql.PreparedStatement parameter.
static int	RESULT_SET Constant indicating a java.sql.ResultSet parameter.
static int	STATEMENT Constant indicating a java.sql.Statement parameter.

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.Object	call(java.lang.Object target, java.lang.String methName, java.lang.Object[] params, java.lang.Class[] types) Deprecated. Please use standard Java reflection APIs instead.
static void	clearStatementCache(java.lang.Object conn) Signals WebSphere to clear the prepared statement cache for the specified connection.
static DataStoreHelper	getDataStoreHelper(javax.sql.DataSource ds) Retrieves the DataStoreHelper associated with the specified WebSphere DataSource.
static java.sql.Connection	getNativeConnection(java.lang.Object connection) PK58756 This method returns the underlying physical JDBC connection to the caller.
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 java.lang.Object	jdbcCall(java.lang.Class underlyingObjectType, java.lang.Object caller, java.lang.String methName, java.lang.Object[] args, java.lang.Class[] argTypes, java.lang.String vendorClassName) 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 java.lang.Object	jdbcPass(java.lang.Class targetClass, java.lang.String methodName, java.lang.Object[] args, java.lang.Class[] types, int[] unwrap) Invokes a static method for which one or more of the method parameters must be a native JDBC object.
static java.lang.Object	jdbcPass(java.lang.Object targetObject, java.lang.String methodName, java.lang.Object[] args, java.lang.Class[] types, int[] unwrap) Invokes a method for which one or more of the method parameters must be a native JDBC object.
static void	setConnectionError(java.lang.Object conn) Deprecated. Replaced by setConnectionError(Object,boolean)
static void	setConnectionError(java.lang.Object conn, boolean logEvent) Signals WebSphere that an application-detected fatal error has occured on the specified connection so that WebSphere can 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

Field Detail

CONSTRUCTOR

public static final java.lang.String CONSTRUCTOR

Constant indicating the jdbcPass method is invoking a constructor.

See Also:

Constant Field Values

IGNORE

public static final int IGNORE

Constant indicating the corresponding parameter should be ignored.

Since:

WAS 5.1

See Also:

Constant Field Values

DATA_SOURCE

public static final int DATA_SOURCE

Constant indicating a javax.sql.DataSource parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

CONNECTION

public static final int CONNECTION

Constant indicating a java.sql.Connection parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

STATEMENT

public static final int STATEMENT

Constant indicating a java.sql.Statement parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

PREPARED_STATEMENT

public static final int PREPARED_STATEMENT

Constant indicating a java.sql.PreparedStatement parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

CALLABLE_STATEMENT

public static final int CALLABLE_STATEMENT

Constant indicating a java.sql.CallableStatement parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

RESULT_SET

public static final int RESULT_SET

Constant indicating a java.sql.ResultSet parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

DATABASE_META_DATA

public static final int DATABASE_META_DATA

Constant indicating a java.sql.DatabaseMetaData parameter.

Since:

WAS 5.1

See Also:

Constant Field Values

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

Deprecated. Please use standard Java reflection APIs instead.

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.

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

java.lang.ExceptionInInitializerError - if the initialization provoked by this method fails.

See Also:

Class, Method

getDataStoreHelper

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

Retrieves the DataStoreHelper associated with the specified WebSphere DataSource.
Note: This method can not be called directly by user applications.

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:

java.sql.SQLException - if the Connection is closed.

java.lang.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. Use this method only to invoke non-JDBC methods.

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

Object result = WSCallHelper.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();

Dynamically Reconfiguring a DataSource with the jdbcCall Method

WebSphere supports dynamic DataSource configuration with single-parameter setter methods invoked via the WSCallHelper.jdbcCall interface. All other methods which alter the properties or state of the DataSource are not supported.

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 required only 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 can be used, as in the above example. A second example follows, where the underlyingObjectType parameter is required.

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. In this case, use the following to call the method and read the value returned:

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

Parameters:

underlyingObjectType - The interface class of the underlying JDBC object to use. This value can 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:

java.sql.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.

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,
                        java.lang.String vendorClassName)
                                       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. Use this method only to invoke non-JDBC methods.

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

Object result = WSCallHelper.jdbcCall( null, conn, "countOpenStatements", new Object[] { new Integer(ResultSet.TYPE_FORWARD_ONLY), new Integer(ResultSet.CONCUR_READ_ONLY) }, new Class[] { int.class, int.class }, null); 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 required only 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 can be used, as in the above example. A second example follows, where the underlyingObjectType parameter is required.

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. In this case, use the following to call the method and read the value returned:

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

Determining what Properties are Settable on a DataSource

As a general rule, properties that are settable on the GUI during DataSource creation are not settable through the WSCallHelper. The WSCallHelper support is intended to provide the ability to set additional properties that cannot be represented on the GUI configuration.

WebSphere allows 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 are available through the WSCallHelper.

Parameters:

underlyingObjectType - The interface class of the underlying JDBC object to use. This value can 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.

vendorClassName - The name of the vendor-specific interface class on which methName is defined. This value can be used in cases where the implementation class of the vendor's JDBC object is a protected class, i.e. calling methName on the underlying JDBC object produces an IllegalAccessException. This value should specify the name of the vendor's recommended Class/Interface which is extended/implemented by the underlying JDBC object. For example "oracle.jdbc.driver.OracleResultSet" may need to be specified when the underlying object is an OracleResultSetImpl object. If not needed, this value may be null.

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.sql.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.

jdbcPass

public static java.lang.Object jdbcPass(java.lang.Class targetClass,
                        java.lang.String methodName,
                        java.lang.Object[] args,
                        java.lang.Class[] types,
                        int[] unwrap)
                                 throws java.sql.SQLException

Invokes a static method for which one or more of the method parameters must be a native JDBC object. This method substitutes any WebSphere JDBC wrappers with the corresponding native JDBC object and invokes the static method. The jdbcPass method should be used only when native JDBC objects are required.

For example, assume JDBC provider XYZ provides a class, ResultSetFormatter, which contains a static method, format, taking two parameters of types com.xyz.jdbc.XYZResultSet and int. Also, assume the internal implementation of the format method requires access to special proprietary methods or fields defined on the com.xyz.jdbc.XYZResultSet class. If WebSphere is configured to use JDBC provider XYZ and a ResultSet object, rset, is obtained, you can use the following code to invoke the ResultSetFormatter.format method:

Object result = WSCallHelper.jdbcPass( ResultSetFormatter.class, "format", new Object[] { rset, new Integer(2) }, new Class[] { com.xyz.jdbc.XYZResultSet.class, int.class } new int[] { WSCallHelper.RESULT_SET, WSCallHelper.IGNORE });

WARNING:

Usage of jdbcPass bypasses the WebSphere application server's JDBC wrappers and might result in unpredictable, unstable behavior. The functions called by the jdbcPass method are not part of the WebSphere application server software; they are provided by database vendors whose responsibility it is to support them. Because jdbcPass is used to invoke database functions that are proprietary to other software vendors, if you choose to use the jdbcPass methods, you do so at your own risk.

Restrictions:

Permitted Methods. Due to the high degree of unpredictability and instability that are possible as side effects of using jdbcPass, WebSphere permits the invocation of only a select list of methods through the jdbcPass interface. These methods guarantee not to alter the state of native JDBC objects in any way that might adversely affect the behavior of the WebSphere JDBC wrappers. If you require access to additional methods through jdbcPass, contact WebSphere support.

Exception Mapping. Because multiple native JDBC objects, possibly all from different DataSources, might be involved in a single jdbcPass invocation, it is not possible for WebSphere to handle connection error detection, stale statement detection, or any other type of exception mapping. It is left to the application to implement any exception mapping and handling that might be necessary. Applications can use the setConnectionError method to notify WebSphere of any such connection error situations detected by the application.

Parameters:

targetClass - the class on which to invoke the static method.

methodName - the name of the method to invoke. The WSCallHelper.CONSTRUCTOR constant may be used to signal the method is a constructor.

args - list of method parameters, of which at least one is a WebSphere JDBC wrapper.

types - list of method parameter types.

unwrap - list of constants specifying which method parameters are WebSphere JDBC wrappers needing to be unwrapped and replaced with the corresponding native JDBC objects.

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.sql.SQLException - if the method call is invalid or throws a SQLException itself during execution. SQLException may also be thrown if the method requested is not permitted by WebSphere.

Since:

WAS 5.1

jdbcPass

public static java.lang.Object jdbcPass(java.lang.Object targetObject,
                        java.lang.String methodName,
                        java.lang.Object[] args,
                        java.lang.Class[] types,
                        int[] unwrap)
                                 throws java.sql.SQLException

Invokes a method for which one or more of the method parameters must be a native JDBC object. The jdbcPass method should be used only when native JDBC objects are required.

For example, assume JDBC provider XYZ provides a class, com.x.jdbc.CustomTable, which contains a proprietary method, populate, taking two parameters of types com.xyz.jdbc.XYZConnection and String. Also, assume the internal implementation of the populate method requires access to special proprietary methods or fields defined on the com.xyz.jdbc.XYZConnection class. If WebSphere is configured to use JDBC provider XYZ and a java.sql.Connection object, conn, is obtained, the following code can be used to invoke the customTable.populate method:

Object result = WSCallHelper.jdbcPass( customTable "populate", new Object[] { conn, "select zebras, elephants, alligators, from zooStats" }, new Class[] { com.xyz.jdbc.XYZConnection.class, String.class } new int[] { WSCallHelper.CONNECTION, WSCallHelper.IGNORE });

WARNING:

Usage of jdbcPass bypasses the WebSphere application server's JDBC wrappers and might result in unpredictable, unstable behavior. The functions called by the jdbcPass method are not part of the WebSphere application server software; they are provided by database vendors whose responsibility it is to support them. Because jdbcPass is used to invoke database functions that are proprietary to other software vendors, if you choose to use the jdbcPass methods, you do so at your own risk.

Restrictions:

Permitted Methods. Due to the high degree of unpredictability and instability that are possible as side effects of using jdbcPass, WebSphere permits the invocation of only a select list of methods through the jdbcPass interface. These methods guarantee they will not alter the state of native JDBC objects in any way that might adversely effect the behavior of the WebSphere JDBC wrappers. If you require access to additional methods through jdbcPass, contact WebSphere support.

Exception Mapping. Because multiple native JDBC objects, possibly all from different DataSources, might be involved in a single jdbcPass invocation, it is not possible for WebSphere to handle connection error detection, stale statement detection, or any other type of exception mapping. It is left to the application to implement any exception mapping and handling that might be necessary. Applications can use the setConnectionError method to notify WebSphere of any such connection error situations detected by the application.

Parameters:

targetObject - the object on which to invoke the method.

methodName - the name of the method to invoke. The WSCallHelper.CONSTRUCTOR constant may be used to signal the method is a constructor.

args - list of method parameters, of which at least one is a WebSphere JDBC wrapper.

types - list of method parameter types.

unwrap - list of constants specifying which method parameters are WebSphere JDBC wrappers needing to be unwrapped and replaced with the corresponding native JDBC objects.

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.sql.SQLException - if the method call is invalid or throws a SQLException itself during execution. SQLException may also be thrown if the method requested is not permitted by WebSphere.

Since:

WAS 5.1

setConnectionError

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

Deprecated. Replaced by setConnectionError(Object,boolean)

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

Parameters:

conn - the connection on which the error occurred.

setConnectionError

public static final void setConnectionError(java.lang.Object conn,
                      boolean logEvent)

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

Parameters:

conn - the connection on which the error occurred.

logEvent - log the event to system out

clearStatementCache

public static final void clearStatementCache(java.lang.Object conn)
                                      throws java.sql.SQLException

Signals WebSphere to clear the prepared statement cache for the specified connection.

Parameters:

conn - the connection on which the error occurred.

Throws:

java.sql.SQLException

Since:

PK21673

getNativeConnection

public static final java.sql.Connection getNativeConnection(java.lang.Object connection)
                                                     throws java.sql.SQLException

PK58756 This method returns the underlying physical JDBC connection to the caller. Take caution when you use the underlying physical connections directly, because some important functions of the application server will be lost, such as the following:

Tracing Deferred enlistment Transaction management Exception mapping Connection pooling Do not actually close the underlying physical connection; instead, close the connection handle from the application server. If you close the native connection handle, there will be failures the next time the application server uses the connection handle. ????

Returns:

a java.sql.Connection

Throws:

java.sql.SQLException