Top Description Fields Methods
org.apache.derby.iapi.jdbc

public Interface EngineConnection

extends Connection
Known Direct Implementers
org.apache.derby.impl.jdbc.EmbedConnection, org.apache.derby.iapi.jdbc.BrokeredConnection
Imports
java.sql.Connection, .SQLException, .SQLWarning, java.util.concurrent.Executor
Additional methods the embedded engine exposes on its Connection object implementations. An internal api only, mainly for the network server. Allows consistent interaction between EmbedConnections and BrokeredConnections.

Field Summary

Inherited from java.sql.Connection:
TRANSACTION_NONETRANSACTION_READ_COMMITTEDTRANSACTION_READ_UNCOMMITTEDTRANSACTION_REPEATABLE_READTRANSACTION_SERIALIZABLE

Method Summary

Modifier and TypeMethod and Description
public void
abort(Executor
The Executor implementation which will be used by abort.
executor)

Redeclares java.sql.Connection.abort.

Terminates an open connection.

public void
addWarning(SQLWarning
Warning to be added, will be chained to any existing warnings.
newWarning)

Add a SQLWarning to this Connection object.

public String

Returns:

the current schema name
getCurrentSchemaName()

Obtain the name of the current schema, so that the NetworkServer can use it for piggy-backing

public Object

Returns:

the LOB Object corresponding to this locator.
getLOBMapping(int
the integer that represents the LOB locator value.
key)

Get the LOB reference corresponding to the locator.

public int
getNetworkTimeout()

Redeclares java.sql.Connection.getNetworkTimeout.

Retrieves the number of milliseconds the driver will wait for a database request to complete.

public int

Returns:

the isolation level
getPrepareIsolation()

Return prepare isolation

public String

Returns:

the current schema name
getSchema()

Redeclares java.sql.Connection.getSchema.

Get the name of the current schema.

public boolean

Returns:

true if this is a global XA transaction
isInGlobalTransaction()

Is this a global transaction

public void
resetFromPool()

Resets the connection before it is returned from a PooledConnection to a new application request (wrapped by a BrokeredConnection).

public void
setDrdaID(String
The DRDA identifier
drdaID)

Set the DRDA identifier for this connection.

public void
setNetworkTimeout(Executor
The Executor implementation which will be used by setNetworkTimeout.
executor, int
The time in milliseconds to wait for the database operation to complete. If the JDBC driver does not support milliseconds, the JDBC driver will round the value up to the nearest second. If the timeout period expires before the operation completes, a SQLException will be thrown. A value of 0 indicates that there is not timeout for database operations.
millis)

Redeclares java.sql.Connection.setNetworkTimeout.

Sets the maximum period a Connection or objects created from the Connection will wait for the database to reply to any one request.

public void
setPrepareIsolation(int
Isolation level to change to. level is the DB2 level specified in the package names which happen to correspond to our internal levels. If level == ExecutionContext.UNSPECIFIED_ISOLATION, the statement won't be prepared with an isolation level.
level)

Set the transaction isolation level that will be used for the next prepare.

public void
setSchema(String
The new default schema
schemaName)

Redeclares java.sql.Connection.setSchema.

Set the default schema for the Connection.

Inherited from java.sql.Connection:
beginRequestclearWarningsclosecommitcreateArrayOfcreateBlobcreateClobcreateNClobcreateSQLXMLcreateStatementcreateStatementcreateStatementcreateStructendRequestgetAutoCommitgetCataloggetClientInfogetClientInfogetHoldabilitygetMetaDatagetTransactionIsolationgetTypeMapgetWarningsisClosedisReadOnlyisValidnativeSQLprepareCallprepareCallprepareCallprepareStatementprepareStatementprepareStatementprepareStatementprepareStatementprepareStatementreleaseSavepointrollbackrollbacksetAutoCommitsetCatalogsetClientInfosetClientInfosetHoldabilitysetReadOnlysetSavepointsetSavepointsetShardingKeysetShardingKeysetShardingKeyIfValidsetShardingKeyIfValidsetTransactionIsolationsetTypeMap

Method Detail

abortback to summary
public void abort(Executor executor) throws SQLException

Redeclares java.sql.Connection.abort.

Doc from java.sql.Connection.abort.

Terminates an open connection. Calling abort results in:

  • The connection marked as closed
  • Closes any physical connection to the database
  • Releases resources used by the connection
  • Insures that any thread that is currently accessing the connection will either progress to completion or throw an SQLException.

Calling abort marks the connection closed and releases any resources. Calling abort on a closed connection is a no-op.

It is possible that the aborting and releasing of the resources that are held by the connection can take an extended period of time. When the abort method returns, the connection will have been marked as closed and the Executor that was passed as a parameter to abort may still be executing tasks to release resources.

This method checks to see that there is an SQLPermission object before allowing the method to proceed. If a SecurityManager exists and its checkPermission method denies calling abort, this method throws a java.lang.SecurityException.

Parameters
executor:Executor

The Executor implementation which will be used by abort.

Exceptions
SQLException:
if a database access error occurs or the executor is null,
addWarningback to summary
public void addWarning(SQLWarning newWarning) throws SQLException

Add a SQLWarning to this Connection object.

Parameters
newWarning:SQLWarning

Warning to be added, will be chained to any existing warnings.

Exceptions
SQLException:
on error
getCurrentSchemaNameback to summary
public String getCurrentSchemaName() throws SQLException

Obtain the name of the current schema, so that the NetworkServer can use it for piggy-backing

