All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class interbase.interclient.Connection

java.lang.Object
   |
   +----interbase.interclient.Connection

public final class Connection

extends Object

implements Connection

A Connection represents a session with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or database changes will not be saved.

One of InterBase's biggest strengths is the row-level locking provided by our versioning engine. This versioning of records is of great importance for applications in which there is a lot of updating going on, and a high level of concurrency is desired. The default InterBase snapshot transaction mode allows for writers not to block readers, and readers not to block writers. MS SQL Server will serialize a lot of operations that InterBase would allow to operate concurrently.

See Also:

getConnection

LOCK_RESOLUTION_NOWAIT

The InterBase lock resolution protocol in which a transaction will not wait for locks to be released, but instead, a LockConflictException is thrown. InterClient Extension.

LOCK_RESOLUTION_WAIT

The default lock resolution mode for InterBase. InterClient Extension.

TABLELOCK_PROTECTED_READ

Disallow all table writes; Permit table reads by all transactions. InterClient Extension.

TABLELOCK_PROTECTED_WRITE

Permit exclusive table writes only; Permit table reads by concurrency and read-committed mode transactions with read access. InterClient Extension.

TABLELOCK_SHARED_READ

Permit table writes by any transaction with write access; Permit table reads by any transaction. InterClient Extension.

TABLELOCK_SHARED_WRITE

Permit table writes by concurrency and read-committed mode transactions with write access; Permit table reads by concurrency and read-committed mode transactions with read access. InterClient Extension.

TRANSACTION_NONE

JDBC Isolation level in which transactions are not supported.

TRANSACTION_READ_COMMITTED

JDBC Isolation level in which dirty reads are prevented; non-repeatable reads and phantom reads can occur.

TRANSACTION_READ_LATEST_COMMITTED_VERSION

An InterBase isolation in which transactions read the last committed update but not if an uncommitted update is pending. InterClient Extension.

TRANSACTION_READ_MOST_RECENT_COMMITTED_VERSION

An InterBase isolation in which transactions read the most recent committed updates of simultaneous transactions (synonym for TRANSACTION_READ_COMMITTED). InterClient Extension.

TRANSACTION_READ_UNCOMMITTED

JDBC Isolation level in which dirty reads, non-repeatable reads and phantom reads can occur.

TRANSACTION_REPEATABLE_READ

JDBC Isolation level in which dirty reads and non-repeatable reads are prevented; phantom reads can occur.

TRANSACTION_SERIALIZABLE

JDBC Isolation level in which dirty reads, non-repeatable reads and phantom reads are prevented.

TRANSACTION_SNAPSHOT

The native isolation mode for InterBase, also known as concurrency mode (synonym for TRANSACTION_SERIALIZABLE). InterClient Extension.

TRANSACTION_SNAPSHOT_TABLE_STABILITY

An InterBase isolation which ensures exclusive write-access to tables which are being modified. InterClient Extension.

clearWarnings()

After this call, getWarnings returns null until a new warning is reported for this Connection.

close()

In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.

commit()

Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.

commitRefresh()

Like commit but a new transaction is started immediately with a fresh snapshot (only meaningful for SNAPSHOT isolation mode). InterClient Extension.

commitRetain()

Like commit but keep your snapshot and retain your transaction context (only meaningful for SNAPSHOT isolation mode). InterClient Extension.

createStatement()

SQL statements without parameters are normally executed using Statement objects.

finalize()

A connection will be closed when its finalizer is called by the garbage collector.

getAutoCommit()

Get the current auto-commit state.

getCatalog()

Return the Connection's current catalog name.

getLockResolution()

Get this Connection's current lock resolution mode. InterClient Extension.

getMetaData()

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc.

getStatistics()

Get statistics for this connection. InterClient Extension.

getTableLock(String)

Get the current table lock mode on a table. InterClient Extension.

getTransactionId()

Get the InterBase transaction id for the current transaction. InterClient Extension.

getTransactionIsolation()

Get this Connection's current transaction isolation mode.

getWarnings()

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

inTransaction()

Is a transaction currently active on this connection? InterClient Extension.

isClosed()

Is the connection closed?

isReadOnly()

Is the connection in read-only mode?

nativeSQL(String)

A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.

prepareCall(String)

A SQL stored procedure call statement is handled by creating a CallableStatement for it.

prepareStatement(boolean, String)

Prepares a statement with InterBase SET_PLAN enabled or disabled. InterClient Extension.

prepareStatement(String)

A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object.

rollback()

Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection.

setAutoCommit(boolean)

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions.

setCatalog(String)

A sub-space of this Connection's database may be selected by setting a catalog name.

setLockResolution(int)

Set the InterBase transaction lock resolution protocol. InterClient Extension.

setReadOnly(boolean)

You can put a connection in read-only mode as a hint to enable database optimizations.

setTableLock(String, int)

Specify an InterBase table lock mode for a table. InterClient Extension.

setTransactionIsolation(int)

You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.

  public final static int TRANSACTION_NONE

JDBC Isolation level in which transactions are not supported.

  public final static int TRANSACTION_READ_UNCOMMITTED

JDBC Isolation level in which dirty reads, non-repeatable reads and phantom reads can occur.

  public final static int TRANSACTION_READ_COMMITTED

JDBC Isolation level in which dirty reads are prevented; non-repeatable reads and phantom reads can occur.

  public final static int TRANSACTION_REPEATABLE_READ

JDBC Isolation level in which dirty reads and non-repeatable reads are prevented; phantom reads can occur.

  public final static int TRANSACTION_SERIALIZABLE

JDBC Isolation level in which dirty reads, non-repeatable reads and phantom reads are prevented.

  public final static int TRANSACTION_READ_MOST_RECENT_COMMITTED_VERSION

InterClient Extension for future release

An InterBase isolation in which transactions read the most recent committed updates of simultaneous transactions (synonym for TRANSACTION_READ_COMMITTED).

This is identical to the JDBC isolation level TRANSACTION_READ_COMMITTED and exists only for the sake of promoting InterBase terminology.

  public final static int TRANSACTION_READ_LATEST_COMMITTED_VERSION

InterClient Extension for future release

An InterBase isolation in which transactions read the last committed update but not if an uncommitted update is pending.

If an uncommitted update is pending, then this transaction will either wait on read or throw a LockConflictException, depending on the lock resolution mode.

  public final static int TRANSACTION_SNAPSHOT

InterClient Extension for future release

The native isolation mode for InterBase, also known as concurrency mode (synonym for TRANSACTION_SERIALIZABLE).

SNAPSHOT transactions keep a snapshot of the database when the transaction starts and do not 'see' the committed updates of simultaneous transactions. This versioning of records provides for serializability in which writers don't block readers, and readers don't block writers. Thereby allowing for high transaction throughput. This isolation level is possible because of InterBase's multi-generational architecture. Although rare, update side effects can occur with this isolation level, but these can be avoided thru the use of triggers or validity constraints.

This variable is identical to the JDBC isolation level TRANSACTION_SERIALIZABLE and exists only for the sake of promoting InterBase terminology.

  public final static int TRANSACTION_SNAPSHOT_TABLE_STABILITY

InterClient Extension for future release

An InterBase isolation which ensures exclusive write-access to tables which are being modified.

This isolation level is used in conjunction with the setTableLock() method.

  public final static int LOCK_RESOLUTION_WAIT

InterClient Extension for future release

The default lock resolution mode for InterBase.

This is the lock resolution protocol in which a transaction will wait for conflicting transactions to release locks.

  public final static int LOCK_RESOLUTION_NOWAIT

InterClient Extension for future release

The InterBase lock resolution protocol in which a transaction will not wait for locks to be released, but instead, a LockConflictException is thrown.

  public final static int TABLELOCK_SHARED_WRITE

InterClient Extension for future release

