Caché JDBC Compliance

The Caché JDBC Driver is a high-performance type 4 JDBC database driver (pure Java, with no Caché-specific binary code and no JDBC-ODBC bridge). It is fully compliant with the JDBC 4.1 API specification, supporting all required interfaces and adhering to all JDBC 4.1 guidelines and requirements. Caché supports all features except SQL Exception handling enhancements, National Character Set conversions, and the XML data type.

This chapter lists all classes and interfaces of the JDBC 4.1 API, indicates which optional features have been omitted from the Caché driver, and describes all Caché-specific features.

The following topics are covered:

JDBC 4.1 Interfaces and Classes — gives a brief summary of the major JDBC 4.1 implementation requirements.
The JDBC Core API (java.sql) — describes the level of Caché driver support for each element in the java.sql package.
The JDBC Optional Package API (javax.sql) — describes the level of Caché driver support for each element in the javax.sql package.
Interfaces with Unsupported Optional Methods — provides a detailed list of optional methods not supported by the Caché driver.
Caché JDBC Additions and Extensions — describes additional Caché-specific methods available in some interfaces.

JDBC 4.1 Interfaces and Classes

This section gives a brief summary of the major JDBC 4.1 implementation requirements. Classes and exceptions not listed here are already fully implemented in the JDBC 4.1 API.

Required Interfaces

The following interfaces must be fully implemented:

java.sql.DatabaseMetaData	java.sql.ResultSetMetaData	javax.sql.DataSource
java.sql.ParameterMetaData	java.sql.Wrapper

See DatabaseMetaData Variant Methods and CacheDataSource for related information.

Required Interfaces with Optional Methods

The following interfaces must be implemented, but some methods in them are optional if the implementation of those methods depends on a feature that the DBMS does not support:

java.sql.CallableStatement	java.sql.Driver	java.sql.ResultSet
java.sql.Connection	java.sql.PreparedStatement	java.sql.Statement

See Interfaces with Unsupported Optional Methods for details. Also see CallableStatement Additional Method.

Optional Interfaces

The following interfaces are optional. Interfaces in italics are not supported by the Caché JDBC driver:

java.sql.Array	java.sql.Savepoint	javax.sql.CommonDataSource
java.sql.Blob	java.sql.SQLData	javax.sql.ConnectionEventListener
java.sql.Clob	java.sql.SQLInput	javax.sql.ConnectionPoolDataSource
java.sql.NClob	java.sql.SQLOutput	javax.sql.PooledConnection
java.sql.RowId	java.sql.Struct	javax.sql.StatementEventListener
java.sql.Ref		javax.sql.XAConnection
		javax.sql.XADataSource

For additional information, see ConnectionPoolDataSource.

The JDBC Core API (java.sql)

This section describes Caché JDBC driver support for each element in the java.sql package.

java.sql Interfaces

The Caché JDBC driver provides the following levels of support for java.sql interfaces:

Array — not supported
Blob — all methods fully supported
CallableStatement — some optional methods not supported; has some Caché-specific additional methods
Clob — all methods fully supported
Connection — some optional methods not supported
DatabaseMetaData — all methods supported, some with restrictions
Driver — some optional methods not supported
NClob — not supported
ParameterMetaData — all methods fully supported
PreparedStatement — some optional methods not supported
Ref — not supported
ResultSet — some optional methods not supported
ResultSetMetaData — all methods fully supported
RowId — all methods fully supported
Savepoint — all methods fully supported
SQLData — not supported
SQLInput — not supported
SQLOutput — not supported
SQLXML — not supported
Statement — some optional methods not supported or restricted
Struct — not supported
Wrapper — all methods fully supported

java.sql Classes

The following java.sql classes are already fully implemented in the JDBC 4.1 API:

ClientInfoStatus	DriverPropertyInfo	Time
Date	RowIdLifeTime	Timestamp
DriverManager	SQLPermission	Types

java.sql Exceptions

The Caché JDBC driver throws only the following exceptions:

BatchUpdateException
SQLException
SQLWarning

The following exceptions are listed here for completeness, but are not required and are never used:

DataTruncation	SQLNonTransientException
SQLClientInfoException	SQLRecoverableException
SQLDataException	SQLSyntaxErrorException
SQLFeatureNotSupportedException	SQLTimeoutException
SQLIntegrityConstraintViolationException	SQLTransactionRollbackException
SQLInvalidAuthorizationSpecException	SQLTransientConnectionException
SQLNonTransientConnectionException	SQLTransientException

The JDBC Optional Package API (javax.sql)

This section describes Caché JDBC driver support for each element in the javax.sql package.

javax.sql Interfaces

The Caché JDBC driver provides the following levels of support for javax.sql interfaces:

CommonDataSource — not implemented (use DataSource)
ConnectionEventListener — all methods fully supported
ConnectionPoolDataSource — all methods fully supported, with additional methods implemented in CacheConnectionPoolDataSource
DataSource — all methods fully supported, with additional methods implemented in CacheDataSource
PooledConnection — all methods fully supported
Rowset — not supported
RowSetInternal — not supported
RowSetListener — not supported
RowSetMetaData — not supported
RowSetReader — not supported
RowSetWriter — not supported
StatementEventListener — not supported
XAConnection — not supported
XADataSource — not supported

javax.sql Classes

The following javax.sql classes are already fully implemented in the JDBC 4.1 API:

ConnectionEvent

RowSetEvent

StatementEvent

Interfaces with Unsupported Optional Methods

The following interfaces have optional methods that the Caché JDBC driver does not support, or methods implemented in a non-standard manner:

CallableStatement — Unsupported Methods

java.sql.CallableStatement does not support the following optional methods:

getArray()

Array getArray(int i)
Array getArray(String parameterName)

getNCharacterStream() and setNCharacterStream()

Reader getNCharacterStream(int parameterIndex)
Reader getNCharacterStream(String parameterName)

void setNCharacterStream(String parameterName, Reader value)
void setNCharacterStream(String parameterName, Reader value, long length)

getNClob() and setNClob()

java.sql.NClob getNClob(int parameterIndex)
java.sql.NClob getNClob(String parameterName)

void setNClob(String parameterName, Reader reader)
void setNClob(String parameterName, Reader reader, long length)
void setNClob(String parameterName, java.sql.NClob value)

getNString() and setNString()

String getNString(int parameterIndex)
String getNString(String parameterName)

void setNString(String parameterName, String value)

getObject()

Object getObject(int i, java.util.Map map)
Object getObject(String parameterName, java.util.Map map)

getRef()

Ref getRef(int i)
Ref getRef(String parameterName)

getRowId() and setRowId()

java.sql.RowId getRowId(int i)
java.sql.RowId getRowId(String parameterName)

void setRowId(String parameterName, java.sql.RowId x)

getURL() and setURL()

java.net.URL getURL(int i)
java.net.URL getURL(String parameterName)

void setURL(String parameterName, java.net.URL val)

getSQLXML() and setSQLXML()

java.sql.SQLXML getSQLXML(int parameterIndex)
java.sql.SQLXML getSQLXML(String parameterName)

void setSQLXML(String parameterName, java.sql.SQLXML xmlObject)

Connection — Unsupported or Restricted Methods

java.sql.Connection does not support the following optional methods:

abort()
```
void abort(Executor executor)
```

createArrayOf()

java.sql.Array createArrayOf(String typeName, Object[] elements)

createBlob()
```
Blob createBlob()
```
createClob()
```
Clob createClob()
```
createNClob()
```
java.sql.NClob createNClob()
```
createSQLXML()
```
java.sql.SQLXML createSQLXML()
```

createStruct()

java.sql.Struct createStruct(String typeName, Object[] attributes)

getNetworkTimeout()
```
int getNetworkTimeout()
```
getTypeMap()
```
java.util.Map getTypeMap()
```
setTypeMap()
```
void setTypeMap(java.util.Map map)
```

setNetworkTimeout()

void setNetworkTimeout(Executor executor, int milliseconds)

Optional Connection Methods with Restrictions

The following optional java.sql.Connection methods are implemented with restrictions or limitations:

prepareCall()
Only TYPE_FORWARD_ONLY is supported for resultSetType. Only CONCUR_READ_ONLY is supported for resultSetConcurrency.
```
java.sql.CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency)
```
setReadOnly()
A no-op (the Caché driver does not support READ_ONLY mode)
```
void setReadOnly(Boolean readOnly)
```
setCatalog()
A no-op (the Caché driver does not support catalogs)
```
void setCatalog(String catalog)
```
setTransactionIsolation()
Only TRANSACTION_READ_COMMITED and TRANSACTION_READ_UNCOMMITED are supported for level.
```
void setTransactionIsolation(int level)
```

