oracle.jdbc
Interface OracleConnection


public abstract interface OracleConnection
extends java.sql.Connection

The OracleConnection class extends the JDBC 1.0 Connection interface.

The implementation relies on native methods. The native methods do all the work and return error codes, a return value >= 0 means the call was successful. The Java methods call the native methods, check the error codes and raise exceptions if errors occured. If the native method get_error_message returns a string that can be used to explain the error to the user.

Since:
8.1.7

Field Summary
static int DATABASE_CLOSED
           
static int DATABASE_NOTOK
           
static int DATABASE_OK
          Define return values for pingDatabase api
static int DATABASE_TIMEOUT
           
 
Fields inherited from class 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 archive(int mode, int aseq, java.lang.String acstext)
           
 void assertComplete()
          Wait until all Ultra method calls to this connection have completed, either by returning or throwing an exception.
 java.sql.Statement createStatementWithKey(java.lang.String key)
          This is same as createStatement, except if a 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.
 boolean getAutoClose()
          We are always in auto-close mode.
 boolean getCreateStatementAsRefCursor()
          Retrieve the current setting of the createStatementAsRefCursor flag.
 int getDefaultExecuteBatch()
          Allows the user to retrieve the batch value for the connection.
 int getDefaultRowPrefetch()
          Allows the user to retrieve the row prefetch value for the connection.
 java.lang.Object getDescriptor(java.lang.String sql_name)
          Return the matched StructDescriptor.
 boolean getIncludeSynonyms()
          Returns true if DatabaseMetaData.getColumns will report information if a table synonym is passed in, and false otherwise.
 java.lang.Object getJavaObject(java.lang.String sql_name)
          Deprecated.  
 boolean getRemarksReporting()
          Return true if the DatabaseMetaData calls getTables and getColumns will report the REMARKS column.
 boolean getRestrictGetTables()
          Returns true if the information returned by DatabaseMetaData.getTables is restricted, and false otherwise.
 java.lang.String getSessionTimeZone()
          Obtain Oracle session time zone region name.
 java.lang.String getSQLType(java.lang.Object obj)
          Deprecated.  
 int getStmtCacheSize()
          Insert the method's description here.
 short getStructAttrCsId()
          Obtain the Oracle identifier of the character set used in STRUCT attributes.
 boolean getSynchronousMode()
          Return the value of the synchronous mode switch for this connection.
 java.lang.String getUserName()
           
 boolean getUsingXAFlag()
           
 boolean getXAErrorFlag()
           
 boolean isLogicalConnection()
          Method that returns a boolean indicating whether its a logical connection or not.
 java.lang.Object openJoltConnection(java.lang.String apiName, short major, short minor)
          When used with the Ultra driver, opens a Jolt connection with the given generic api name and the highest version supported by both parties that is less than or equal to the version provided.
 int pingDatabase(int timeOut)
          ping Database
 java.sql.CallableStatement prepareCallWithKey(java.lang.String key)
          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.
 java.sql.PreparedStatement prepareStatementWithKey(java.lang.String key)
          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.
 void putDescriptor(java.lang.String sql_name, java.lang.Object desc)
          Store the Object Descriptor for later usage.
 void registerApiDescription(java.lang.String apiName, short major, short minor, java.lang.String className)
          When used in the Ultra driver, registers an ApiDescription for use in a Jolt connection.
 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 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)
          Set the batch value for executes for all prepared statements belonging to this connection and created after the batch value was set.
 void setDefaultRowPrefetch(int value)
          Set the value of row prefetch for all statements associated with this connection and created after this value was set.
 void setIncludeSynonyms(boolean synonyms)
          Turn on or off retrieval of synonym information in DatabaseMetaData.
 void setRemarksReporting(boolean reportRemarks)
          Turn 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.
 void setRestrictGetTables(boolean restrict)
          Turn on or off the restriction of the returned data in DatabaseMetaData.
 void setSessionTimeZone(java.lang.String regionName)
          Set the session time zone.
 void setStmtCacheSize(int size)
          Insert the method's description here.
 void setStmtCacheSize(int size, boolean clearMetaData)
          Insert the method's description here.
 void setSynchronousMode(boolean isSynchronous)
          Set the value of the synchronous mode switch for this connection.
 void setUsingXAFlag(boolean value)
           
 void setXAErrorFlag(boolean value)
           
 void shutdown(int mode)
           
 void startup(java.lang.String startup_str, int mode)
           
 
Methods inherited from interface java.sql.Connection
clearWarnings, close, commit, createStatement, createStatement, getAutoCommit, getCatalog, getMetaData, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, nativeSQL, prepareCall, prepareCall, prepareStatement, prepareStatement, rollback, setAutoCommit, setCatalog, setReadOnly, setTransactionIsolation, setTypeMap
 

Field Detail

DATABASE_OK

public static final int DATABASE_OK
Define return values for pingDatabase api

DATABASE_CLOSED

public static final int DATABASE_CLOSED

