Management of TimesTen Database Connections

About TimesTen DSNs

A DSN (data source name) is a logical name that identifies a TimesTen database and the set of connection attributes user for connecting to the database. The type of DSN you create depends on whether your application connects directly to the database or connects from a client.

For TimesTen Scaleout, DSNs are automatically available for all connectables defined in the grid. Refer to Overview of TimesTen Scaleout in the Oracle TimesTen In-Memory Database Scaleout User's Guide for information about creating a database and connecting to a database, using either a direct connection or a client/server connection. See Creating a Database and Connecting to a Database.

For TimesTen Classic, refer to Oracle TimesTen In-Memory Database Operations Guide. To connect directly to the database, create a DSN as described in Creating a DSN on Linux and UNIX for TimesTen Classic. To create a client connection to the database, create a DSN as described in Creating and Configuring Client DSNs on Windows or Creating and Configuring Client DSNs on Linux and UNIX.

After you have created a DSN, your application can connect to the database. The sections that follow describe how to create a JDBC connection to a database using either the JDBC direct driver or the JDBC client driver.

Using Java Wrapper Functionality for Connections

TimesTen exposes TimesTen-specific implementations through standard java.sql.Wrapper functionality.

You can use Wrapper to retrieve connection objects that implement the TimesTenConnection interface and provide access to TimesTen-specific features. The following example returns a TimesTenConnection object then calls its TimesTen extension setReplicationTrack() method.

String databaseUrl = null;
...
Connection conn = DriverManager.getConnection(databaseUrl);
If (conn.isWrapperFor(TimesTenConnection.class) ) {
  TimesTenConnection tconn = conn.unwrap(TimesTenConnection.class);
  tconn.setReplicationTrack(4);
}
...

Creating a Connection URL for the Database and Specifying Connection Attributes

To create a JDBC connection, specify a TimesTen connection URL for the database. The format of a TimesTen connection URL is:

jdbc:timesten:{direct|client}:dsn=DSNname;[DSNattributes;]

The default is direct.

For example, the following creates a direct connection to the sample database:

String URL = "jdbc:timesten:direct:dsn=sampledb";

You can programmatically set or override the connection attributes in the DSN description by specifying attributes in the connection URL.

Refer to Connection Attributes for Data Manager DSNs or Server DSNs in Oracle TimesTen In-Memory Database Operations Guide.

General connection attributes require no special privilege. First connection attributes are set when the database is first loaded, and persist for all connections. Only the instance administrator can load a database with changes to first connection attribute settings. Refer to Connection Attributes in Oracle TimesTen In-Memory Database Reference.

For example, to set the LockLevel general connection attribute to 1, create a URL as follows:

String URL = "jdbc:timesten:direct:dsn=sampledb;LockLevel=1";

Connecting to the Database

After you have defined a URL, you can use the getConnection() method of either DriverManager or TimesTenDataSource to connect to the database.

If you use the DriverManager.getConnection() method, specify the driver URL to connect to the database.

import java.sql.*;
...
Connection conn = DriverManager.getConnection(URL);

To use the TimesTenDataSource method getConnection(), first create a data source. Then use the TimesTenDataSource method setUrl() to set the URL and getConnection() to connect:

import com.timesten.jdbc.TimesTenDataSource;
import java.sql.*;
...

TimesTenDataSource ds = new TimesTenDataSource();
ds.setUrl("jdbc:timesten:direct:<dsn>");
Connection conn = ds.getConnection();

The TimesTen user name and password can be set in the DSN within the URL in the setUrl() call, but there are also TimesTenDataSource methods to set them separately, as well as to set the Oracle Database password (as applicable):

TimesTenDataSource ds = new TimesTenDataSource();
ds.setUser(myttusername);                    // User name to log in to TimesTen
ds.setPassword(ttpassword);                  // Password to log in to TimesTen
ds.setUrl("jdbc:timesten:direct:<dsn>");
ds.setOraclePassword(oraclepassword);        // Password to log in to Oracle DB
Connection conn = ds.getConnection();

Either the DriverManager.getConnection() method or the ds.getConnection() method returns a Connection object (conn in this example) that you can use as a handle to the database. See the level1 sample application for an example on how to use the DriverManager method getConnection(), and the level2 and level3 sample applications for examples of using the TimesTenDataSource method getConnection(). Refer to About TimesTen Quick Start and Sample Applications.

Disconnecting from the Database

When you are finished accessing the database, typically call the Connection method close() to close the connection to the database.

TimesTen connections also support the standard abort() method, as well as standard try-with-resource functionality using java.lang.AutoCloseable.

If an error has occurred, you may want to roll back the transaction before disconnecting from the database. See Non-Fatal Errors and Rolling Back Failed Transactions.

Opening and Closing a Direct Connection

This example shows the general framework for an application that uses the DriverManager class to create a direct connection to the sample database, execute some SQL, and then close the connection.

See the level1 sample application for a working example. (See About TimesTen Quick Start and Sample Applications regarding the sample applications.)

String URL = "jdbc:timesten:dsn=sampledb";
Connection conn = null;

try {
     Class.forName("com.timesten.jdbc.TimesTenDriver");
} catch (ClassNotFoundException ex) {
      // See Error Handling
}

try {
    // Open a connection to TimesTen
    conn = DriverManager.getConnection(URL);

    // Report any SQLWarnings on the connection
    // See Reporting Errors and Warnings

    // Do SQL operations
    // See TimesTen Features and Operations in Your Application below

    // Close the connection to TimesTen
    conn.close();

// Handle any errors
} catch (SQLException ex) {
    // See Error Handling
}

Checking Database Validity

Applications can call this TimesTenConnection method to detect whether the database is valid.

boolean isDataStoreValid() throws java.sql.SQLException

It returns true if the database is valid, or false if the database is in an invalid state, such as due to system or application failure.