Returns:String

the current schema name

Exceptions
SQLException:
on error
getLOBMappingback to summary
public Object getLOBMapping(int key) throws SQLException

Get the LOB reference corresponding to the locator.

Parameters
key:int

the integer that represents the LOB locator value.

Returns:Object

the LOB Object corresponding to this locator.

Exceptions
SQLException:
on error
getNetworkTimeoutback to summary
public int getNetworkTimeout() throws SQLException

Redeclares java.sql.Connection.getNetworkTimeout.

Doc from java.sql.Connection.getNetworkTimeout.

Retrieves the number of milliseconds the driver will wait for a database request to complete. If the limit is exceeded, a SQLException is thrown.

Returns:int

the current timeout limit in milliseconds; zero means there is no limit

Exceptions
SQLException:
if a database access error occurs or this method is called on a closed Connection
getPrepareIsolationback to summary
public int getPrepareIsolation() throws SQLException

Return prepare isolation

Returns:int

the isolation level

Exceptions
SQLException:
on error
getSchemaback to summary
public String getSchema() throws SQLException

Redeclares java.sql.Connection.getSchema.

Get the name of the current schema.

Returns:String

the current schema name

Exceptions
SQLException:
on error
isInGlobalTransactionback to summary
public boolean isInGlobalTransaction()

Is this a global transaction

Returns:boolean

true if this is a global XA transaction

resetFromPoolback to summary
public void resetFromPool() throws SQLException

Resets the connection before it is returned from a PooledConnection to a new application request (wrapped by a BrokeredConnection).

Note that resetting the transaction isolation level is not performed as part of this method. Temporary tables, IDENTITY_VAL_LOCAL and current schema are reset.

Exceptions
SQLException:
on error
setDrdaIDback to summary
public void setDrdaID(String drdaID)

Set the DRDA identifier for this connection.

Parameters
drdaID:String

The DRDA identifier

setNetworkTimeoutback to summary
public void setNetworkTimeout(Executor executor, int millis) throws SQLException

Redeclares java.sql.Connection.setNetworkTimeout.

Doc from java.sql.Connection.setNetworkTimeout.

Sets the maximum period a Connection or objects created from the Connection will wait for the database to reply to any one request. If any request remains unanswered, the waiting method will return with a SQLException, and the Connection or objects created from the Connection will be marked as closed. Any subsequent use of the objects, with the exception of the close, isClosed or Connection.isValid methods, will result in a SQLException.

Note

This method is intended to address a rare but serious condition where network partitions can cause threads issuing JDBC calls to hang uninterruptedly in socket reads, until the OS TCP-TIMEOUT (typically 10 minutes). This method is related to the abort() method which provides an administrator thread a means to free any such threads in cases where the JDBC connection is accessible to the administrator thread. The setNetworkTimeout method will cover cases where there is no administrator thread, or it has no access to the connection. This method is severe in it's effects, and should be given a high enough value so it is never triggered before any more normal timeouts, such as transaction timeouts.

JDBC driver implementations may also choose to support the setNetworkTimeout method to impose a limit on database response time, in environments where no network is present.

Drivers may internally implement some or all of their API calls with multiple internal driver-database transmissions, and it is left to the driver implementation to determine whether the limit will be applied always to the response to the API call, or to any single request made during the API call.

This method can be invoked more than once, such as to set a limit for an area of JDBC code, and to reset to the default on exit from this area. Invocation of this method has no impact on already outstanding requests.

The Statement.setQueryTimeout() timeout value is independent of the timeout value specified in setNetworkTimeout. If the query timeout expires before the network timeout then the statement execution will be canceled. If the network is still active the result will be that both the statement and connection are still usable. However if the network timeout expires before the query timeout or if the statement timeout fails due to network problems, the connection will be marked as closed, any resources held by the connection will be released and both the connection and statement will be unusable.

When the driver determines that the setNetworkTimeout timeout value has expired, the JDBC driver marks the connection closed and releases any resources held by the connection.

This method checks to see that there is an SQLPermission object before allowing the method to proceed. If a SecurityManager exists and its checkPermission method denies calling setNetworkTimeout, this method throws a java.lang.SecurityException.

Parameters
executor:Executor

The Executor implementation which will be used by setNetworkTimeout.

millis:int

The time in milliseconds to wait for the database operation to complete. If the JDBC driver does not support milliseconds, the JDBC driver will round the value up to the nearest second. If the timeout period expires before the operation completes, a SQLException will be thrown. A value of 0 indicates that there is not timeout for database operations.

Exceptions
SQLException:
if a database access error occurs, this method is called on a closed connection, the executor is null, or the value specified for seconds is less than 0.
setPrepareIsolationback to summary
public void setPrepareIsolation(int level) throws SQLException

Set the transaction isolation level that will be used for the next prepare. Used by network server to implement DB2 style isolation levels. Note the passed in level using the Derby constants from ExecutionContext and not the JDBC constants from java.sql.Connection.

Parameters
level:int

Isolation level to change to. level is the DB2 level specified in the package names which happen to correspond to our internal levels. If level == ExecutionContext.UNSPECIFIED_ISOLATION, the statement won't be prepared with an isolation level.

Exceptions
SQLException:
on error
setSchemaback to summary
public void setSchema(String schemaName) throws SQLException

Redeclares java.sql.Connection.setSchema.

Set the default schema for the Connection.

Parameters
schemaName:String

The new default schema

Exceptions
SQLException:
on error