DATABASE_NOTOK

public static final int DATABASE_NOTOK

DATABASE_TIMEOUT

public static final int DATABASE_TIMEOUT
Method Detail

archive

public void archive(int mode,
                    int aseq,
                    java.lang.String acstext)
             throws java.sql.SQLException
Parameters:
mode -  
aseq -  
acstext -  
Throws:
java.sql.SQLException -  

getAutoClose

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

getDefaultExecuteBatch

public int getDefaultExecuteBatch()
Allows the user to retrieve the batch value for the connection.

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

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

See Also:
OracleStatement.setRowPrefetch, setDefaultRowPrefetch

getDefaultRowPrefetch

public int getDefaultRowPrefetch()
Allows the user to retrieve the row prefetch value for the connection.

The row prefetch from the connection is used for all statements associated with this connection. However, the user can also define a different row prefetch value for each statement. This can be done using Oraclestatement.setRowPrefetch, which will override the default value provided from the connection. Therefore, the row prefetch value returned by this getDefaultRowPrefetch entrypoint is valid for statements for which the user has not defined a different row prefetch.

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

See Also:
OracleStatement.setRowPrefetch, setDefaultRowPrefetch

getDescriptor

public java.lang.Object getDescriptor(java.lang.String sql_name)
Return the matched StructDescriptor.

getIncludeSynonyms

public boolean getIncludeSynonyms()
Returns true if DatabaseMetaData.getColumns will report information if a table synonym is passed in, and false otherwise.


getRestrictGetTables

public boolean getRestrictGetTables()
Returns true if the information returned by DatabaseMetaData.getTables is restricted, and false otherwise.


getJavaObject

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

getRemarksReporting

public boolean getRemarksReporting()
Return true if the DatabaseMetaData calls getTables and getColumns will report the REMARKS column.


getSQLType

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

getStmtCacheSize

public int getStmtCacheSize()
Insert the method's description here. Creation date: (03/03/2000 9:19:30 AM)
Returns:
int

getStructAttrCsId

public short getStructAttrCsId()
                        throws java.sql.SQLException
Obtain the Oracle identifier of the character set used in STRUCT attributes. Note that TTC always send structure attributes in the database character set.
Returns:
the Oracle identifier of the character set. See oracle.sql.CharacterSet for the set of constants defined for the identifiers.

getUserName

public java.lang.String getUserName()
                             throws java.sql.SQLException
Returns:
 
Throws:
java.sql.SQLException -  

getUsingXAFlag

public boolean getUsingXAFlag()
Returns:
 

getXAErrorFlag

public boolean getXAErrorFlag()
Returns:
 

pingDatabase

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

putDescriptor

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

registerSQLType

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

registerSQLType

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

setAutoClose

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

setDefaultExecuteBatch

public void setDefaultExecuteBatch(int batch)
                            throws java.sql.SQLException
Set the batch value for executes for all prepared statements belonging to this connection and created after the batch value was set.

All statements created before using this API to set the batch value will have a batch value of 1.

Batching allows the JDBC driver to avoid making one round-trip to the RDBMS to execute a prepared statement every time bind variables change. The driver "batches" multiple executions of the statement with different bind variables. Actual execution normally happens when the number of executions reaches the pre-defined "batch" value. The set of bind variables along with the number of times the statement needs to be executed (equal to "batch"), are sent to the RDBMS in one round-trip.

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

The user can override the batch value set by this setDefaultExecuteBatch entrypoint for individual prepared statements, by calling OraclePreparedStatement.setExecuteBatch for those statements.

The default value of batch will be overridden by the driver for a particular statement if that statement has any streaming bind values.

See Also:
OracleStatement.setRowPrefetch, getDefaultRowPrefetch

setDefaultRowPrefetch

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

If this value is not set by the user, only 1 row will be fetched at a time.

All statements created before this API was called will have a row prefetch of 1.

Row prefetching allows the JDBC driver to "fetch" multiple rows in one round-trip to the database. If this value is not set by the user, only 1 row will be fetched at a time.

To use the setDefaultRowPrefetch entrypoint you have to cast the Statement object to the type oracle.jdbc.driver.OracleConnection.

The user can override the row prefetch value set by this oracle.jdbc.driver.OracleConnection entrypoint for individual statements, by calling OracleStatement.setRowPrefetch for those statements.

The row_prefetch will be turned back to 1 automatically by the driver if any of the select-column types is streaming (long data or long raw data). This is overrides any value the user might set. Also, this will be done regardless of wether the streaming columns are read or not.

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

See Also:
OracleStatement.setRowPrefetch, getDefaultRowPrefetch

setIncludeSynonyms

public void setIncludeSynonyms(boolean synonyms)
Turn 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. By default, the JDBC driver will not report information about table columns when you pass a synonym to getColumns.

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.


setRemarksReporting

public void setRemarksReporting(boolean reportRemarks)
Turn 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.

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


setRestrictGetTables

