ca.idms.jdbc
Class IdmsJdbcObject

java.lang.Object
  ca.idms.io.TraceObject
      ca.idms.jdbc.IdmsJdbcObject

All Implemented Interfaces:

Trace, SQLState

Direct Known Subclasses:

IdmsConnection, IdmsDatabaseMetaData, IdmsLogicalConnection, IdmsMetaData, IdmsPooledConnection, IdmsResultObject, IdmsSavepoint

public abstract class IdmsJdbcObject
extends TraceObject
implements SQLState

Common base class for the CA IDMS JDBC driver. This class makes common objects accessible and provides common routines, most of which are related to exception handling, including:

• object state check routines
• unsupported method handling
• methods to get and set warnings, these satisfy several JDBC interfaces
• QCLI error handling, generates SQLExceptions and notifies the connection pool manager listeners if needed
• generates language independent messages for exceptions
• miscellaneous common methods

Most of the classes that make up the the JDBC driver are derived from this class. The exceptions are those classes that must be as small and self-contained as possible, such as IdmsJdbcDriver and IdmsDataSource.

Author:

Dave Ross

Field Summary

static java.lang.String	FAKE_METHODS Resource bundle name for fake support methods.
static java.lang.String	FAKE_SUPPORT System property name to enable "fake support".
static int	fakeSupport Indicates how to handle unsupported JDBC APIs.
static java.lang.String	MESSAGES Resource bundle name for exception message

Fields inherited from class ca.idms.io.TraceObject

exclude, EXCLUDE, FALSE, include, INCLUDE, logWriter, PREFIX, PROPERTIES_FILE, PROPERTIES_KEY, snap, SNAP, SNAP_BYTES, SNAP_NATIVE, SNAP_OBJECT, SNAP_SQL, snapBytes, snapNative, snapObject, snapSql, stub, trace, TRACE, TRACE_FILE, TRACE_LIFE, TRACE_NATIVE, TRACE_PRODUCT, traceLife, traceNative, traceStream, TRUE

Fields inherited from interface ca.idms.qcli.SQLState

SQL_00000, SQL_01000, SQL_01004, SQL_07001, SQL_07009, SQL_08001, SQL_08002, SQL_08003, SQL_08004, SQL_08006, SQL_08007, SQL_0A000, SQL_21000, SQL_22000, SQL_22001, SQL_22003, SQL_22005, SQL_22007, SQL_24000, SQL_25000, SQL_3C000, SQL_40000, SQL_42000, SQL_HY000, SQL_HY004, SQL_HY009, SQL_HY010, SQL_HY024, SQL_HY106, SQL_HYC00

Method Summary

void	clearWarnings() Sets the warning chain to null.
protected java.lang.Object	get(java.lang.reflect.Field f) Allows the default snap method access to non-public variables.
java.sql.SQLWarning	getWarnings() The first warning reported by calls on this object is returned.
boolean	hasCursor() Checks the detailed transaction state.
boolean	hasUpdate() Checks the detailed transaction state.
boolean	isStarted() Checks the transaction state.
boolean	isSuspended() Checks the session state.
boolean	isWrapperFor(java.lang.Class<?> c) Returns true if this object either implements the class or interface argument.
void	notifyStatementError(java.sql.SQLException ex) This utility method can be called to invoke the notifyStatementError method which resides in IdmsPooledConnection.
<T> T	unwrap(java.lang.Class<T> c) Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by a proxy object.

Methods inherited from class ca.idms.io.TraceObject

finalize, getBoolean, getClasses, getInteger, getProperty, listProperties, message, parseList, print, print, print, println, println, snap, snap, snap, snap, snap, snap, snap, toHex, toHex, toHex, toHex, toHex, toString, trace, trace, trace, trace, trace, trace, traceEntry, unloadProperties

Methods inherited from class java.lang.Object

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

Field Detail

MESSAGES

public static final java.lang.String MESSAGES

Resource bundle name for exception message

See Also:

Constant Field Values

fakeSupport

public static int fakeSupport

Indicates how to handle unsupported JDBC APIs. When 0, the default, methods corresponding to features that IDMS does not support throw an SQLException, according to the JDBC 3.0 specification (see Section 6.2). If not zero, the driver will pretend to support these methods, if possible, through a variety of techniques that can include silently ignoring methods that don't return a value, and returning an appropriate value when needed, such as 0, null, or an empty ResultSet, or even a "harmless" actual value in some cases. This can be useful for debugging, and in some case, compatibility with third party products that do not pay proper attention to the DataBaseMetadata feature support methods.

A value of -1 will enable simulation of all unsupported methods, or a least those that are required by an "included" interface. Other non-zero values 0 can be used to selectively enable groups of methods, as directed by CA technical support.

This is controlled by the FAKE_METHODS fake methods resource bundle. This properties file defines a table of fully qualified method names and an hexadecimal integer values acting as a bit flags indicating the "fake support level", for example:

 ca.idms.jdbc.Savepoint.getSavePointName=FFFFFFFF
 ca.idms.jdbc.Connection.setSavePoint=80000000
 

When an unsupported method is invoked, if the bit from the entry for the method is set in fakeSupport the driver will pretend to execute the method if possible, otherwise the driver will throw an SQLException. In the example above, the driver will always simulate the getSavePointName method when fakeSupport is non-zero, but will only simulate setSavePoint if the high order bit is set in fakeSupport.

When fakeSupport == 0 or -1 there is no need to check the resource bundle at all, so we don't. Entries are cached in a Hashtable to minimize the performance impact, but applications should not really be calling these methods anyway, since the DatabaseMetaData methods clearly say the corresponding features are not supported.

A Java application can enable this by setting the value in any object derived from this class (such as IdmsConnection). It can also be enabled by setting the system property ca.jdbc.fake.support=value.

FAKE_SUPPORT

public static final java.lang.String FAKE_SUPPORT

System property name to enable "fake support".

See Also:

Constant Field Values

FAKE_METHODS

public static final java.lang.String FAKE_METHODS

Resource bundle name for fake support methods.

See Also:

Constant Field Values

Method Detail

get

protected java.lang.Object get(java.lang.reflect.Field f)
                        throws java.lang.IllegalAccessException

Allows the default snap method access to non-public variables.

Overrides:

get in class TraceObject

Parameters:

f - a Field returned by Class.getDeclaredFields

Returns:

the Object named by f

Throws:

java.lang.IllegalAccessException - should not happen

See Also:

TraceObject.snap, TraceObject.snap()

getWarnings

public java.sql.SQLWarning getWarnings()
                                throws java.sql.SQLException

The first warning reported by calls on this object is returned.

This method satisfies the JDBC interface for derived classes.

Returns:

the first SQLWarning or null

Throws:

java.sql.SQLException - not!

clearWarnings

public void clearWarnings()
                   throws java.sql.SQLException

Sets the warning chain to null. This method satisfies the JDBC interface for derived classes.

Throws:

java.sql.SQLException - not!.

notifyStatementError

public void notifyStatementError(java.sql.SQLException ex)

This utility method can be called to invoke the notifyStatementError method which resides in IdmsPooledConnection. This is applicable only to Prepared or Callable statements associated with a connection pool.

isWrapperFor

public boolean isWrapperFor(java.lang.Class<?> c)
                     throws java.sql.SQLException

Returns true if this object either implements the class or interface argument.

Parameters:

c - class or interface.

Returns:

true if this object that implements the interface or is an instance of the class.

Throws:

java.sql.SQLException

Since:

1.6

unwrap

public <T> T unwrap(java.lang.Class<T> c)
         throws java.sql.SQLException

Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by a proxy object.

Parameters:

c - class or interface.

Returns:

Object that implements the interface or is an instance of the class.

Throws:

java.sql.SQLException - - If no object found.

Since:

1.6

isSuspended

public boolean isSuspended()

Checks the session state.

When all sessions are suspended the CA IDMS task ends.

Returns:

true if session is suspended

isStarted

public boolean isStarted()

Checks the transaction state.

Returns:

true if a transaction has been started, false if no transaction has been started or the last transaction was committed.

hasUpdate

public boolean hasUpdate()

Checks the detailed transaction state.

Returns:

true if there is an uncommitted update

hasCursor

public boolean hasCursor()

Checks the detailed transaction state.

Returns:

true if there is an uncommitted cursor (the cursor may have been closed)