Permit table writes by concurrency and read-committed mode transactions with write access; Permit table reads by concurrency and read-committed mode transactions with read access.

  public final static int TABLELOCK_SHARED_READ

InterClient Extension for future release

Permit table writes by any transaction with write access; Permit table reads by any transaction.

See Also:

setTableLock

  public final static int TABLELOCK_PROTECTED_WRITE

InterClient Extension for future release

Permit exclusive table writes only; Permit table reads by concurrency and read-committed mode transactions with read access.

  public final static int TABLELOCK_PROTECTED_READ

InterClient Extension for future release

Disallow all table writes; Permit table reads by all transactions.

  protected void finalize() throws Throwable

A connection will be closed when its finalizer is called by the garbage collector. However, there is no guarantee that the garbage collector will ever run, and in general will not run when an application terminates abruptly without closing its connections.

Therefore, it is recommended that connections be explicitly closed even if your application throws an exception. This can be achieved by placing a call to close() in a finally clause of your application as follows

 try {
   ...
 }
 finally {
   if (connection != null)
     try { connection.close (); } catch (SQLException e) {}
 }
 

Or alternatively, use the System.runFinalizersOnExit () method.

Overrides:

finalize in class Object

  public synchronized Statement createStatement() throws SQLException

SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it is more efficient to use a PreparedStatement.

Returns:

a new Statement object.

  public synchronized PreparedStatement prepareStatement(String sql) throws SQLException

A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Note: InterBase supports statement precompilation of prepared statements, alllowing for efficient execution of repeated statement executions. Moreover, unlike many other vendors, InterBase allows prepared statements to remain open across transaction commits and rollbacks.

Parameters:

sql - a SQL statement that may contain one or more '?' IN parameter placeholders.

Returns:

a new PreparedStatement object containing the pre-compiled statement.

Throws: SQLException

If the connection is closed.

  public synchronized CallableStatement prepareCall(String sql) throws SQLException

A SQL stored procedure call statement is handled by creating a CallableStatement for it. The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing it.

Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the prepareCall is done; others may wait until the CallableStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Note: InterBase supports statement precompilation of callable statements, alllowing for efficient execution of repeated stored procedure calls. Moreover, unlike many other vendors, InterBase allows callable statements to remain open across transaction commits and rollbacks.

Parameters:

sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.

Returns:

a new CallableStatement object containing the pre-compiled SQL statement.

Throws: SQLException

If the connection is closed.

  public String nativeSQL(String sql) throws SQLException

A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.

Parameters:

sql - a SQL statement that may contain one or more '?' parameter placeholders

Returns:

the native form of this statement

Throws: SQLException

If an escape syntax error occurs.

  public synchronized void setAutoCommit(boolean enableAutoCommit) throws SQLException

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in auto-commit mode.

The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output param values have been retrieved.

Although a sequence of auto-committed statements is in general less efficient than a manually committed sequence, InterBase efficiently auto-commits using a native auto-commit mode.

Parameters:

enableAutoCommit - true enables auto-commit; false disables auto-commit.

Throws: SQLException

If the connection is closed.

  public boolean getAutoCommit() throws SQLException

Get the current auto-commit state.

Returns:

Current state of auto-commit mode.

See Also:

setAutoCommit

  public synchronized void commit() throws SQLException

Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Throws: SQLException

If auto commit is enabled, or the connection is closed.

See Also:

setAutoCommit

  public synchronized void rollback() throws SQLException

Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Throws: SQLException

If auto commit is enabled, or the connection is closed.

See Also:

setAutoCommit

  public synchronized void close() throws SQLException

In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.

Note: A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection.

  public boolean isClosed() throws SQLException

Is the connection closed?

Returns:

true if the connection is closed; false if it's still open.

  public synchronized DatabaseMetaData getMetaData() throws SQLException

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is made available through a DatabaseMetaData object.

Returns:

a DatabaseMetaData object for this Connection.

  public synchronized void setReadOnly(boolean readOnly) throws SQLException

You can put a connection in read-only mode as a hint to enable database optimizations.

