Oracle10g JDBC

oracle.jdbc
Interface OracleConnection

All Superinterfaces:
java.sql.Connection
All Known Implementing Classes:
OracleConnectionWrapper

public interface OracleConnection
extends java.sql.Connection

This interface defines the Oracle extensions to the standard JDBC interface java.sql.Connection. You can use java.sql.Connection in your application where you do not make use of the Oracle extensions. However, when your application uses the Oracle extensions to java.sql.Connection you must use oracle.jdbc.OracleConnection.

OracleConnection extends standard JDBC connection functionality to create and return Oracle statement objects, set flags and options for Oracle performance extensions, and support type maps for Oracle objects.

Basic example : Once you connect to the database and, in the process, create your Connection object (see OracleDriver), the next step is to create a Statement object. The createStatement method of your JDBC Connection object returns an object of the JDBC Statement type.
Here is an example of how to create the Statement object (conn being your connection object):

Statement stmt = conn.createStatement();

Note that there is nothing Oracle-specific about this statement; it follows standard JDBC syntax.

Since:
8.1.7

Field Summary
static int ABANDONED_CONNECTION_CALLBACK
           
static int ALL_CONNECTION_CALLBACKS
           
static int CACHE_SIZE_NOT_SET
           
static int CONNECTION_RELEASE_HIGH
           
static int CONNECTION_RELEASE_LOCKED
           
static int CONNECTION_RELEASE_LOW
           
static int DATABASE_CLOSED
          Define return values for pingDatabase api The physical database connection is closed.
static int DATABASE_NOTOK
          Define return values for pingDatabase api The physical database connection is not closed but the database is not reachable.
static int DATABASE_OK
          Define return values for pingDatabase api The physical database connection is not closed and the database is reachable.
static int DATABASE_TIMEOUT
          Define return values for pingDatabase api The call timed out before any positive or negative acknowledgement was received.
static int END_TO_END_ACTION_INDEX
           
static int END_TO_END_CLIENTID_INDEX
           
static int END_TO_END_ECID_INDEX
           
static int END_TO_END_MODULE_INDEX
           
static int END_TO_END_STATE_INDEX_MAX
           
static int INVALID_CONNECTION
          Values used for close(int).
static java.lang.String PROXY_CERTIFICATE
           
static java.lang.String PROXY_DISTINGUISHED_NAME
           
static java.lang.String PROXY_ROLES
           
static int PROXY_SESSION
          Values used for close(int).
static java.lang.String PROXY_USER_NAME
           
static java.lang.String PROXY_USER_PASSWORD
           
static int PROXYTYPE_CERTIFICATE
           
static int PROXYTYPE_DISTINGUISHED_NAME
           
static int PROXYTYPE_USER_NAME
           
static int RELEASE_CONNECTION_CALLBACK
           
 
Fields inherited from interface java.sql.Connection
TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE
 
Method Summary
 java.sql.Connection _getPC()
          Return the underlying physical connection if this is a logical connection.
 void applyConnectionAttributes(java.util.Properties connAttr)
          Applies the connection Attributes provided on the underlying PooledConnection.
 void archive(int mode, int aseq, java.lang.String acstext)
          Deprecated. This method will be removed in a future version.
 void close(int opt)
          If opt is OracleConnection.INVALID_CONNECTION : Closes the given Logical connection, as well the underlying PooledConnection without returning the connection to the cache when called with the parameter INVALID_CONNECTION.
 void close(java.util.Properties connAttr)
          Closes the given Logical connection, and returns the underlying PooledConnection to the implicit connection cache.
 boolean getAutoClose()
          The driver is always in auto-close mode.
 java.sql.CallableStatement getCallWithKey(java.lang.String key)
          getCallWithKey Searches the explicit cache for a match on key.
 java.util.Properties getConnectionAttributes()
          Returns the connection Attributes set on the underlying PooledConnection.
 int getConnectionReleasePriority()
          Returns the release priority set on the connection
 boolean getCreateStatementAsRefCursor()
          Retrieves the current setting of the createStatementAsRefCursor flag which you can set with the setCreateStatementAsRefCursor method.
 int getDefaultExecuteBatch()
          Retrieves the overall connection batch value of this connection.
 int getDefaultRowPrefetch()
          Retrieves the value of row prefetch for all statements associated with this connection and created after this value was set.
 java.lang.Object getDescriptor(java.lang.String sql_name)
          Gets a Descriptor object corresponding to a sql type.
 short getEndToEndECIDSequenceNumber()
          Gets the current end to end tracing context id sequence number.
 java.lang.String[] getEndToEndMetrics()
          Gets the values of the end-to-end metrics, if any.
 boolean getExplicitCachingEnabled()
          getExplicitCachingEnabled Returns true if the explicit cache is currently enabled, false otherwise.
 boolean getImplicitCachingEnabled()
          getImplicitCachingEnabled Returns true if the implicit cache is currently enabled, false otherwise.
 boolean getIncludeSynonyms()
          Checks whether or not synonyms information is included in DatabaseMetaData.getColumns.
 java.lang.Object getJavaObject(java.lang.String sql_name)
          Deprecated.  
 java.util.Properties getProperties()
          Determines the connection properties.
 boolean getRemarksReporting()
          Checks whether or not a call of getTables or getColumns of the DatabaseMetaData interface will report the REMARKS column.
 boolean getRestrictGetTables()
          Gets the restriction status of the returned data in DatabaseMetaData.getTables.
 java.lang.String getSessionTimeZone()
          Obtain Oracle session time zone region name.
 java.lang.String getSQLType(java.lang.Object obj)
          Deprecated.  
 int getStatementCacheSize()
          getStatementCacheSize Returns the current size of the application cache.
 java.sql.PreparedStatement getStatementWithKey(java.lang.String key)
          getStatementWithKey Searches the explicit cache for a match on key.
 int getStmtCacheSize()
          Deprecated. Use getStatementCacheSize() instead.
 short getStructAttrCsId()
          Obtain the Oracle identifier of the character set used in STRUCT attributes.
 java.util.Properties getUnMatchedConnectionAttributes()
          Returns the unmatched connection Attributes from the underlying PooledConnection.
 java.lang.String getUserName()
          Gets the user name of the current connection.
 boolean getUsingXAFlag()
          Deprecated.  
 boolean getXAErrorFlag()
          Deprecated.  
 boolean isLogicalConnection()
          Method that returns a boolean indicating whether its a logical connection or not.
 boolean isProxySession()
          Returns true if the current session associated with this connection is a proxy session.
 void openProxySession(int type, java.util.Properties prop)
          Opens a new proxy session with the username provided in the prop argument and switch to this new session.

