Key JDBC Classes and Interfaces

Package Imports

You will need to import some JDBC packages for your application.

Import the standard JDBC package in any Java program that uses JDBC:

import java.sql.*;

If you are going to use data sources or pooled connections, also import the standard extended JDBC package:

import javax.sql.*;

Import the TimesTen JDBC package:

import com.timesten.jdbc.*;

To use XA data sources for JTA, also import this TimesTen package:

import com.timesten.jdbc.xa.*;

Support for Interfaces in the java.sql Package

TimesTen supports the java.sql interfaces.

The supported interfaces are indicated in Table 2-1, with TimesTen-specific support and restrictions noted.

Also see TimesTen JDBC Extensions.

Table 2-1 Supported java.sql Interfaces

Interface in java.sql	Remarks on TimesTen Support
`Blob`	The `position()` method, which returns the position where a specified byte pattern or BLOB pattern begins, is not supported.
`CallableStatement`	You must pass parameters to `CallableStatement` by position, not by name. You cannot use SQL escape syntax. There is no support for `Array`, `Struct`, or `Ref`. There is no support for `Calendar` for `setDate()`, `getDate()`, `setTime()`, or `getTime()`.
`Clob`	The `position()` method, which returns the position where a specified character pattern or CLOB pattern begins, is not supported.
`Connection`	There is no support for savepoints. TimesTen supports Read Committed and Serializable isolation levels: `setTransactionIsolation (TRANSACTION_READ_COMMITTED); setTransactionIsolation (TRANSACTION_SERIALIZABLE);` See Fetching Multiple Rows of Data for information about the relationship between prefetching and isolation level. Also see Concurrency Control Through Isolation and Locking in Oracle TimesTen In-Memory Database Operations Guide and Isolation in Oracle TimesTen In-Memory Database Reference.
`DatabaseMetaData`	There are no restrictions. The `supportsRefCursors()` method returns `TRUE`. The `getMaxLogicalLobSize()` method returns the maximum number of bytes that TimesTen allows for the logical size of a LOB.
`Driver`	TimesTen does not use `java.util.logging`, so the `getParentLogger()` method returns `SQLFeatureNotSupportedException`. (The TimesTen driver preceded `java.util.logging` functionality and uses its own logging mechanism.)
`NClob`	The `position()` method, which returns the position where a specified character pattern or NCLOB pattern begins, is not supported.
`ParameterMetaData`	The JDBC driver cannot determine whether a column is nullable and always returns `parameterNullableUnknown` from calls to `isNullable()`. The `getScale()` method returns 1 for `VARCHAR`, `NVARCHAR`, and `VARBINARY` data types if they are `INLINE`. (Scale is of no significance to these data types.)
`PreparedStatement`	There is no support for `getMetaData()` in `PreparedStatement`. There is no support for `Array`, `Struct`, or `Ref`. Settings using `setObject(java.util.Calendar)` and `setDate(java.util.Date)` are mapped to `TIMESTAMP`. There is no support for the `Calendar` type in `setDate()`, `getDate()`, `setTime()`, or `getTime()`.
`ResultSet`	There is support for `getMetaData()` in `ResultSet`. You cannot have multiple open `ResultSet` objects per statement. You cannot specify the holdability of a result set, so a cursor cannot remain open after it has been committed. There is no support for scrollable or updatable result sets. There is no support for `Array`, `Struct`, or `Ref`. There is no support for the `Calendar` type in `setDate()`, `getDate()`, `setTime()`, or `getTime()`. In the TimesTen implementation, `setFetchSize()` and `getFetchSize()` allow you to set or get the maximum number of rows of data in a client/server result set buffer. See Configuring the Result Set Buffer Size in Client/Server Using JDBC See Working with TimesTen Result Sets: Hints and Restrictions.
`ResultSetMetaData`	The `getPrecision()` method returns 0 for undefined precision. The `getScale()` method returns -127 for undefined scale.
`RowId`	The `ROWID` data type can be accessed using the `RowId` interface. Output and input/output rowids can be registered as `Types.ROWID`. Metadata methods return `Types.ROWID` and `RowId` as applicable.
`Statement`	TimesTen does not support auto-generated keys. In TimesTen, the `cancel()` method delegates to the ODBC function `SQLCancel`. For details about the TimesTen implementation of this function, see ODBC 2.5 Function Support in Oracle TimesTen In-Memory Database C Developer's Guide. The function is also supported for ODBC 3.5. See Managing Cache Groups for special TimesTen functionality of the `getUpdateCount()` method with cache groups. In the TimesTen implementation, `setFetchSize()` and `getFetchSize()` allow you to set or get the maximum number of rows of data in a client/server result set buffer. See Configuring the Result Set Buffer Size in Client/Server Using JDBC
`Wrapper`	TimesTen exposes `TimesTenConnection`, `TimesTenCallableStatement`, `TimesTenPreparedStatement`, and `TimesTenStatement` through `Wrapper`.

Support for Classes in the java.sql Package

TimesTen supports certain java.sql classes (and some additional subclasses of SQLException).

Table 2-2 Supported java.sql Classes

Interface in java.sql	Remarks on TimesTen Support
`DataTruncation`	No remarks
`Date`	No remarks
`DriverManager`	No remarks
`DriverPropertyInfo`	No remarks
`Time`	Because TimesTen does not support `TIMEZONE` in the `TIME` data type, Java client/server applications should run in the same time zone as the server.
`Timestamp`	Same consideration for `TIMESTAMP` as for `TIME`.
`Types`	No remarks
`SQLException`	No remarks
`SQLFeatureNotSupportedException`	No remarks
`SQLWarning`	No remarks

Support Notes for Classes in the java.io Package

There are special notes for TimesTen support of classes in the java.io package.

An InputStream object returned by TimesTen does not support mark or reset operations (specifically, the mark(), markSupported(), and reset() methods).
The read() method of an InputStream or Reader object returns 0 (zero) if the length of the buffer used in the method call is 0, regardless of the amount of data in the InputStream or Reader object. Therefore, usage such as the following is problematic if the CLOB length may be 0, such as if it were populated using the SQL EMPTY_CLOB() function:
```
java.io.Reader r = myclob.getCharacterStream();
char[] buf = new char[myclob.length()]; //buf for r.read() call
```
Typically, when you call read(), -1 is returned if the end of the stream is reached. But in the preceding case, -1 is never returned. Be aware of this when you use streams returned by the BLOB getBinaryStream() method, which returns InputStream, the CLOB getAsciiStream() method, which returns InputStream, or the CLOB getCharacterStream() method, which returns Reader.

Support for Interfaces and Classes in the javax.sql Package

TimesTen supports certain javax.sql interfaces.

CommonDataSource and DataSource are implemented by TimesTenDataSource.

TimesTen does not use java.util.logging, so the getParentLogger() method, specified in CommonDataSource, returns SQLFeatureNotSupportedException. (The TimesTen driver preceded java.util.logging functionality and uses its own logging mechanism.)
PooledConnection is implemented by ObservableConnection.
ConnectionPoolDataSource is implemented by ObservableConnectionDS.
XADataSource is implemented by TimesTenXADataSource (in package com.timesten.jdbc.xa).

Note:

The TimesTen JDBC driver itself does not implement a database connection pool. The ObservableConnection and ObservableConnectionDS classes simply implement standard Java EE interfaces, facilitating the creation and management of database connection pools according to the Java EE standard.

TimesTen supports this javax.sql event listener:

When using a PooledConnection instance, you can register a ConnectionEventListener instance to listen for ConnectionEvent occurrences.

Note:

You can register a StatementEventListener instance in TimesTen; however, StatementEvent instances are not supported.

TimesTen JDBC Extensions

For most scenarios, you can use standard JDBC functionality as supported by TimesTen, but TimesTen also provides extensions in the com.timesten.jdbc package for TimesTen-specific features.

This is shown in Table 2-3.

Table 2-3 TimesTen JDBC Extensions

Interface	Extends	Remarks
`TimesTenBlob`	`Blob`	You can cast `Blob` instances to `TimesTenBlob`. This includes features to indicate whether a LOB is an Oracle Database passthrough LOB, free LOB resources, and get a binary stream with position and length specifications. See Large Objects (LOBs).
`TimesTenCallableStatement`	`CallableStatement`	Exposed through `java.sql.Wrapper`. Supports PL/SQL REF CURSORs. See Working with REF CURSORs. Supports associative array binds with methods to set input parameters and to register and get output parameters. See Working with Associative Arrays.
`TimesTenClob`	`Clob`	You can cast `Clob` instances to `TimesTenClob`. This includes features to indicate whether a LOB is an Oracle Database passthrough LOB, free LOB resources, and get a character stream with position and length specifications. See Large Objects (LOBs).
`TimesTenConnection`	`Connection`	Exposed through `java.sql.Wrapper`. Provides capabilities such as prefetching rows to improve performance, optimizing query performance, listening to events for automatic client failover, setting the track number for parallel replication schemes where you specify replication tracks, checking database validity, and setting the maximum number of rows or bytes for the client/server result set buffer. See Fetching Multiple Rows of Data, Optimizing Query Performance, General Client Failover Features, Features for Use with Replication, Checking Database Validity and Configuring the Result Set Buffer Size in Client/Server Using JDBC.
`TimesTenNClob`	`NClob`	You can cast `NClob` instances to `TimesTenNClob`. This includes features to indicate whether a LOB is an Oracle Database passthrough LOB. See Large Objects (LOBs).
`TimesTenPreparedStatement`	`PreparedStatement`	Exposed through `java.sql.Wrapper`. Supports DML returning. See Working with DML Returning (RETURNING INTO Clause). Supports associative array binds with a method to set input parameters. See Working with Associative Arrays.
`TimesTenStatement`	`Statement`	Exposed through `java.sql.Wrapper`. Provides capabilities for specifying a query threshold or setting or getting the maximum number of rows or bytes for the client/server result set buffer. See Setting a Threshold Duration for SQL Statements and Configuring the Result Set Buffer Size in Client/Server Using JDBC.

Additional TimesTen Classes and Interfaces

In addition to implementations discussed previously, TimesTen provides interfaces and classes in the com.timesten.jdbc package.

Features supported by these interfaces and classes are discussed later in this chapter.

Use interface TimesTenTypes for TimesTen type extensions (such as for TimesTen REF CURSORs).
Use interface ClientFailoverEventListener (and also the ClientFailoverEvent class below) for automatic client failover features. See JDBC Support for Automatic Client Failover.
Use interface TimesTenVendorCode for vendor codes used in SQL exceptions.
Use interface TimesTenDistributionKey and TimesTenDistributionKeyBuilder for client routing in TimesTen Scaleout. See Client Routing API for TimesTen Scaleout.
Use interface TimesTenConnectionBuilder to connect to an optimal element based on a distribution key, element ID, or replica set ID. See Connecting to an Element Based on a Distribution Key.
Use class ClientFailoverEvent (and also the ClientFailoverEventListener interface above) for automatic client failover features.