The following java.sql.Connection methods do not support CLOSE_CURSORS_AT_COMMIT for resultSetHoldability:

createStatement()

java.sql.Statement createStatement(int resultSetType, int result, int resultSetHoldability)

getHoldability()
```
int getHoldability()
```

prepareCall()

java.sql.CallableStatement prepareCall(String sql, 
                                       int resultSetType, 
                                       int resultSetConcurrency, 
                                       int resultSetHoldability)

prepareStatement()

java.sql.PreparedStatement prepareStatement(String sql, 
                                       int resultSetType, 
                                       int resultSetConcurrency, 
                                       int resultSetHoldability)

setHoldability()
```
void setHoldability(int holdability)
```

Caché currently supports only zero or one Auto Generated Keys. An exception is thrown if the java.sql.Connection methods below provide columnIndexes or columnNames arrays whose lengths are not equal to one.

prepareStatement()

java.sql.PreparedStatement prepareStatement(String sql, int[] columnIndexes)
java.sql.PreparedStatement prepareStatement(String sql, String[] columnNames)

DatabaseMetaData — Variant Methods

java.sql.DatabaseMetaData is fully supported, but has methods that vary from the JDBC standard due to Caché-specific handling of their return values. The following methods are affected:

supportsMixedCaseQuotedIdentifiers()
Caché returns false, which is not JDBC compliant.
```
boolean supportsMixedCaseQuotedIdentifiers()
```
getIdentifierQuoteString()
If delimited id support is turned on, Caché returns " (double quote character), which is what a JDBC compliant driver should return; otherwise Caché returns a space.
```
String getIdentifierQuoteString()
```

Driver — Unsupported Methods

java.sql.Driver does not support the following optional method:

getParentLogger()
```
void getParentLogger()
```

PreparedStatement — Unsupported Methods

java.sql.PreparedStatement does not support the following optional methods:

setArray()
```
void setArray(int i, Array x)
```

setNCharacterStream()

void setNCharacterStream(int parameterIndex, Reader value)
void setNCharacterStream(int parameterIndex, Reader value, long length)

setNClob()

void setNClob(int parameterIndex, Reader reader, long length)
void setNClob(int parameterIndex, Reader reader)
void setNClob(int parameterIndex, NClob value)

setNString()

void setNString(int parameterIndex, String value)

setRef()
```
void setRef(int i, Ref x)
```

setRowId()

void setRowId(int parameterIndex, RowId x)

setSQLXML()

void setSQLXML(int parameterIndex, SQLXML xmlObject)

setUnicodeStream()

Deprecated in Java JDK specification.

void setUnicodeStream(int i, InputStream x, int length)

setURL()
```
void setURL(int i, java.net.URL x)
```

ResultSet — Unsupported or Restricted Methods

Caché does not support TYPE_SCROLL_SENSITIVE result set types.

The following method is implemented with restrictions:

