Class WSCallHelper
- java.lang.Object
-
- com.ibm.websphere.rsadapter.WSCallHelper
-
public class WSCallHelper extends java.lang.Object
This interface is provided for compatibility purposes only. Please use the standard JDBC wrapper pattern instead:Connection con = dataSource.getConnection(); con.unwrap(VendorInterface.class).doSomething(...);
-
-
Field Summary
Fields Modifier and Type Field 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
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 the connection manager to clear the prepared statement cache for the specified connection.static DataStoreHelper
getDataStoreHelper(javax.sql.DataSource ds)
Retrieves the DataStoreHelper associated with the specified Liberty DataSource.static java.sql.Connection
getNativeConnection(java.lang.Object connection)
Deprecated.Use the standard JDBC Connection.unwrap(VendorInterface.class) operation, or other methods provided on WSCallHelper, such as jdbcCall, instead.static boolean
isShareable(java.sql.Connection conn)
Determines whether a connection obtained from a Liberty DataSource is sharable 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 Liberty 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 Liberty 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 bysetConnectionError(Object,boolean)
static void
setConnectionError(java.lang.Object conn, boolean logEvent)
Signals the connection manager that an application-detected fatal error has occurred on the specified connection so that the connection manager can remove it from the pool, or purge the entire pool, as determined by the purge policy.
-
-
-
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.- See Also:
- Constant Field Values
-
DATA_SOURCE
public static final int DATA_SOURCE
Constant indicating a javax.sql.DataSource parameter.- See Also:
- Constant Field Values
-
CONNECTION
public static final int CONNECTION
Constant indicating a java.sql.Connection parameter.- See Also:
- Constant Field Values
-
STATEMENT
public static final int STATEMENT
Constant indicating a java.sql.Statement parameter.- See Also:
- Constant Field Values
-
PREPARED_STATEMENT
public static final int PREPARED_STATEMENT
Constant indicating a java.sql.PreparedStatement parameter.- See Also:
- Constant Field Values
-
CALLABLE_STATEMENT
public static final int CALLABLE_STATEMENT
Constant indicating a java.sql.CallableStatement parameter.- See Also:
- Constant Field Values
-
RESULT_SET
public static final int RESULT_SET
Constant indicating a java.sql.ResultSet parameter.- See Also:
- Constant Field Values
-
DATABASE_META_DATA
public static final int DATABASE_META_DATA
Constant indicating a java.sql.DatabaseMetaData parameter.- See Also:
- Constant Field Values
-
-
Method Detail
-
call
@Deprecated 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 Liberty DataSource.
Note: Never invoke this from applications.- Parameters:
ds
- a Liberty DataSource.- Returns:
- the DataStoreHelper
-
isShareable
public static final boolean isShareable(java.sql.Connection conn) throws java.sql.SQLException
Determines whether a connection obtained from a Liberty DataSource is sharable or not.- Parameters:
conn
- the Connection.- Returns:
- true if this Connection is sharable; false if it is non-sharable.
- Throws:
java.sql.SQLException
- if the Connection is closed.java.lang.ClassCastException
- if the connection was not obtained from a Liberty DataSource.
-
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 Liberty 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
calledcountOpenStatements()
taking twoint
parameters, and if a Liberty 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[] { ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY }, new Class[] { int.class, int.class }); int numOpenStatements = ((Integer) result).intValue();
All methods which alter the properties or state of a DataSource are not supported.
When to use the 'underlyingObjectType' Parameter
Some Liberty JDBC wrappers wrap multiple JDBC classes. For example, the 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 Liberty 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
calledgetTransactionStatus()
, and a Liberty 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 the wrapper wraps only one type of JDBC object or the JDBC interface is the same as that of the wrapper class.caller
- The Liberty 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 Liberty 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
calledcountOpenStatements()
taking twoint
parameters, and if a Liberty 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[] { ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY }, new Class[] { int.class, int.class }, null); int numOpenStatements = ((Integer) result).intValue();
All methods which alter the properties or state of a DataSource are not supported.
When to use the 'underlyingObjectType' Parameter
Some Liberty JDBC wrappers wrap multiple JDBC classes. For example, the 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 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
calledgetTransactionStatus()
, and a Liberty 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);
- Parameters:
underlyingObjectType
- The interface class of the underlying JDBC object to use. This value can be null if the wrapper wraps only one type of JDBC object or the JDBC interface is the same as that of the wrapper class.caller
- The Liberty 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 Liberty JDBC wrappers in the method parameters 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 typescom.xyz.jdbc.XYZResultSet
andint
. Also, assume the internal implementation of theformat
method requires access to special proprietary methods or fields defined on thecom.xyz.jdbc.XYZResultSet
class. If Liberty is configured to use JDBC provider XYZ and a ResultSet object,rset
, is obtained, you can use the following code to invoke theResultSetFormatter.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 application server's JDBC wrappers and might result in unpredictable, unstable behavior. The functions called by thejdbcPass
method are not part of the application server software; they are provided by database vendors whose responsibility it is to support them. BecausejdbcPass
is used to invoke database functions that are proprietary to other software vendors, if you choose to use thejdbcPass
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
, Liberty permits the invocation of only a select list of methods through thejdbcPass
interface. These methods guarantee not to alter the state of native JDBC objects in any way that might adversely affect the behavior of the Liberty JDBC wrappers. If you require access to additional methods throughjdbcPass
, submit a request for enhancement.Exception Mapping. Because multiple native JDBC objects, possibly all from different data sources, might be involved in a single
jdbcPass
invocation, it is not possible for Liberty 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 thesetConnectionError
method to notify Liberty 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 Liberty JDBC wrapper.types
- list of method parameter types.unwrap
- list of constants specifying which method parameters are Liberty JDBC wrappers needing to be unwrapped and replaced with the corresponding vendor 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 Liberty.
-
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 typescom.xyz.jdbc.XYZConnection
andString
. Also, assume the internal implementation of thepopulate
method requires access to special proprietary methods or fields defined on thecom.xyz.jdbc.XYZConnection
class. If Liberty is configured to use JDBC provider XYZ and a java.sql.Connection object,conn
, is obtained, the following code can be used to invoke thecustomTable.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 application server's JDBC wrappers and might result in unpredictable, unstable behavior. The functions called by thejdbcPass
method are not part of the application server software; they are provided by database vendors whose responsibility it is to support them. BecausejdbcPass
is used to invoke database functions that are proprietary to other software vendors, if you choose to use thejdbcPass
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
, Liberty permits the invocation of only a select list of methods through thejdbcPass
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 Liberty JDBC wrappers. If you require access to additional methods throughjdbcPass
, submit a request for enhancement.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 Liberty 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 thesetConnectionError
method to notify Liberty 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 Liberty JDBC wrapper.types
- list of method parameter types.unwrap
- list of constants specifying which method parameters are Liberty JDBC wrappers needing to be unwrapped and replaced with the corresponding vendor 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 Liberty.
-
setConnectionError
@Deprecated public static final void setConnectionError(java.lang.Object conn)
Deprecated.Replaced bysetConnectionError(Object,boolean)
Signals the connection manager that an application-detected fatal error has occurred on the specified connection so that the connection manager 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 the connection manager that an application-detected fatal error has occurred on the specified connection so that the connection manager 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 the connection manager to clear the prepared statement cache for the specified connection.- Parameters:
conn
- the connection for which the prepared statement cache is to be cleared.- Throws:
java.sql.SQLException
-
getNativeConnection
@Deprecated public static final java.sql.Connection getNativeConnection(java.lang.Object connection) throws java.sql.SQLException
Deprecated.Use the standard JDBC Connection.unwrap(VendorInterface.class) operation, or other methods provided on WSCallHelper, such as jdbcCall, instead.Do not use this method. It returns the underlying connection from the JDBC driver without the Liberty wrapper in place to manage transaction enlistment and coordination, connection pooling and sharing, statement caching, and other essential services provided by Liberty. Usage of the unwrapped connection that is returned by this method can lead data corruption and inconsistency as well as other erroneous behavior, not only for the returned connection itself, but also for any number of other connection requests which have no awareness at all of this method being used and just happen to obtain the now possibly corrupted connection from the pool.
There are safer alternatives that should be used instead of this method.
- The JDBC specification standard wrapper pattern should always be used
where possible:
Connection con = ds.getConnection(); MyVendorConnection vcon = con.unwrap(MyVendorConnection.class); result = vcon.doSomething(param1, param2);
- The
jdbcCall
methods onWSCallHelper
allow for invocation of vendor methods that do not have an interface:Connection con = ds.getConnection(); result = WSCallHelper.jdbcCall(Connection.class, con, "doSomethingElse", new Object[] { param1, param2 }); new Class[] { int.class, String.class });
- The
jdbcPass
method onWSCallHelper
allows for invoking a limited set of vendor method that require a native vendor object to be supplied as a parameter. It suffers from the same vulnerabilities asgetNativeConnection
but limits the exposure of the native object to the vendor method.
- Parameters:
connection
- Liberty connection wrapper.- Returns:
- the underlying connection object from the JDBC driver.
- Throws:
java.sql.SQLException
- The JDBC specification standard wrapper pattern should always be used
where possible:
-
-