public void setRestrictGetTables(boolean restrict)
Turn 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.


setStmtCacheSize

public void setStmtCacheSize(int size)
                      throws java.sql.SQLException
Insert the method's description here. Creation date: (03/03/2000 9:19:04 AM)
Parameters:
size - int

setStmtCacheSize

public void setStmtCacheSize(int size,
                             boolean clearMetaData)
                      throws java.sql.SQLException
Insert the method's description here. Creation date: (03/03/2000 9:18:41 AM)
Parameters:
size - int
clearMetaData - boolean

setUsingXAFlag

public void setUsingXAFlag(boolean value)
Parameters:
value -  

setXAErrorFlag

public void setXAErrorFlag(boolean value)
Parameters:
value -  

shutdown

public void shutdown(int mode)
              throws java.sql.SQLException
Parameters:
mode -  
Throws:
java.sql.SQLException -  

startup

public void startup(java.lang.String startup_str,
                    int mode)
             throws java.sql.SQLException
Parameters:
startup_str -  
mode -  
Throws:
java.sql.SQLException -  

createStatementWithKey

public java.sql.Statement createStatementWithKey(java.lang.String key)
                                          throws java.sql.SQLException
This is same as createStatement, except if a 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 Statement is found in the Cache, a null is returned. Key cannot be null.

Parameters:
key - the key with which it was closed
Returns:
a Statement object or null if no entries are found in the Cache with the given Key.
Throws:
java.sql.SQLException - if a database access error occurs

prepareStatementWithKey

public java.sql.PreparedStatement prepareStatementWithKey(java.lang.String key)
                                                   throws java.sql.SQLException
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
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 feture 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.


getCreateStatementAsRefCursor

public boolean getCreateStatementAsRefCursor()
Retrieve the current setting of the createStatementAsRefCursor flag.
Returns:
current value of createStatementAsRefCursor flag To use the getCreateStatementAsRefCursor entrypoint you have to cast the Connection object to the type oracle.jdbc.OracleConnection.

See Also:
setCreateStatementAsRefCursor(boolean)

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

assertComplete

public void assertComplete()
                    throws java.sql.SQLException
Wait until all Ultra method calls to this connection have completed, either by returning or throwing an exception. This method may throw an exception if one of the calls caused an error on the server. Is a no-op for the Thin, OCI, and Server Internal drivers.
Throws:
java.sql.SQLException -  

getSynchronousMode

public boolean getSynchronousMode()
Return the value of the synchronous mode switch for this connection. When using the Ultra driver may return true or false. If true, then this connection is operating in synchronous mode and exceptions will be thrown by the methods that casue them. If false, then running in asynchronous mode and exceptions may be thrown at some time after the method that caused them returns. See JDBC Users Guide for more details. Asynchronous mode is much faster. In the Thin, OCI, and Server Internal drivers, always returns true.
Returns:
boolean true if synchronous mode, false if asynchronous.

setSynchronousMode

public void setSynchronousMode(boolean isSynchronous)
Set the value of the synchronous mode switch for this connection. When using the Ultra driver may be either true or false. If true, then this connection will operate in synchronous mode and exceptions will be thrown by the methods that casue them. If false, then will run in asynchronous mode and exceptions may be thrown at some time after the method that caused them returns. See JDBC Users Guide for more details. Asynchronous mode is much faster. In the Thin, OCI, and Server Internal drivers, value is ignored.
Parameters:
isSynchronous - true if should run synchronously, false if asynchronously.

registerApiDescription

public void registerApiDescription(java.lang.String apiName,
                                   short major,
                                   short minor,
                                   java.lang.String className)
When used in the Ultra driver, registers an ApiDescription for use in a Jolt connection. See Jolt Appendix of JDBC Users Guide for more details. A single ApiDescription class can be registered for multiple versions and generic api names. The last ApiDescription class registered for a given api name and version replaces any others. Ignored by the Thin, OCI, and Server Internal drivers.
Parameters:
apiName - a String that names the generic api that this ApiDescription supports
major - a short that specifies the major version number that this ApiDescription supports
minor - a short that specifies the minor version number that this ApiDescription supports
className - a String that is the fully qualified class name of the ApiDescription class

openJoltConnection

public java.lang.Object openJoltConnection(java.lang.String apiName,
                                           short major,
                                           short minor)
When used with the Ultra driver, opens a Jolt connection with the given generic api name and the highest version supported by both parties that is less than or equal to the version provided. If there is no common version or the other party does not support that api name, then returns null. You must cast the result to an ApiDescription. See Jolt Appendix of JDBC Users Guide for more details. When used with the Thin, OCI, or Server Internal drivers, always returns null.
Parameters:
apiName - a String that names the generic api to be used
major - the major version number of the highest version to be used
minor - the minor version number of the highest version to be used
Returns:
an ApiDescription that was regisetered with apiName and has the highest version number that is also supported by the server and is less than major.minor or null if none.

_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