setFetchDirection()
Does not support ResultSet.FETCH_REVERSE (instead, use afterLast to move the result set's cursor to after the last row, and use previous to scroll backwards).
```
void setFetchDirection(int direction)
```

java.sql.ResultSet does not support the following optional methods:

getArray()

Array getArray(int i)
Array getArray(String colName)

getCursorName()
```
String getCursorName()
```

getObject()

Object getObject(int i, java.util.Map map)
Object getObject(String colName, java.util.Map map)

getRef()

Ref getRef(int i)
Ref getRef(String colName)

getHoldability()
```
int getHoldability()
```

getNString()

String getNString(int columnIndex)
String getNString(String columnLabel)

getNCharacterStream()

Reader getNCharacterStream(int columnIndex)
Reader getNCharacterStream(String columnLabel)

getUnicodeStream()

Deprecated in Java JDK specification.

java.io.InputStream getUnicodeStream(int i)
java.io.InputStream getUnicodeStream(String colName)

getURL()

java.net.URL getURL(int i)
java.net.URL getURL(String colName)

updateArray()

void updateArray(int i, Array x)
void updateArray(String colName, Array x)

updateNString()

void updateNString(int columnIndex, String nString)
void updateNString(String columnLabel, String nString)

updateNCharacterStream()

void updateNCharacterStream(int columnIndex, Reader x)
void updateNCharacterStream(int columnIndex, Reader x, long length)
void updateNCharacterStream(String columnLabel, Reader reader)
void updateNCharacterStream(String columnLabel, Reader reader, long length)

updateNClob()

void updateNClob(int columnIndex, Reader reader)
void updateNClob(int columnIndex, Reader reader, long length)
void updateNClob(String columnLabel, Reader reader)
void updateNClob(String columnLabel, Reader reader, long length)

updateRef()

void updateRef(int i, Ref x)
void updateRef(String colName, Ref x)

Statement — Unsupported or Restricted Methods

java.sql.Statement does not support the following optional methods:

cancel()
```
void cancel()
```
closeOnCompletion()
```
void closeOnCompletion()
```
isCloseOnCompletion()
```
boolean isCloseOnCompletion()
```

Optional Statement Methods with Restrictions

The following optional java.sql.Statement methods are implemented with restrictions or limitations:

getResultSetHoldability()
Only HOLD_CURSORS_OVER_COMMIT
```
int getResultSetHoldability()
```
setCursorName()
A no-op.
```
void setCursorName(String name)
```
setEscapeProcessing()
A no-op (does not apply)
```
void setEscapeProcessing(Boolean enable)
```
setFetchDirection()
Does not support ResultSet.FETCH_REVERSE (instead, use afterLast to move the result set's cursor to after the last row, and use previous to scroll backwards).
```
void setFetchDirection(int direction)
```

Caché currently supports only zero or one auto-generated key. An exception is thrown if the java.sql.Statement methods below provide columnIndexes or columnNames arrays whose lengths are not equal to one:

execute()

boolean execute(String sql, int[] columnIndexes)
boolean execute(String sql, String[] columnNames)

executeUpdate()

int executeUpdate(String sql, int[] columnIndexes)
int executeUpdate(String sql, String[] columnNames)

Caché JDBC Additions and Extensions

The following interfaces have additional Caché-specific methods:

CallableStatement — has an additional method to get binary streams.
CacheConnectionPoolDataSource — is the Caché-specific implementation of the javax.sql.ConnectionPoolDataSource interface.
CacheDataSource — is the Caché-specific implementation of javax.sql.DataSource.

CallableStatement Additional Method

java.sql.CallableStatement has the following additional Caché-only method:

getBinaryStream()
Retrieves the value of the designated parameter (where i is the index of the parameter) as a java.io.InputStream object.
```
java.io.InputStream getBinaryStream(int i)
```

CacheConnectionPoolDataSource

The com.intersys.jdbc.CacheConnectionPoolDataSource class fully implements the javax.sql.ConnectionPoolDataSource interface. This class does not inherit the methods of javax.sql.CommonDataSource, which is not supported by the Caché JDBC driver.

Required Methods

getPooledConnection()

javax.sql.PooledConnection getPooledConnection()
javax.sql.PooledConnection getPooledConnection(String usr,String pwd)

Caution:

Calling applications should never use the getPooledConnection() methods or the PooledConnection class. Caché driver connections must always be obtained by calling the getConnection() method (which is inherited from CacheDataSource). The Caché driver provides pooling transparently through the java.sql.Connection object that it returns.

Additional Caché-only Methods

CacheConnectionPoolDataSource also supports the following additional Caché-only management methods:

restartConnectionPool()
Restarts a connection pool. Closes all physical connections, and empties the connection pool.
```
void restartConnectionPool()
```
getPoolCount()
Returns the current number of entries in the connection pool.
```
int getPoolCount()
```
setMaxPoolSize()
Sets a maximum connection pool size. If the maximum size is not set, it defaults to 40.
```
void setMaxPoolSize(int max)
```
getMaxPoolSize()
Returns the current maximum connection pool size
```
int getMaxPoolSize()
```

CacheConnectionPoolDataSource inherits from CacheDataSource, which provides additional Caché-specific methods.

CacheDataSource

The com.intersys.jdbc.CacheDataSource class fully implements the javax.sql.DataSource interface. This class does not inherit the methods of javax.sql.CommonDataSource, which is not supported by the Caché JDBC driver.

Required Methods

getConnection()

java.sql.Connection getConnection()
java.sql.Connection getConnection(String usr,String pwd)

Additional Caché-only Methods

In addition to the methods defined by the interface, this class also includes a number of Cache specific methods that can be used to get or set DataSource properties.

In order to be able to connect, at least server name and database name properties must be defined, either by using the corresponding setters, or by supplying a valid URL (the same as what would be used when connecting via the Driver class). Port number is optional, and defaults to 1972. Username and Password can be set with the optional methods, or can be supplied via the getConnection() method. See Defining a JDBC Connection URL for details and a complete list of connection parameters.

The following Caché-only management methods are available:

getConnectionSecurityLevel()
Returns an int representing the current Connection Security Level setting.
```
int getConnectionSecurityLevel()
```
getDatabaseName()
Returns a String representing the current database (Caché namespace) name.
```
String getDatabaseName()
```
getDataSourceName()
Returns a String representing the current data source name.
```
String getDataSourceName()
```
getDefaultTransactionIsolation()
Gets the current default transaction isolation.
```
int getDefaultTransactionIsolation()
```
getDescription()
Returns a String representing the current description.
```
String getDescription()
```
getEventClass()
Returns a String representing an Event Class object.
```
String getEventClass()
```
getKeyRecoveryPassword()
Returns a String representing the current Key Recovery Password setting.
```
getKeyRecoveryPassword()
```
getNodelay()
Returns a boolean representing a current TCP_NODELAY option setting.
```
boolean getNodelay()
```
getPassword()
Returns a String representing the current password.
```
String getPassword()
```
getPortNumber()
Returns an int representing the current port number.
```
int getPortNumber()
```
getServerName()
Returns a String representing the current server name.
```
String getServerName()
```
getServicePrincipalName()
Returns a String representing the current Service Principal Name setting.
```
String getServicePrincipalName()
```
getSSLConfigurationName()
Returns a String representing the current SSL Configuration Name setting.
```
getSSLConfigurationName()
```
getURL()
Returns a String representing a current URL for this CacheDataSource object.
```
String getURL()
```
getUser()
Returns a String representing the current username.
```
String getUser()
```

setConnectionSecurityLevel()

Sets the connection security level

Sets the Connection Security Level for this DataSource object.

setDatabaseName()
Sets the database name (Caché namespace) for this CacheDataSource object.
```
void setDatabaseName(String dn)
```
setDataSourceName()
Sets the data source name for this CacheDataSource object. DataSourceName is an optional setting and is not used by CacheDataSource to connect.
```
void setDataSourceName(String dsn)
```
setDefaultTransactionIsolation()
Sets the default transaction isolation level.
```
void setDefaultTransactionIsolation(int level)
```
setDescription()
Sets the description for this CacheDataSource object. Description is an optional setting and is not used by CacheDataSource to connect.
```
void setDescription(String d)
```
setEventClass()
Sets the Event Class for this CacheDataSource object. The Event Class is a mechanism specific to Cache JDBC. It is completely optional, and the vast majority of applications will not need this feature.
The Caché JDBC server will dispatch to methods implemented in a class when a transaction is about to be committed and when a transaction is about to be rolled back. The class in which these methods are implemented is referred to as the “event class.” If an event class is specified during login, then the JDBC server will dispatch to %OnTranCommit just prior to committing the current transaction and will dispatch to %OnTranRollback just prior to rolling back (aborting) the current transaction. User event classes should extend %ServerEvent. The methods do not return any values and cannot abort the current transaction.
```
void setEventClass(String e)
```
setKeyRecoveryPassword()
Sets the Key Recovery Password for this CacheDataSource object.
```
setKeyRecoveryPassword(java.lang.String password) 
```
setLogFile()
Unconditionally sets the log file name for this CacheDataSource object.
```
setLogFile(java.lang.String logFile)
```
setNodelay()
Sets the TCP_NODELAY option for this CacheDataSource object. Toggling this flag can affect the performance of the application. If not set, it defaults to true.
```
void setNodelay(boolean nd)
```
setPassword()
Sets the password for this CacheDataSource object.
```
void setPassword(String p)
```
setPortNumber()
Sets the port number for this CacheDataSource object
```
void setPortNumber(int pn)
```
setServerName()
Sets the server name for this CacheDataSource object.
```
void setServerName(String sn)
```
setServicePrincipalName()
Sets the Service Principal Name for this CacheDataSource object.
```
void setServicePrincipalName(String name)
```
setSSLConfigurationName()
Sets the SSL Configuration Name for this CacheDataSource object.
```
setSSLConfigurationName(java.lang.String name)
```
setURL()
Sets the URL for this CacheDataSource object.
```
void setURL(String u)
```
setUser()
Sets the username for this CacheDataSource object.
```
void setUser(String u)
```