This feature is a thin only feature.

Three proxy types are supported :
OracleConnection.PROXYTYPE_USER_NAME : In this type PROXY_USER_NAME needs to be provided in prop.
 void oracleReleaseSavepoint(OracleSavepoint savepoint)
          Removes the given OracleSavepoint object from the current transaction.
 void oracleRollback(OracleSavepoint savepoint)
          Undoes all changes made after the given OracleSavepoint object was set.
 OracleSavepoint oracleSetSavepoint()
          Creates an unnamed savepoint in the current transaction and returns the new OracleSavepoint object that represents it.
 OracleSavepoint oracleSetSavepoint(java.lang.String name)
          Creates a savepoint with the given name in the current transaction and returns the new OracleSavepoint object that represents it.
 int pingDatabase(int timeOut)
          ping Database
 java.sql.CallableStatement prepareCallWithKey(java.lang.String key)
          Deprecated. This is same as prepareCall, except if a Callable Statement with the given KEY exists in the Cache, then the statement is returned AS IT IS when it was closed and cached with this KEY. An object returned from the Cache based on Key will have its state set to "KEYED". If no such Callable Statement is found, then null is returned. Key cannot be null.
 java.sql.PreparedStatement prepareStatementWithKey(java.lang.String key)
          Deprecated. This is same as prepareStatement, except if a Prepared Statement with the given KEY exists in the Cache, then the statement is returned AS IT IS when it was closed and cached with this KEY. An object returned from the Cache based on Key will have its state set to "KEYED". If no such Prepared Statement is found, a null is returned. Key cannot be null.
 void purgeExplicitCache()
          purgeExplicitCache Removes all existing statements from the explicit cache, after which it will be empty.
 void purgeImplicitCache()
          purgeImplicitCache Removes all existing statements from the implicit cache, after which it will be empty.
 void putDescriptor(java.lang.String sql_name, java.lang.Object desc)
          Store the Object Descriptor for later usage.
 void registerConnectionCacheCallback(OracleConnectionCacheCallback occc, java.lang.Object userObj, int cbkFlag)
          Registers the connection cache callback on the logical connection This is used in conjunction with the Implicit Connection Cache Properties.
 void registerSQLType(java.lang.String sql_name, java.lang.Class java_class)
          Deprecated.  
 void registerSQLType(java.lang.String sql_name, java.lang.String java_class_name)
          Deprecated.  
 void registerTAFCallback(OracleOCIFailover cbk, java.lang.Object obj)
          Register an application TAF Callback instance that will be called when an application failover occurs.
 void setAutoClose(boolean autoClose)
          We are always in auto-close mode.
 void setConnectionReleasePriority(int priority)
          Sets connection release priority.
 void setCreateStatementAsRefCursor(boolean value)
          When this is set to true, any new statements created from this connection will be created as a REF CURSOR.
 void setDefaultExecuteBatch(int batch)
          Sets a default batch value for the Oracle update batching model (the default value is 1).
 void setDefaultRowPrefetch(int value)
          Sets the value of row prefetch for all statements associated with this connection and created after this value was set.
 void setEndToEndMetrics(java.lang.String[] metrics, short sequenceNumber)
          Sets the values of the end-to-end tracing metrics.
 void setExplicitCachingEnabled(boolean cache)
          setExplicitCachingEnabled Enables or disables the explicit cache.
 void setImplicitCachingEnabled(boolean cache)
          setImplicitCachingEnabled Enables or disables the implicit cache.
 void setIncludeSynonyms(boolean synonyms)
          Turns on or off retrieval of synonym information in DatabaseMetaData.
 void setPlsqlWarnings(java.lang.String setting)
          Enable/Disable PLSQL Compiler Warnings
 void setRemarksReporting(boolean reportRemarks)
          Turns on or off the reporting of the REMARKS columns by the getTables and getColumns calls of the DatabaseMetaData interface.
 void setRestrictGetTables(boolean restrict)
          Turns on or off the restriction of the returned data in DatabaseMetaData.getTables.
 void setSessionTimeZone(java.lang.String regionName)
          Set the session time zone.
 void setStatementCacheSize(int size)
          setStatementCacheSize Specifies the size of the size of the application cache (which will be used by both implicit and explicit caching).
 void setStmtCacheSize(int size)
          Deprecated. Use setStatementCacheSize() instead.
 void setStmtCacheSize(int size, boolean clearMetaData)
          Deprecated. Use setStatementCacheSize() instead.
 void setUsingXAFlag(boolean value)
          Deprecated.  
 void setWrapper(OracleConnection wrapper)
          Set the wrapping object
 void setXAErrorFlag(boolean value)
          Deprecated.  
 void shutdown(int mode)
          Deprecated. This method will be removed in a future version.
 void startup(java.lang.String startup_str, int mode)
          Deprecated. This method will be removed in a future version.
 OracleConnection unwrap()
          Return the wrapping object if any else null
 
Methods inherited from interface java.sql.Connection
clearWarnings, close, commit, createStatement, createStatement, createStatement, getAutoCommit, getCatalog, getHoldability, getMetaData, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setHoldability, setReadOnly, setSavepoint, setSavepoint, setTransactionIsolation, setTypeMap
 

Field Detail

DATABASE_OK

public static final int DATABASE_OK
Define return values for pingDatabase api The physical database connection is not closed and the database is reachable. SQL requests my succeed.

See Also:
Constant Field Values

DATABASE_CLOSED

public static final int DATABASE_CLOSED
Define return values for pingDatabase api The physical database connection is closed. SQL requests will fail.

See Also:
Constant Field Values

DATABASE_NOTOK

public static final int DATABASE_NOTOK
Define return values for pingDatabase api The physical database connection is not closed but the database is not reachable. SQL requests will fail.

See Also:
Constant Field Values

DATABASE_TIMEOUT

public static final int DATABASE_TIMEOUT
Define return values for pingDatabase api The call timed out before any positive or negative acknowledgement was received. SQL requests may or may not succeed.

See Also:
Constant Field Values

INVALID_CONNECTION

public static final int INVALID_CONNECTION
Values used for close(int). The connection is no longer useable.

See Also:
Constant Field Values

PROXY_SESSION

public static final int PROXY_SESSION
Values used for close(int). Close the proxy session, not the entire connection

See Also:
Constant Field Values

ABANDONED_CONNECTION_CALLBACK

public static final int ABANDONED_CONNECTION_CALLBACK
See Also:
Constant Field Values

RELEASE_CONNECTION_CALLBACK

public static final int RELEASE_CONNECTION_CALLBACK
See Also:
Constant Field Values

ALL_CONNECTION_CALLBACKS

public static final int ALL_CONNECTION_CALLBACKS
See Also:
Constant Field Values

CONNECTION_RELEASE_LOCKED

public static final int CONNECTION_RELEASE_LOCKED
See Also:
Constant Field Values

CONNECTION_RELEASE_LOW

public static final int CONNECTION_RELEASE_LOW
See Also:
Constant Field Values

CONNECTION_RELEASE_HIGH

public static final int CONNECTION_RELEASE_HIGH
See Also:
Constant Field Values

PROXYTYPE_USER_NAME

public static final int PROXYTYPE_USER_NAME
See Also:
Constant Field Values

PROXYTYPE_DISTINGUISHED_NAME

public static final int PROXYTYPE_DISTINGUISHED_NAME
See Also:
Constant Field Values

PROXYTYPE_CERTIFICATE

public static final int PROXYTYPE_CERTIFICATE
See Also:
Constant Field Values

PROXY_USER_NAME

public static final java.lang.String PROXY_USER_NAME
See Also:
Constant Field Values

PROXY_USER_PASSWORD

public static final java.lang.String PROXY_USER_PASSWORD
See Also:
Constant Field Values

PROXY_DISTINGUISHED_NAME

public static final java.lang.String PROXY_DISTINGUISHED_NAME
See Also:
Constant Field Values

PROXY_CERTIFICATE

public static final java.lang.String PROXY_CERTIFICATE
See Also:
Constant Field Values

PROXY_ROLES

public static final java.lang.String PROXY_ROLES
See Also:
Constant Field Values

END_TO_END_ACTION_INDEX

public static final int END_TO_END_ACTION_INDEX
See Also:
Constant Field Values

END_TO_END_CLIENTID_INDEX

public static final int END_TO_END_CLIENTID_INDEX
See Also:
Constant Field Values

END_TO_END_ECID_INDEX

public static final int END_TO_END_ECID_INDEX
See Also:
Constant Field Values

END_TO_END_MODULE_INDEX

public static final int END_TO_END_MODULE_INDEX
See Also:
Constant Field Values

END_TO_END_STATE_INDEX_MAX

public static final int END_TO_END_STATE_INDEX_MAX
See Also:
Constant Field Values

CACHE_SIZE_NOT_SET

public static final int CACHE_SIZE_NOT_SET
See Also:
Constant Field Values
Method Detail

archive

public void archive(int mode,
                    int aseq,
                    java.lang.String acstext)
             throws java.sql.SQLException
Deprecated. This method will be removed in a future version.

Not implemented.

Throws:
java.sql.SQLException

openProxySession

public void openProxySession(int type,
                             java.util.Properties prop)
                      throws java.sql.SQLException
Opens a new proxy session with the username provided in the prop argument and switch to this new session.

This feature is a thin only feature.

Three proxy types are supported :
Roles can also be provided in the property argument. The key is OracleConnection.PROXY_ROLES. The value is a String[] which contains the roles.

Throws:
java.sql.SQLException

getAutoClose

public boolean getAutoClose()
                     throws java.sql.SQLException
The driver is always in auto-close mode.

Returns:
should always return true
Throws:
java.sql.SQLException - should never been raised
See Also:
setAutoClose

getDefaultExecuteBatch

public int getDefaultExecuteBatch()
Retrieves the overall connection batch value of this connection.

The batch value from the connection is used for all prepared statements associated with this connection. A different batch value can also be defined for individual prepared statements. This can be done by using OraclePreparedStatement.setExecuteBatch, which will override the default value provided from the connection. Therefore, the batch value returned by this getDefaultExecuteBatch entrypoint is valid for prepared statements for which you have not defined a different batch value.

The following code retrieves the default batch value of the connection conn.
Integer batch_val = ((OracleConnection)conn).getDefaultExecuteBatch();

Returns:
the batch value
See Also:
OraclePreparedStatement.setExecuteBatch, setDefaultExecuteBatch

getDefaultRowPrefetch

public int getDefaultRowPrefetch()
Retrieves the value of row prefetch for all statements associated with this connection and created after this value was set.

The row-prefetching feature associates an integer row-prefetch setting with a given statement object. JDBC fetches that number of rows at a time from the database during the query. That is, JDBC will fetch N rows that match the query criteria and bring them all back to the client at once, where N is the prefetch setting. Then, once your next calls have run through those N rows, JDBC will go back to fetch the next N rows that match the criteria.

You can set the number of rows to prefetch for a particular Oracle statement (any type of statement). You can also reset the default number of rows that will be prefetched for all statements in your connection with the setDefaultRowPrefetch method. Therefore, the row prefetch value returned by this getDefaultRowPrefetch entrypoint is valid for statements for which you have not defined a different row prefetch value.

The default number of rows to prefetch to the client is 10.

Example where conn is your connection object:
//Get the default row-prefetch setting for this connection
int defRowPref = ((OracleConnection)conn).getDefaultRowPrefetch();

Returns:
the row prefetch value
See Also:
OracleStatement.setRowPrefetch, setDefaultRowPrefetch

getDescriptor

public java.lang.Object getDescriptor(java.lang.String sql_name)
Gets a Descriptor object corresponding to a sql type.

Parameters:
sql_name - the sql type
Returns:
the Descriptor Object that matches the sql type
See Also:
putDescriptor, oracle.sql.TypeDescriptor

getEndToEndMetrics

public java.lang.String[] getEndToEndMetrics()
                                      throws java.sql.SQLException
Gets the values of the end-to-end metrics, if any. Does not include the sequence number. If DMS is in use and metrics have been set via DMS, this method will return the metrics set via DMS, not those set via setEndToEndMetrics. The DMS metric override the metrics set by setEndToEndMetrics.

Throws:
java.sql.SQLException - if an error occurs
See Also:
setEndToEndMetrics

getEndToEndECIDSequenceNumber

public short getEndToEndECIDSequenceNumber()
                                    throws java.sql.SQLException
Gets the current end to end tracing context id sequence number. This could be any of the following values: the value passed in the most recent call to setEndToEndMetrics the value returned by the database after the most recent statement execution the value incremented by JDBC diagnostic messages the value JDBC retrieved from DMS (only in a DMS environment)

Throws:
java.sql.SQLException - if an error occurs

getIncludeSynonyms

public boolean getIncludeSynonyms()
Checks whether or not synonyms information is included in DatabaseMetaData.getColumns. By default and for performance reasons it won't but you can change this with the setIncludeSynonyms method.

Returns:
true if DatabaseMetaData.getColumns will report information if a table synonym is passed in, and false otherwise
See Also:
setIncludeSynonyms

getRestrictGetTables

public boolean getRestrictGetTables()
Gets the restriction status of the returned data in DatabaseMetaData.getTables.

The default behavior is to return information about all synonyms, including those which do not point to accessible tables or views. But you can change this with the setRestrictGetTables method.

Returns:
true if the information returned by DatabaseMetaData.getTables is restricted, and false otherwise
See Also:
setRestrictGetTables

getJavaObject

public java.lang.Object getJavaObject(java.lang.String sql_name)
                               throws java.sql.SQLException
Deprecated.  

Throws:
java.sql.SQLException

getRemarksReporting

public boolean getRemarksReporting()
Checks whether or not a call of getTables or getColumns of the DatabaseMetaData interface will report the REMARKS column.

By default and for performance reasons it won't (it will return null) but you can change this with the setRemarksReporting method.

Returns:
true if the DatabaseMetaData calls getTables and getColumns will report the REMARKS column and false otherwise
See Also:
setRemarksReporting

getSQLType

public java.lang.String getSQLType(java.lang.Object obj)
                            throws java.sql.SQLException
Deprecated.  

Throws:
java.sql.SQLException

getStmtCacheSize

public int getStmtCacheSize()
Deprecated. Use getStatementCacheSize() instead.


getStructAttrCsId

public short getStructAttrCsId()
                        throws java.sql.SQLException
Obtain the Oracle identifier of the character set used in STRUCT attributes. Note that the network transport layer always send structure attributes in the database character set.

Returns:
the Oracle identifier of the character set.
Throws:
java.sql.SQLException - if Conversion is null
See Also:
oracle.sql.CharacterSet for the set of constants defined for the identifiers."

getUserName

public java.lang.String getUserName()
                             throws java.sql.SQLException
Gets the user name of the current connection.

Example where conn is your connection object:
String UserName = ((OracleConnection)conn).getUserName();

Returns:
the user name
Throws:
java.sql.SQLException - if the logical connection is closed

getUsingXAFlag

public boolean getUsingXAFlag()
Deprecated.  

Gets the value of the UsingXA flag which the driver sets to true when using XA to manage distributed transactions. If you are not using distributed transactions with the XA library, the value of the UsingXA flag will be false.

Returns:
true when using XA to manage distributed transactions and false otherwise.
See Also:
setUsingXAFlag

getXAErrorFlag

public boolean getXAErrorFlag()
Deprecated.  

Gets the value of the XAError flag which is used with distributed transactions.

When using distributed transactions with an XA library, you can ask the driver to raise exception when doing anything that might require a transaction. To do so, set the value of the XAError flag to true with the method setXAErrorFlag.

The default value is false.

Returns:
false is the normal JDBC usage. true means that the driver will raise an exception when doing anything that might require a transaction.
See Also:
setXAErrorFlag

pingDatabase

public int pingDatabase(int timeOut)
                 throws java.sql.SQLException
ping Database

Throws:
java.sql.SQLException

putDescriptor

public void putDescriptor(java.lang.String sql_name,
                          java.lang.Object desc)
                   throws java.sql.SQLException
Store the Object Descriptor for later usage.

Parameters:
sql_name - the sql type
desc - the Object Descriptor associated
Throws:
java.sql.SQLException - if sql_name or desc is null
See Also:
getDescriptor, oracle.sql.TypeDescriptor

registerSQLType

public void registerSQLType(java.lang.String sql_name,
                            java.lang.Class java_class)
                     throws java.sql.SQLException
Deprecated.  

Throws:
java.sql.SQLException

registerSQLType

public void registerSQLType(java.lang.String sql_name,
                            java.lang.String java_class_name)
                     throws java.sql.SQLException
Deprecated.  

Throws:
java.sql.SQLException

setAutoClose

public void setAutoClose(boolean autoClose)
                  throws java.sql.SQLException
We are always in auto-close mode.

Parameters:
autoClose - the boolean value
Throws:
java.sql.SQLException - when the argument autoClose is false
See Also:
getAutoClose

setDefaultExecuteBatch

public void setDefaultExecuteBatch(int batch)
                            throws java.sql.SQLException
Sets a default batch value for the Oracle update batching model (the default value is 1).

You can reduce the number of round trips to the database, thereby improving application performance, by grouping multiple UPDATE, DELETE, or INSERT statements into a single "batch" and having the whole batch sent to the database and processed in one trip. To do this, you can either use the Oracle update batching model or the batch updates of the Sun Microsystems JDBC 2.0 specification. The standard model is a manual, explicit model (there is no batch value) whereas the Oracle model is an implicit model.

Note: It is important to be aware that you cannot mix theses models. In any single application, you can use the syntax of one model or the other, but not both. The Oracle JDBC driver will throw exceptions when you mix these syntaxes.

The Oracle update batching feature associates a batch value (limit) with each prepared statement object (this way the driver knows in advance how many operations will be batched). With Oracle update batching, instead of the JDBC driver executing a prepared statement each time its executeUpdate method is called, the driver adds the statement to a batch of accumulated execution requests. The driver will pass all the operations to the database for execution once the batch value is reached. For example, if the batch value is 10, then each batch of 10 operations will be sent to the database and processed in one trip.

The following code sets the default batch value to 20 for all prepared statement objects associated with the conn connection object:

((OracleConnection)conn).setDefaultExecuteBatch(20);

Even though this sets the default batch value for all the prepared statements of the connection, you can override it by calling setDefaultBatch on individual Oracle prepared statements. The connection batch value will apply to statement objects created after this batch value was set.

Note that instead of calling setDefaultExecuteBatch, you can set the defaultBatchValue Java property if you use a Java Properties object in establishing the connection.

Types of Statements Supported. As implemented by Oracle, update batching is intended for use with prepared statements, when you are repeating the same statement with different bind variables. Be aware of the following:

Oracle Update Batching Characteristics and Limitations

Parameters:
batch - your default batch value (default is 1)
Throws:
java.sql.SQLException - if the argument batch is <=0
See Also:
OraclePreparedStatement.setExecuteBatch, getDefaultExecuteBatch

setDefaultRowPrefetch

public void setDefaultRowPrefetch(int value)
                           throws java.sql.SQLException
Sets the value of row prefetch for all statements associated with this connection and created after this value was set.

The row-prefetching feature associates an integer row-prefetch setting with a given statement object. JDBC fetches that number of rows at a time from the database during the query. That is, JDBC will fetch N rows that match the query criteria and bring them all back to the client at once, where N is the prefetch setting. Then, once your next calls have run through those N rows, JDBC will go back to fetch the next N rows that match the criteria.

You can set the number of rows to prefetch for a particular Oracle statement (any type of statement) but this method allows you to reset the default number of rows that will be prefetched for all statements in your connection. The default number of rows to prefetch to the client is 10.

Use the setDefaultRowPrefetch method to set the default number of rows to prefetch, passing in an integer that specifies the desired default. If you want to check the current setting of the default, then use the getDefaultRowPrefetch method. This method returns an integer.

Example where conn is your connection object:
//Set the default row-prefetch setting for this connection to 7
((OracleConnection)conn).setDefaultRowPrefetch(7);

Note 1 : A statement object receives the default row-prefetch setting from the associated connection at the time the statement object is created. Subsequent changes to the connection's default row-prefetch setting have no effect on the statement's row-prefetch setting.

Note 2 : If a column of a result set is of datatype LONG or LONG RAW (that is, the streaming types), JDBC changes the statement's row-prefetch setting to 1, even if you never actually read a value of either of those types.

Note 3 : Do not mix the JDBC 2.0 fetch size API and the Oracle row-prefetching API in your application. You can use one or the other but not both.

Parameters:
value - the number of rows to prefetch
Throws:
java.sql.SQLException - if the argument value is <=0
See Also:
OracleStatement.setRowPrefetch, getDefaultRowPrefetch

setEndToEndMetrics

public void setEndToEndMetrics(java.lang.String[] metrics,
                               short sequenceNumber)
                        throws java.sql.SQLException
Sets the values of the end-to-end tracing metrics. The indices for the array are the END_TO_END_XXX_INDEX values defined in this class. The values set by this method are overridden by any values set via DMS if DMS is in use.

Throws:
java.sql.SQLException - if an error occurs
See Also:
getEndToEndMetrics

setIncludeSynonyms

public void setIncludeSynonyms(boolean synonyms)
Turns on or off retrieval of synonym information in DatabaseMetaData. getColumns.

Similar to setRemarksReporting, getColumns performs extremely slow if information about synonyms has to be included, because it neccessitates an outer join so, by default, the JDBC driver will not report information about synonyms.

You can get synonym information by passing true to this method, and turn it off by passing false. You can also control this behavior by passing a property named "includeSynonyms" as "true" to DriverManager.getConnection.

Parameters:
synonyms - true if you want to retrieve synonym information in DatabaseMetaData.getColumns and false otherwise.
See Also:
getIncludeSynonyms

setRemarksReporting

public void setRemarksReporting(boolean reportRemarks)
Turns on or off the reporting of the REMARKS columns by the getTables and getColumns calls of the DatabaseMetaData interface.

The DatabaseMetaData calls getTables and getColumns are extremely slow if the REMARKS column has to be reported as this necessitates an expensive outer join so by default the JDBC driver does not report the REMARKS columns.

You can turn the reporting of REMARKS on by passing a true argument to this method. You turn it back off by passing a false argument.

Example where conn is your connection object:
((OracleConnection)conn).setRemarksReporting(true);

You can also control the reporting of REMARKS by passing a property named remarksReporting as true to the DriverManager.getConnection call.

Parameters:
reportRemarks - true if you want to turn on the reporting of the REMARKS columns and false otherwise.
See Also:
getRemarksReporting

setRestrictGetTables

public void setRestrictGetTables(boolean restrict)
Turns on or off the restriction of the returned data in DatabaseMetaData.getTables.

DatabaseMetaData.getTables will return information about all accessible tables, views, and synonyms. There are two issues relating to synonyms which can affect the quality of the returned data:

  1. Public synonyms can exist for tables to which you don't have access. Although the synonym itself is viewable, the underlying table is not.
  2. Synonyms can exist for non-table objects, such as procedures, sequences, Java classes, etc.
As a result of the above issues, getTables can return rows containing objects that are not describable with getColumns, either because they are not accessible (issue 1) or because they are not tables or views (issue 2).

To remedy this, you can restrict the results of getTables to only those tables and views to which you have access. This is done by either passing true to this method, or by passing the restrictGetTables property as true to the DriverManager.getConnection call. The default behavior is to return information about all synonyms, including those which do not point to accessible tables or views.

Note that getTables can return more than one row for the same object, one for the object itself, and additional rows for any synonyms defined for that object. This is the case regardless of the setting for restrictGetTables.

The following code turns on the restriction:
((OracleConnection)conn).setRestrictGetTables(true);

Parameters:
restrict - true to turn on the restriction and false otherwise.
See Also:
getRestrictGetTables

setStmtCacheSize

public void setStmtCacheSize(int size)
                      throws java.sql.SQLException
Deprecated. Use setStatementCacheSize() instead.

Throws:
java.sql.SQLException

setStmtCacheSize

public void setStmtCacheSize(int size,
                             boolean clearMetaData)
                      throws java.sql.SQLException
Deprecated. Use setStatementCacheSize() instead.

Throws:
java.sql.SQLException

setStatementCacheSize

public void setStatementCacheSize(int size)
                           throws java.sql.SQLException
setStatementCacheSize Specifies the size of the size of the application cache (which will be used by both implicit and explicit caching).

Parameters:
size - Requested size of the cache. If the existing cache size is less than size, statements will be purged to reduce the size.
Throws:
java.sql.SQLException - if size < 0, or if called on a logical connection.

getStatementCacheSize

public int getStatementCacheSize()
                          throws java.sql.SQLException
getStatementCacheSize Returns the current size of the application cache. This is valid on both physical and logical connections. If the statement cache has not been initialized with setStatementCacheSize(), then CACHE_SIZE_NOT_SET is returned.

Throws:
java.sql.SQLException

setImplicitCachingEnabled

public void setImplicitCachingEnabled(boolean cache)
                               throws java.sql.SQLException
setImplicitCachingEnabled Enables or disables the implicit cache. Note that this is independent of the cache size, set with setStatmentCacheSize().

Parameters:
cache - If true, then implicit caching will be enabled. If false, then any existing statements will be purged and the implicit cache will be disabled.
Throws:
java.sql.SQLException - if called on a logical connection.

getImplicitCachingEnabled

public boolean getImplicitCachingEnabled()
                                  throws java.sql.SQLException
getImplicitCachingEnabled Returns true if the implicit cache is currently enabled, false otherwise. This method is valid on both logical and physical connections.

Throws:
java.sql.SQLException

setExplicitCachingEnabled

public void setExplicitCachingEnabled(boolean cache)
                               throws java.sql.SQLException
setExplicitCachingEnabled Enables or disables the explicit cache. Note that this is independent of the cache size, set with setStatmentCacheSize().

Parameters:
cache - If true, then explicit caching will be enabled. If false, then any existing statements will be purged and the explicit cache will be disabled.
Throws:
java.sql.SQLException - if called on a logical connection.

getExplicitCachingEnabled

public boolean getExplicitCachingEnabled()
                                  throws java.sql.SQLException
getExplicitCachingEnabled Returns true if the explicit cache is currently enabled, false otherwise. This method is valid on both logical and physical connections.

Throws:
java.sql.SQLException

purgeImplicitCache

public void purgeImplicitCache()
                        throws java.sql.SQLException
purgeImplicitCache Removes all existing statements from the implicit cache, after which it will be empty. This method does not affect the size of the application cache, nor the enabled/disabled status.

Throws:
java.sql.SQLException

purgeExplicitCache

public void purgeExplicitCache()
                        throws java.sql.SQLException
purgeExplicitCache Removes all existing statements from the explicit cache, after which it will be empty. This method does not affect the size of the application cache, nor the enabled/disabled status.

Throws:
java.sql.SQLException

getStatementWithKey

public java.sql.PreparedStatement getStatementWithKey(java.lang.String key)
                                               throws java.sql.SQLException
getStatementWithKey Searches the explicit cache for a match on key. If found, the statement is returned, with the paramater and define metadata identical to the last usage. If no match is found, or if explicit caching is not enabled, then null is returned (as opposed to throwing an exception).

Parameters:
key - Specified key to search for
Throws:
java.sql.SQLException

getCallWithKey

public java.sql.CallableStatement getCallWithKey(java.lang.String key)
                                          throws java.sql.SQLException
getCallWithKey Searches the explicit cache for a match on key. If found, the statement is returned, with the paramater and define metadata identical to the last usage. If no match is found, or if explicit caching is not enabled, then null is returned (as opposed to throwing an exception).

Parameters:
key - Specified key to search for
Throws:
java.sql.SQLException

setUsingXAFlag

public void setUsingXAFlag(boolean value)
Deprecated.  

When using distributed transactions with XA, you can set the value of the UsingXA flag.

XA is a general standard (not specific to Java) for distributed transactions. You should use this method only when using XA.

