Using Caché with JDBC
Caché JDBC Compliance
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

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
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:
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:
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:
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:
Connection — Unsupported or Restricted Methods
java.sql.Connection does not support the following optional methods:
Optional Connection Methods with Restrictions
The following optional java.sql.Connection methods are implemented with restrictions or limitations:
The following java.sql.Connection methods do not support CLOSE_CURSORS_AT_COMMIT for resultSetHoldability:
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.
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:
Driver — Unsupported Methods
java.sql.Driver does not support the following optional method:
PreparedStatement — Unsupported Methods
java.sql.PreparedStatement does not support the following optional methods:
ResultSet — Unsupported or Restricted Methods
Caché does not support TYPE_SCROLL_SENSITIVE result set types.
The following method is implemented with restrictions:
java.sql.ResultSet does not support the following optional methods:
Statement — Unsupported or Restricted Methods
java.sql.Statement does not support the following optional methods:
Optional Statement Methods with Restrictions
The following optional java.sql.Statement methods are implemented with restrictions or limitations:
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:
Caché JDBC Additions and Extensions
The following interfaces have additional Caché-specific methods:
CallableStatement Additional Method
java.sql.CallableStatement has the following additional Caché-only method:
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
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:
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
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: