com.ibm.websphere.rsadapter
Class WSCallHelper
- java.lang.Object
com.ibm.websphere.rsadapter.WSCallHelper
- public class WSCallHelper
- extends java.lang.Object
jdbcCall
method is used to invoke vendor specific non-JDBC methods on
the underlying JDBC objects wrapped by WebSphere.
Field Summary
Modifier and Type | Field and Description |
---|---|
|
CALLABLE_STATEMENT
Constant indicating a java.sql.CallableStatement parameter.
|
|
CONNECTION
Constant indicating a java.sql.Connection parameter.
|
|
CONSTRUCTOR
Constant indicating the jdbcPass method is invoking a constructor.
|
|
DATA_SOURCE
Constant indicating a javax.sql.DataSource parameter.
|
|
DATABASE_META_DATA
Constant indicating a java.sql.DatabaseMetaData parameter.
|
|
IGNORE
Constant indicating the corresponding parameter should be ignored.
|
|
PREPARED_STATEMENT
Constant indicating a java.sql.PreparedStatement parameter.
|
|
RESULT_SET
Constant indicating a java.sql.ResultSet parameter.
|
|
STATEMENT
Constant indicating a java.sql.Statement parameter.
|
Method Summary
Modifier and Type | Method and Description |
---|---|
|
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.
|
|
clearStatementCache(java.lang.Object conn)
Signals WebSphere to clear the prepared statement cache for the specified
connection.
|
|
getDataStoreHelper(javax.sql.DataSource ds)
Retrieves the DataStoreHelper associated with the specified WebSphere DataSource.
|
|
getNativeConnection(java.lang.Object connection)
PK58756
This method returns the underlying physical JDBC connection to the caller.
|
|
isShareable(java.sql.Connection conn)
Determines whether a WebSphere Connection is shareable or not.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
setConnectionError(java.lang.Object conn)
Deprecated. Replaced by
setConnectionError(Object,boolean)
|
|
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
IGNORE
- public static final int IGNORE
DATA_SOURCE
- public static final int DATA_SOURCE
CONNECTION
- public static final int CONNECTION
STATEMENT
- public static final int STATEMENT
PREPARED_STATEMENT
- public static final int PREPARED_STATEMENT
CALLABLE_STATEMENT
- public static final int CALLABLE_STATEMENT
RESULT_SET
- public static final int RESULT_SET
DATABASE_META_DATA
- public static final int DATABASE_META_DATA
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
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. java.lang.NoSuchMethodException
- if a matching method is not found or if the name is
"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. Class
,
Method
getDataStoreHelper
- public static final DataStoreHelper getDataStoreHelper( javax.sql.DataSource ds)
Note: This method can not be called directly by user applications.
ds
- a WebSphere DataSource. isShareable
- public static final boolean isShareable( java.sql.Connection conn)
- throws java.sql.SQLException
conn
- the Connection. 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:
|
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:
|
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. 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:
|
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:
|
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.
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. 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:
|
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.
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. 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. 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:
|
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.
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. 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. setConnectionError
- public static final void setConnectionError( java.lang.Object conn)
setConnectionError(Object,boolean)
conn
- the connection on which the error occurred. setConnectionError
- public static final void setConnectionError( java.lang.Object conn,
- boolean logEvent)
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
conn
- the connection on which the error occurred. java.sql.SQLException
getNativeConnection
- public static final java.sql.Connection getNativeConnection( java.lang.Object connection)
- throws java.sql.SQLException
java.sql.SQLException