By default, when using distributed transactions with XA, the driver will set the UsingXA flag to true and exceptions will be raised when you want to do anything with your logical connection that might require a transaction. Otherwise the flag UsingXA is always false.

If you are actually using distributed transactions with XA and you dislike the default behavior, you can set the flag back to false.

Parameters:
value - the value of the UsingXA flag
See Also:
getUsingXAFlag

setXAErrorFlag

public void setXAErrorFlag(boolean value)
Deprecated.  

Sets the value of the XAError flag which is used with distributed transactions. When coexisting with an XA library, you can set the XAError flag to true and the driver will then raise an exception when doing anything that might require a transaction.

Parameters:
value - the value of the XAError flag
See Also:
getXAErrorFlag

shutdown

public void shutdown(int mode)
              throws java.sql.SQLException
Deprecated. This method will be removed in a future version.

Not implemented.

Throws:
java.sql.SQLException

startup

public void startup(java.lang.String startup_str,
                    int mode)
             throws java.sql.SQLException
Deprecated. This method will be removed in a future version.

Not implemented

Throws:
java.sql.SQLException

prepareStatementWithKey

public java.sql.PreparedStatement prepareStatementWithKey(java.lang.String key)
                                                   throws java.sql.SQLException
Deprecated. This is same as prepareStatement, except if a Prepared Statement with the given KEY exists in the Cache, then the statement is returned AS IT IS when it was closed and cached with this KEY. An object returned from the Cache based on Key will have its state set to "KEYED". If no such Prepared Statement is found, a null is returned. Key cannot be null.

Parameters:
key - the key with which it was closed
Returns:
a OraclePreparedStatement object
Throws:
java.sql.SQLException - if a database access error occurs

prepareCallWithKey

public java.sql.CallableStatement prepareCallWithKey(java.lang.String key)
                                              throws java.sql.SQLException
Deprecated. This is same as prepareCall, except if a Callable Statement with the given KEY exists in the Cache, then the statement is returned AS IT IS when it was closed and cached with this KEY. An object returned from the Cache based on Key will have its state set to "KEYED". If no such Callable Statement is found, then null is returned. Key cannot be null.

Parameters:
key - the key with which it was closed
Returns:
a oracle.jdbc.driver.CallableStatement object
Throws:
java.sql.SQLException - if a database access error occurs

setCreateStatementAsRefCursor

public void setCreateStatementAsRefCursor(boolean value)
When this is set to true, any new statements created from this connection will be created as a REF CURSOR. Only resultsets obtained from statements that are created as REF CURSORS can be returned from a Java Stored Procedure. This feature is supported by the server-side internal driver only, and is no-op in all other JDBC drivers.

Default value is false.

To use the setCreateStatementAsRefCursor entrypoint you have to cast the Connection object to the type oracle.jdbc.OracleConnection.

Parameters:
value - true if new statements should be created as REF CURSORS, false otherwise
See Also:
getCreateStatementAsRefCursor

getCreateStatementAsRefCursor

public boolean getCreateStatementAsRefCursor()
Retrieves the current setting of the createStatementAsRefCursor flag which you can set with the setCreateStatementAsRefCursor method.

To use the getCreateStatementAsRefCursor entrypoint you have to cast the Connection object to the type oracle.jdbc.OracleConnection.

Returns:
the current setting of the createStatementAsRefCursor flag
See Also:
setCreateStatementAsRefCursor

setSessionTimeZone

public void setSessionTimeZone(java.lang.String regionName)
                        throws java.sql.SQLException
Set the session time zone.

This method is used to set the session time zone. This method must be invoked before accessing any TIMESTAMP WITH LOCAL TIME ZONE data. Upon invocation of this method, the Jdbc driver sets the session timezone of the connection adnd saves the session timezone so that any TSLTZ data accessed via Jdbc are adjusted using the session timezone.

Parameters:
regionName - Oracle session time zone region name.
Throws:
java.sql.SQLException - if an error occurred.
Since:
9i

getSessionTimeZone

public java.lang.String getSessionTimeZone()
Obtain Oracle session time zone region name.

Returns:
Oracle session time zone region name.
Since:
9i

getProperties

public java.util.Properties getProperties()
Determines the connection properties.

See Also:
properties set during creation

_getPC

public java.sql.Connection _getPC()
Return the underlying physical connection if this is a logical connection. Returns null otherwise.

Returns:
Connection object if its a logical handle otherwise returns null

isLogicalConnection

public boolean isLogicalConnection()
Method that returns a boolean indicating whether its a logical connection or not.

Returns:
boolean true if this is a logical connection

registerTAFCallback

public void registerTAFCallback(OracleOCIFailover cbk,
                                java.lang.Object obj)
                         throws java.sql.SQLException
Register an application TAF Callback instance that will be called when an application failover occurs. The TAF feature is only available in the Jdbc OCI driver.

Parameters:
cbk - Callback instance.
obj - Context object in which any client's state can be stored and provided when the callback method is invoked.
Throws:
java.sql.SQLException - if this method is invoked in drivers other than the Jdbc OCI driver.
Since:
9i

unwrap

public OracleConnection unwrap()
Return the wrapping object if any else null

Returns:
wrapping object which implements oracle.jdbc.OracleConnection if any else return null
Since:
9iRw

setWrapper

public void setWrapper(OracleConnection wrapper)
Set the wrapping object

Parameters:
wrapper - An object which implements oracle.jdbc.OracleConnection and which can act as a wrapper for this object # @since 9iR2

oracleSetSavepoint

public OracleSavepoint oracleSetSavepoint()
                                   throws java.sql.SQLException
Creates an unnamed savepoint in the current transaction and returns the new OracleSavepoint object that represents it.

Returns:
the new OracleSavepoint object
Throws:
java.sql.SQLException - if a database access error occurs or this Connection object is currently in auto-commit mode
Since:
9.0.2
See Also:
OracleSavepoint

oracleSetSavepoint

public OracleSavepoint oracleSetSavepoint(java.lang.String name)
                                   throws java.sql.SQLException
Creates a savepoint with the given name in the current transaction and returns the new OracleSavepoint object that represents it.

Parameters:
name - a String containing the name of the savepoint
Returns:
the new OracleSavepoint object
Throws:
java.sql.SQLException - if a database access error occurs or this Connection object is currently in auto-commit mode
Since:
9.0.2
See Also:
OracleSavepoint

oracleRollback

public void oracleRollback(OracleSavepoint savepoint)
                    throws java.sql.SQLException
Undoes all changes made after the given OracleSavepoint object was set.

This method should be used only when auto-commit has been disabled.

Parameters:
savepoint - the OracleSavepoint object to roll back to
Throws:
java.sql.SQLException - if a database access error occurs, the OracleSavepoint object is no longer valid, or this Connection object is currently in auto-commit mode
Since:
9.0.2
See Also:
OracleSavepoint

oracleReleaseSavepoint

public void oracleReleaseSavepoint(OracleSavepoint savepoint)
                            throws java.sql.SQLException
Removes the given OracleSavepoint object from the current transaction. Any reference to the savepoint after it have been removed will cause an SQLException to be thrown.

Parameters:
savepoint - the OracleSavepoint object to be removed
Throws:
java.sql.SQLException - if a database access error occurs or the given OracleSavepoint object is not a valid savepoint in the current transaction
Since:
9.0.2
See Also:
OracleSavepoint

close

public void close(java.util.Properties connAttr)
           throws java.sql.SQLException
Closes the given Logical connection, and returns the underlying PooledConnection to the implicit connection cache. The connection Attributes is set on the PooledConnection. If the connection Attributes passed is null, then a null value is set on the PooledConnection as well. When called on a physical connection, the connection Attributes passed in has no effect.

Parameters:
connAttr - the connection Attributes to be applied
Throws:
java.sql.SQLException - if a database access error occurs

close

public void close(int opt)
           throws java.sql.SQLException
If opt is OracleConnection.INVALID_CONNECTION : Closes the given Logical connection, as well the underlying PooledConnection without returning the connection to the cache when called with the parameter INVALID_CONNECTION. If this API is called on a physical connection, the supplied parameter has no effect.

If opt is OracleConnection.PROXY_SESSION : Closes the proxy session (opened with openProxySession()).

Parameters:
opt - set to INVALID_CONNECTION to close the PooledConnection
Throws:
java.sql.SQLException - if a database access error occurs

isProxySession

public boolean isProxySession()
Returns true if the current session associated with this connection is a proxy session.


applyConnectionAttributes

public void applyConnectionAttributes(java.util.Properties connAttr)
                               throws java.sql.SQLException
Applies the connection Attributes provided on the underlying PooledConnection. The connection Attributes set via the close API overrides the value set by this API.

Parameters:
connAttr - the connection Attributes to be applied
Throws:
java.sql.SQLException - if a database access error occurs

getConnectionAttributes

public java.util.Properties getConnectionAttributes()
                                             throws java.sql.SQLException
Returns the connection Attributes set on the underlying PooledConnection. This API returns null when called on a physical connection.

Throws:
java.sql.SQLException - if a database access error occurs

getUnMatchedConnectionAttributes

public java.util.Properties getUnMatchedConnectionAttributes()
                                                      throws java.sql.SQLException
Returns the unmatched connection Attributes from the underlying PooledConnection. These are essentially the PooledConnection Attributes that did not match the ones from the connection request. This API returns null when called on a physical connection.

Throws:
java.sql.SQLException - if a database access error occurs

registerConnectionCacheCallback

public void registerConnectionCacheCallback(OracleConnectionCacheCallback occc,
                                            java.lang.Object userObj,
                                            int cbkFlag)
                                     throws java.sql.SQLException
Registers the connection cache callback on the logical connection This is used in conjunction with the Implicit Connection Cache Properties.

Parameters:
occc - Implementation of the OracleConnectionCacheCallback Interface
userObj - User private object to be passed when invoking callbacks
cbkFlag - Indicates which callback method to invoke. Supported values are: ABANDONED_CONNECTION_CALLBACK RELEASE_CONNECTION_CALLBACK ALL_CONNECTION_CALLBACKS
Throws:
java.sql.SQLException - if a database access error occurs

setConnectionReleasePriority

public void setConnectionReleasePriority(int priority)
                                  throws java.sql.SQLException
Sets connection release priority. Works in conjunction with the Connection Cache Callback method RELEASE_CONNECTION_CALLBACK Suported release priorities are: CONNECTION_RELEASE_LOCKED CONNECTION_RELEASE_LOW CONNECTION_RELEASE_HIGH

Parameters:
priority - one of the above release priority
Throws:
java.sql.SQLException - if a database access error occurs

getConnectionReleasePriority

public int getConnectionReleasePriority()
                                 throws java.sql.SQLException
Returns the release priority set on the connection

Throws:
java.sql.SQLException - if a database access error occurs

setPlsqlWarnings

public void setPlsqlWarnings(java.lang.String setting)
                      throws java.sql.SQLException
Enable/Disable PLSQL Compiler Warnings

Parameters:
setting - Setting specified for ALTER SESSION SET PLSQL_WARNINGS. Sample values are: "'ENABLE:ALL'", "'DISABLE:ALL'", "'ENALBLE:INFORMATIONAL'", etc. Please refer to the SQL reference of ALTER SESSION SET PLSQL_WARNINGS for more information. If the setting is "'DISABLE:ALL'", jdbc drivers turn off PLSQL Compiler Warnings. Note: the quotes(') in the setting String are necessary.
Throws:
java.sql.SQLException - if a database access error occurs

Oracle10g JDBC

Copyright © 1998,2004, Oracle. All rights reserved