Note: setReadOnly cannot be called while in the middle of a transaction.

Parameters:

readOnly - true enables read-only mode; false disables read-only mode.

Throws: SQLException

If the connection is closed, or a transaction is already active.

  public boolean isReadOnly() throws SQLException

Is the connection in read-only mode?

Returns:

true if connection is read-only.

  public synchronized void setCatalog(String catalog) throws SQLException

A sub-space of this Connection's database may be selected by setting a catalog name. If the driver does not support catalogs it will silently ignore this request.

For InterBase this is a no-op.

Throws: SQLWarning

InterBase does not support Catalogs.

  public String getCatalog() throws SQLException

Return the Connection's current catalog name.

Throws: SQLException

InterBase does not support Catalogs.

  public synchronized void setTransactionIsolation(int level) throws SQLException

You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.

Note: setTransactionIsolation cannot be called while in the middle of a transaction.

InterBase supports the JDBC isolation levels TRANSACTION_READ_COMMITTED, and TRANSACTION_SERIALIZABLE as well as some native isolation levels not surfaced in JDBC.

Parameters:

level - one of the TRANSACTION_* isolation values with the exception of TRANSACTION_NONE; some databases may not support other values.

Throws: SQLException

If the connection is closed, a transaction is already active, or the isolation level is unsupported.

See Also:

supportsTransactionIsolationLevel, setLockResolution, setTableLock

  public int getTransactionIsolation() throws SQLException

Get this Connection's current transaction isolation mode.

Returns:

the current transaction mode TRANSACTION_* value.

  public SQLWarning getWarnings() throws SQLException

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

Note: Subsequent warnings will be chained to this SQLWarning.

Returns:

the first SQLWarning or null

  public synchronized void clearWarnings() throws SQLException

After this call, getWarnings returns null until a new warning is reported for this Connection.

  public void setLockResolution(int mode) throws SQLException

InterClient Extension for future release

Set the InterBase transaction lock resolution protocol.

Note: setLockResolution cannot be called while in the middle of a transaction.

Throws: SQLException

Not yet implemented.

  public int getLockResolution() throws SQLException

InterClient Extension for future release

Get this Connection's current lock resolution mode.

Returns:

LOCK_RESOLUTION_WAIT or LOCK_RESOLUTION_NOWAIT

  public void setTableLock(String table,
                           int mode) throws SQLException

InterClient Extension for future release

Specify an InterBase table lock mode for a table.

Note: setTableLock cannot be called while in the middle of a transaction.

Throws: SQLException

Not yet implemented.

  public int getTableLock(String table) throws SQLException

InterClient Extension for future release

Get the current table lock mode on a table.

Returns:

Table lock mode TABLELOCK_* value.

  public int getTransactionId() throws SQLException

InterClient Extension for future release

Get the InterBase transaction id for the current transaction.

Throws: SQLException

Not yet implemented.

  public void commitRetain() throws SQLException

InterClient Extension for future release

Like commit but keep your snapshot and retain your transaction context (only meaningful for SNAPSHOT isolation mode).

Throws: SQLException

Not yet implemented.

  public void commitRefresh() throws SQLException

InterClient Extension for future release

Like commit but a new transaction is started immediately with a fresh snapshot (only meaningful for SNAPSHOT isolation mode).

Throws: SQLException

Not yet implemented.

  public boolean inTransaction() throws SQLException

InterClient Extension for future release

Is a transaction currently active on this connection?

Throws: SQLException

Not yet implemented.

  public ConnectionStatistics getStatistics() throws SQLException

InterClient Extension for future release

Get statistics for this connection.

Throws: SQLException

Not yet implemented.

  public PreparedStatement prepareStatement(boolean setPlan,
                                            String sql) throws SQLException

InterClient Extension for future release

Prepares a statement with InterBase SET_PLAN enabled or disabled. Equivalent to JDBC prepareStatement if setPlan is false.

Throws: SQLException

Not yet implemented.

All Packages  Class Hierarchy  This Package  Previous  Next  Index