|
1.51.2 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--interbase.interclient.Connection
Represents a database session and provides a factory for SQL statements.
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.
InterClient note: 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. Other DBMSs will serialize a lot of operations that InterBase would allow to operate concurrently.
Field Summary | |
static int |
IGNORE_UNCOMMITTED_RECORD_VERSIONS_ON_READ
A read-committed version-acknowledgement mode in which transactions read the most recent committed updates of concurrent transactions. |
static int |
LOCK_RESOLUTION_NO_WAIT
The InterBase lock resolution protocol in which a transaction will not wait for locks to be released, but instead, a LockConflictException is thrown immediately. |
static int |
LOCK_RESOLUTION_WAIT
The default lock resolution mode for InterBase in which a transaction will wait for a database lock. |
static int |
RECOGNIZE_UNCOMMITTED_RECORD_VERSIONS_ON_READ
A read-committed version-acknowledgement mode in which transactions read the last committed update but not if an uncommitted update is pending. |
static int |
TABLELOCK_PROTECTED_READ
A table lock in which this transaction reserves exclusive access to a table for reads. |
static int |
TABLELOCK_PROTECTED_WRITE
A table lock in which this transaction reserves exclusive access to a table for writes. |
static int |
TABLELOCK_SHARED_READ
A table lock in which a table may be accessed read-only, and may also be shared by concurrent transactions. |
static int |
TABLELOCK_SHARED_WRITE
The default table lock for snapshot and read-committed transactions in which a table may be shared by concurrent transactions for writes. |
static int |
TRANSACTION_NONE
JDBC Isolation level in which transactions are not supported. |
static int |
TRANSACTION_READ_COMMITTED
JDBC Isolation level in which dirty reads are prevented; non-repeatable reads and phantom reads can occur. |
static int |
TRANSACTION_READ_UNCOMMITTED
JDBC Isolation level in which dirty reads, non-repeatable reads and phantom reads can occur. |
static int |
TRANSACTION_REPEATABLE_READ
JDBC Isolation level in which dirty reads and non-repeatable reads are prevented; phantom reads can occur. |
static int |
TRANSACTION_SERIALIZABLE
JDBC Isolation level in which dirty reads, non-repeatable reads and phantom reads are prevented. |
static int |
TRANSACTION_SNAPSHOT
A synonym for TRANSACTION_SERIALIZABLE. |
static int |
TRANSACTION_SNAPSHOT_TABLE_STABILITY
A native InterBase isolation which ensures exclusive write-access to tables which are being modified. |
Method Summary | |
void |
clearWarnings()
After this call, getWarnings returns null until a new warning is reported for this Connection. |
void |
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. |
void |
commit()
Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. |
void |
commitRetain()
Like commit but keeps your snapshot and retains your transaction context. |
Statement |
createStatement()
Create a Statement as a container for executing SQL on this connection. |
Statement |
createStatement(int resultSetType,
int resultSetConcurrency)
Same as createStatement() above, but allows the default result set
type and result set concurrency type to be overridden. |
protected void |
finalize()
A connection will be closed when its finalizer is called by the garbage collector. |
boolean |
getAutoCommit()
Get the current auto-commit state. |
String |
getCatalog()
Return the Connection's current catalog name. |
int |
getLockResolution()
Gets this Connection's current lock resolution mode. |
DatabaseMetaData |
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. |
int |
getTableLock(String table)
Gets the current table lock mode on a table for this transaction. |
int |
getTransactionId()
Get the InterBase transaction id for the current transaction. |
int |
getTransactionIsolation()
Get this Connection's current transaction isolation mode. |
Map |
getTypeMap()
Get the type-map object associated with this connection. |
int |
getVersionAcknowledgement()
Gets the current version-acknowledgement mode for a read-committed transaction. |
SQLWarning |
getWarnings()
The first warning reported by calls on this Connection is returned. |
boolean |
inTransaction()
Is a transaction currently active on this connection. |
boolean |
isClosed()
Tests to see if a Connection is closed. |
boolean |
isReadOnly()
Tests to see if the connection is in read-only mode. |
String |
nativeSQL(String sql)
Gets the native SQL recognized by the underlying DBMS for the given JDBC sql string. |
CallableStatement |
prepareCall(String sql)
Prepare a CallableStatement for subsequent use on this connection. |
CallableStatement |
prepareCall(String sql,
int resultSetType,
int resultSetConcurrency)
Same as the JDBC 1 prepareCall(sql), but allows the default result set type and result set concurrency type to be overridden. |
PreparedStatement |
prepareStatement(String sql)
Prepare SQL as a PreparedStatement for subsequent use on this connection. |
PreparedStatement |
prepareStatement(String sql,
int resultSetType,
int resultSetConcurrency)
Same as prepareStatement() above, but allows the default result set
type and result set concurrency type to be overridden. |
void |
rollback()
Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. |
void |
setAutoCommit(boolean enableAutoCommit)
Enable or disable auto-commit on this connection. |
void |
setCatalog(String catalog)
A sub-space of this Connection's database may be selected by setting a catalog name. |
void |
setLockResolution(int mode)
Configures the transaction lock resolution protocol. |
void |
setReadOnly(boolean readOnly)
You can put a connection in read-only mode as a hint to enable database optimizations. |
void |
setTableLock(String table,
int tableLock)
Specify an InterBase lock on a table. |
void |
setTransactionIsolation(int level)
You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values. |
void |
setTypeMap(Map map)
Install a type-map object as the default type-map for this connection. |
void |
setVersionAcknowledgement(int mode)
Configures a read-committed transaction to either recognize or ignore uncommitted record versions of a concurrent transaction on read. |
Methods inherited from class java.lang.Object |
clone,
equals,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
public static final int TRANSACTION_NONE
public static final int TRANSACTION_READ_UNCOMMITTED
InterClient note: InterBase does not support such an unrestricted and dangerous isolation level.
public static final int TRANSACTION_READ_COMMITTED
InterClient notes: InterBase supports two kinds of read-committed transactions. The first kind of read-committed transaction, known as read-committed record-versions, can read a committed record even while it's being modified by another transaction, that is the record may have an uncommitted version. The second kind of read-committed transaction, known as read-committed no-record-versions, will either block or abort while trying to read a record version which has an uncommitted version (depending on the lock resolution mode of wait or no-wait). The two modes may be configured using setVersionAcknowledgement(int mode) with either mode IGNORE_UNCOMMITTED_RECORD_VERSIONS_ON_READ or RECOGNIZE_UNCOMMITTED_RECORD_VERSIONS_ON_READ. The default mode for a read-committed transaction is RECOGNIZE_UNCOMMITTED_RECORD_VERSIONS_ON_READ.
public static final int TRANSACTION_REPEATABLE_READ
InterClient note: Repeatable reads are achieved using InterBase's snapshot model of concurrency, which was known as Concurrency mode prior to v4.
public static final int TRANSACTION_SERIALIZABLE
InterClient note: InterBase's multi-generational architecture, aka versioning engine, provides the superb implementation of serializability through the snapshot model of concurrency. Under the snapshot model, once a transaction starts, a snapshot of committed records is taken when the transaction starts, the snapshot is insensitive to the record changes of other transactions. Only changes made within the local transaction itself are visible to the localized snapshot. Writers in another transaction will not block readers within the local transaction because the local transaction reads from the local snapshot only. Similarly Readers in another transaction will not block writes within the local transaction. However, serializability and effective record locking is achieved because a write within the local transaction will block or abort (depending on the lock resolution mode of wait or no-wait) if another transaction has an uncommitted modification (or version) of that record. In other words, an uncommitted record version provides an effective write-lock on a record.
This native isolation was known as Concurrency mode prior to v4, and is also described as the Snapshot model of concurrency.
public static final int TRANSACTION_SNAPSHOT
This is the native default isolation mode for InterBase, and was formerly known as Concurrency mode prior to v4.
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 through 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.
setTransactionIsolation(int)
public static final int TRANSACTION_SNAPSHOT_TABLE_STABILITY
This isolation level was formerly known as Consistency mode prior to v4.
setTransactionIsolation(int)
public static final int LOCK_RESOLUTION_WAIT
This is the lock resolution protocol in which a transaction will wait for conflicting transactions to release locks.
Note: This native InterBase resolution is also known as WAIT mode.
setLockResolution(int)
public static final int LOCK_RESOLUTION_NO_WAIT
Note: This native InterBase resolution is also known as NO WAIT mode.
setLockResolution(int)
public static final int IGNORE_UNCOMMITTED_RECORD_VERSIONS_ON_READ
This is the default behavior for read-committed transactions in InterClient and the BDE. This version-acknowlegement mode is only meaningful for read-committed transactions.
Note: This native InterBase read-committed mode is also known as RECORD_VERSION.
TRANSACTION_READ_COMMITTED
,
setVersionAcknowledgement(int)
public static final int RECOGNIZE_UNCOMMITTED_RECORD_VERSIONS_ON_READ
If an uncommitted update is pending, then this transaction will either wait on read or throw a LockConflictException, depending on the lock resolution mode.
This version-acknowlegement mode is only meaningful for read-committed transactions.
Note: This native InterBase read-committed mode is also
known as NO RECORD_VERSION
.
TRANSACTION_READ_COMMITTED
,
setVersionAcknowledgement(int)
,
setLockResolution(int)
public static final int TABLELOCK_SHARED_WRITE
Permits table writes by concurrency and read-committed mode transactions with write access; Permits table reads by concurrency and read-committed mode transactions with read access.
This table lock mode is disallowed for TRANSACTION_SNAPSHOT_TABLE_STABILITY transactions, which are inherently protected.
setTableLock(String,int)
public static final int TABLELOCK_SHARED_READ
Permits table writes by other transactions with write access; Permits table reads by any transaction.
setTableLock(String,int)
public static final int TABLELOCK_PROTECTED_WRITE
Permits exclusive table writes only; Permits table reads by snapshot and read-committed mode transactions with read access.
setTableLock(String,int)
public static final int TABLELOCK_PROTECTED_READ
Disallows all table writes; Permits table reads by all transactions.
setTableLock(String,int)
Method Detail |
protected void finalize() throws Throwable
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 ohWell) {} }
Or alternatively, use the System.runFinalizersOnExit () method.
public Statement createStatement() throws SQLException
JDBC 2 note: Result sets created using the returned Statement will have forward-only type, and read-only concurrency, by default.
public PreparedStatement prepareStatement(String sql) throws SQLException
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.
JDBC 2 note: Result sets created using the returned PreparedStatement will have forward-only type, and read-only concurrency, by default.
InterClient note: InterBase supports statement precompilation of prepared statements, allowing for efficient execution of repeated statement executions. Moreover, unlike many other vendors, InterBase allows prepared statements to remain open across transaction commits and rollbacks.
sql
- a SQL statement that may contain one or more '?' IN parameter placeholders.public CallableStatement prepareCall(String sql) throws SQLException
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.
JDBC 2 note: Result sets created using the returned CallableStatement will have forward-only type, and read-only concurrency, by default.
InterClient note: InterBase supports statement precompilation of callable statements, allowing 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.
sql
- a SQL statement that may contain one or more '?'
parameter placeholders. Typically this statement is a JDBC
function call escape string.public String nativeSQL(String sql) throws SQLException
sql
- a SQL statement that may contain one or more '?' parameter placeholderspublic void setAutoCommit(boolean enableAutoCommit) throws SQLException
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.
InterClient note: Although a sequence of auto-committed statements is in general less efficient than a manually committed sequence, InterClient efficiently auto-commits using a native auto-commit mode.
enableAutoCommit
- true enables auto-commit; false disables auto-commit.public boolean getAutoCommit() throws SQLException
setAutoCommit(boolean)
public void commit() throws SQLException
setAutoCommit(boolean)
public void rollback() throws SQLException
setAutoCommit(boolean)
public void close() throws SQLException
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
public DatabaseMetaData getMetaData() throws SQLException
public void setReadOnly(boolean readOnly) throws SQLException
Note: setReadOnly cannot be called while in the middle of a transaction.
InterClient note: A read-only transaction may only read data, and has no write access to tables.
readOnly
- true enables read-only mode; false disables read-only mode.public boolean isReadOnly() throws SQLException
public void setCatalog(String catalog) throws SQLException
InterClient note: InterBase does not support catalogs so this request is ignored and is effectively a no-op.
public String getCatalog() throws SQLException
InterClient note:
Always returns null
.
InterBase does not support catalogs.
public void setTransactionIsolation(int level) throws SQLException
Note: setTransactionIsolation cannot be called while in the middle of a transaction.
InterClient note: InterBase supports the JDBC isolation levels TRANSACTION_REPEATABLE_READ, TRANSACTION_READ_COMMITTED, TRANSACTION_SERIALIZABLE as well as an additional native isolation level TRANSACTION_SNAPSHOT_TABLE_STABILITY surfaced as extension to the base JDBC API. The default isolation level is TRANSACTION_SERIALIZABLE.
level
- one of the TRANSACTION_* isolation values with the
exception of TRANSACTION_NONE; some databases may not support other values.DatabaseMetaData.supportsTransactionIsolationLevel(int)
,
setLockResolution(int)
,
setTableLock(java.lang.String,int)
public int getTransactionIsolation() throws SQLException
public SQLWarning getWarnings() throws SQLException
Note: Subsequent warnings will be chained to this SQLWarning.
public void clearWarnings() throws SQLException
public Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException
createStatement()
above, but allows the default result set
type and result set concurrency type to be overridden.resultSetType
- a result set type, see ResultSet.TYPE_XXXresultSetConcurrency
- a concurrency type, see ResultSet.CONCUR_XXXpublic PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
prepareStatement()
above, but allows the default result set
type and result set concurrency type to be overridden.resultSetType
- a result set type, see ResultSet.TYPE_XXXresultSetConcurrency
- a concurrency type, see ResultSet.CONCUR_XXXpublic CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
resultSetType
- a result set type, see ResultSet.TYPE_XXXresultSetConcurrency
- a concurrency type, see ResultSet.CONCUR_XXXpublic Map getTypeMap() throws SQLException
public void setTypeMap(Map map) throws SQLException
public void setLockResolution(int mode) throws SQLException
Note: This method may not be called while in the middle of a transaction.
public int getLockResolution() throws SQLException
setLockResolution(int)
public void setVersionAcknowledgement(int mode) throws SQLException
This method may not be called while in the middle of a transaction. Furthermore, this method is only applicable to read-committed transactions.
If uncommitted record versions are acknowledged, then a transaction may only read the latest version of a row. If an uncommitted row update is pending, then the transaction will either wait on read or throw a LockConflictException, depending on the lock resolution mode.
If uncommitted record versions are ignored, then the transaction can immediately read the latest committed version of a row, even if a more recent uncommitted version is pending. So uncommitted record versions of concurrent transactions are ignored on read.
setLockResolution(int)
public int getVersionAcknowledgement() throws SQLException
setVersionAcknowledgement(int)
public void setTableLock(String table, int tableLock) throws SQLException
TABLELOCK_*
variables.
Note: This method may not be called while in the middle of a transaction.
public int getTableLock(String table) throws SQLException
public void commitRetain() throws SQLException
public int getTransactionId() throws SQLException
This is a placeholder for proposed future functionality.
public boolean inTransaction() throws SQLException
This is a placeholder for proposed possible future functionality.
|
1.51.2 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |