public interface OracleStatement extends OracleCommonStatement
java.sql.Statement
and is the superinterface of the
OraclePreparedStatement
and OracleCallableStatement
interfaces. You can use java.sql.Statement
in your application
where you do not make use of the Oracle extensions. However, when your
application uses the Oracle extensions to java.sql.Statement
you
must cast your statement object to the type
oracle.jdbc.OracleStatement
. Although the type by which the java
compiler will identify the statement object is changed, the object itself is
unchanged.
Extended functionality includes support for settings flags and options for
Oracle performance extensions on a statement-by-statements basis, as opposed
to the OracleConnection
interface that sets these on a
connection-wide basis.
Connection.createStatement
Modifier and Type | Field and Description |
---|---|
static int |
EXPLICIT |
static int |
IMPLICIT |
static int |
NEW |
Modifier and Type | Method and Description |
---|---|
void |
clearDefines()
Lets you clear previously defined types for the define-columns of this
statement.
|
void |
closeOnCompletion()
Specifies that this Statement will be closed when all its dependent
result sets are closed.
|
void |
closeWithKey(java.lang.String key)
The underlying cursor is not closed and the Statement
handle is cached on the Key.
|
int |
creationState()
Deprecated.
|
void |
defineColumnType(int columnIndex,
int type)
Defines the type you will use to retrieve data from a particular database
table column.
|
void |
defineColumnType(int columnIndex,
int type,
int lobPrefetchSize)
Defines the type you will use to retrieve data from a particular database
table column.
|
void |
defineColumnType(int columnIndex,
int type,
int lobPrefetchSize,
short formOfUse)
Deprecated.
|
void |
defineColumnType(int columnIndex,
int typeCode,
java.lang.String typeName)
Defines the type you will use to retrieve data from a particular database
table column and specifies the column type name.
|
void |
defineColumnTypeBytes(int columnIndex,
int type,
int lobPrefetchSize)
Deprecated.
|
void |
defineColumnTypeChars(int columnIndex,
int type,
int lobPrefetchSize)
Deprecated.
|
default java.lang.String |
enquoteIdentifier(java.lang.String identifier,
boolean alwaysQuote)
Returns a SQL identifier.
|
default java.lang.String |
enquoteLiteral(java.lang.String val)
Returns a
String enclosed in single quotes. |
default java.lang.String |
enquoteNCharLiteral(java.lang.String val)
Returns a
String enclosed in single quotes and prefixed with 'N'. |
int |
getLobPrefetchSize()
Returns the LOB prefetch size.
|
long |
getRegisteredQueryId()
Returns the id of the query that has been added in the registration
(only for query change notification).
|
java.lang.String[] |
getRegisteredTableNames()
Returns the name of the tables that have been added to the registration if any.
|
int |
getRowPrefetch()
Retrieves the value or row prefetch for all result sets created from this
statement.
|
java.lang.String |
getSqlId()
Returns the SQL ID for this statement.
|
boolean |
isNCHAR(int index)
isNCHAR (int)
|
default boolean |
isSimpleIdentifier(java.lang.String identifier)
Retrieves whether
identifier is a simple SQL identifier. |
void |
setDatabaseChangeRegistration(DatabaseChangeRegistration registration)
Associate a Database Change Registration object with this statement.
|
void |
setEscapeProcessing(boolean enable)
Sets escape processing on or off.
|
void |
setLobPrefetchSize(int value)
Overrides the LOB prefetch size for this statement.
|
void |
setRowPrefetch(int value)
Sets the value of row prefetch for all result sets created from this
statement.
|
addBatch, cancel, clearBatch, clearWarnings, close, execute, execute, execute, execute, executeBatch, executeLargeBatch, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeQuery, executeUpdate, executeUpdate, executeUpdate, executeUpdate, getConnection, getFetchDirection, getFetchSize, getGeneratedKeys, getLargeMaxRows, getLargeUpdateCount, getMaxFieldSize, getMaxRows, getMoreResults, getMoreResults, getQueryTimeout, getResultSet, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getUpdateCount, getWarnings, isClosed, isCloseOnCompletion, isPoolable, setCursorName, setFetchDirection, setFetchSize, setLargeMaxRows, setMaxFieldSize, setMaxRows, setPoolable, setQueryTimeout
static final int NEW
static final int IMPLICIT
static final int EXPLICIT
void clearDefines() throws java.sql.SQLException
After calling clearDefines
, you can either perform defines
by calling defineColumnType/defineColumnTypeChars
or let the
driver use the default defines for the table.
java.sql.SQLException
- if an error occursvoid defineColumnType(int columnIndex, int type) throws java.sql.SQLException
Defines the type you will use to retrieve data from a particular database table column.
For the JDBC-OCI driver and the server-side internal driver, if you decide to use defineColumnType you must declare the types of exactly all columns in the query. For the thin driver, it is not required to define all the columns.
See the JDBC Manual section on Data Interface for LOBs for a description of using defineColumnType to get LOB columns as streams. In some cases this is a large performance gain. The lob prefetch feature makes this less important, however. It is effective for basic lobs, but less so for SecureFile lobs.
BFILE, BLOB, CLOB, or NCLOB data can be read using the same streaming mechanism as for LONG RAW and LONG data. Use defineColumnType(nn, Types.LONGVARBINARY) for BLOB or BFILE, defineColumnType(nn,Types.LONGVARCHAR) for CLOB, or defineColumnType(nn,Types.LONGNVARCHAR) for NCLOB. This produces a stream on the data as if it were a LONG RAW or LONG column. Use defineColumnType( nn, Types.VARBINARY) or defineColumnType(nn, Types.VARCHAR) returns the data as if it were a RAW or VARCHAR2 column with the size limits of those types.
The following example illustrates the use of this feature in the PM sample schema:
// Ask for the column as a character stream: ((OracleStatement)stmt).defineColumnType(1, Types.LONGVARCHAR); ResultSet rset = stmt.executeQuery("select PRODUCT_TEXT from ONLINE_MEDIA"); while (rset.next() ) System.out.println(rset.getString(1));
All columns can be defined to their "natural" JDBC types; in most
cases, they can be defined to the Types.CHAR
or
Types.VARCHAR
typecode. You can also use the
OracleTypes
typecodes. The type can also be different from the
native type of the column. Appropriate conversions will be done. A
subsequent call to getObject()
for this column will return the
supplied type rather than the native type.
columnIndex
- index of column (first is 1)type
- type to be assigned to columnjava.sql.SQLException
- if an error occursdefineColumnType(int,int,int)
,
clearDefines
void defineColumnType(int columnIndex, int type, int lobPrefetchSize) throws java.sql.SQLException
Defines the type you will use to retrieve data from a particular database table column. See defineColumnType( int, int) for general information.
In previous releases the third parameter was used to control the buffer
sizes used with possible truncation of data. In the current release it is
used only to control the LOB prefetch size at the column level.
This setting overrides the default LOB prefetch size that is defined at the
connection or statement level. The lobPrefetchSize
argument represents
in this case the number of bytes to prefetch for a BLOB and chars for a CLOB and
the value must be >= 0 and the type must be set to OracleTypes.CLOB for a CLOB
column and OracleTypes.BLOB for a BLOB column.
columnIndex
- index of column (first is 1)type
- type to be assigned to columnlobPrefetchSize
- for lob column, size of prefetch bufferjava.sql.SQLException
#java.sql.Statement.setMaxFieldSize
void defineColumnType(int columnIndex, int type, int lobPrefetchSize, short formOfUse) throws java.sql.SQLException
Deprecated method, please use defineColumnType(int, int, int) with the type such as Types.NCHAR, Types.NVARCHAR, Types.NCLOB.
See defineColumnType( int, int) for general information.
The formOfUse parameter may take the value oracle.jdbc.OraclePreparedStatement.FORM_CHAR to specify that the data be in the database character set or oracle.jdbc.OraclePreparedStatement.FORM_NCHAR to specify that the data be in the national character set.
columnIndex
- index of column (first is 1)type
- type to be assigned to columnlobPrefetchSize
- for lob column, size of prefetch bufferformOfUse
- flag to select character set.java.sql.SQLException
void defineColumnTypeBytes(int columnIndex, int type, int lobPrefetchSize) throws java.sql.SQLException
columnIndex
- index of column (first is 1)type
- type to be assigned to columnlobPrefetchSize
- ignored except for lob columnsjava.sql.SQLException
- if an error occursdefineColumnType(int,int,int)
,
clearDefines
void defineColumnTypeChars(int columnIndex, int type, int lobPrefetchSize) throws java.sql.SQLException
columnIndex
- index of column (first is 1)type
- type to be assigned to columnlobPrefetchSize
- ignored except for lob columnsjava.sql.SQLException
- if an error occursdefineColumnType(int,int,int)
,
clearDefines
void defineColumnType(int columnIndex, int typeCode, java.lang.String typeName) throws java.sql.SQLException
Defines the type you will use to retrieve data from a particular database table column and specifies the column type name. This method should be used for structured object, object reference and array columns. See defineColumnType( int, int) for general information.
columnIndex
- index of column (first is 1)typeCode
- type code for this column.typeName
- specifies the fully-qualified name of the
type of the columnjava.sql.SQLException
- if an error occursdefineColumnType(int,int)
,
clearDefines
int getRowPrefetch()
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 this 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
OracleConnection.setDefaultRowPrefetch
method.
setRowPrefetch
,
OracleConnection.setDefaultRowPrefetch
void setRowPrefetch(int value) throws java.sql.SQLException
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.
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 whether the streaming columns are read or not.
Notes :
value
- the number of rows to prefetchjava.sql.SQLException
- if the argument value is <=0getRowPrefetch
,
OracleConnection.setDefaultRowPrefetch
int getLobPrefetchSize() throws java.sql.SQLException
oracle.jdbc.defaultLobPrefetchSize
connection
property or at the statement level through the setLobPrefetchSize(int)
method.
java.sql.SQLException
setLobPrefetchSize
void setLobPrefetchSize(int value) throws java.sql.SQLException
LOB prefetch is enabled by default (see the oracle.jdbc.defaultLobPrefetchSize
connection
property which default value is 4k bytes for BLOBs and 4k chars for CLOBs). The LOB prefetch
size can be set at the connection level through the property or at the statement level through
this method. The statement level setting overrides the setting at the connection level. This
setting can also be overridden at the column level through the defineColumnType
method
where the size represents the number of bytes (or chars for CLOB) to prefetch.
value
- must be >= -1. -1 disables the feature. 0 enables LOB prefetch of metadata
only (lob length and chunk size). Any value >=0 represents the number of bytes to be prefetched for
BLOB and the number of chars for CLOB.java.sql.SQLException
- if value < -1
getLobPrefetchSize
,
OracleConnection.DEFAULT_LOB_PREFETCH_SIZE
void closeWithKey(java.lang.String key) throws java.sql.SQLException
key
- A key to tag to the statement to be retrieved laterjava.sql.SQLException
- if a database access error occursint creationState()
boolean isNCHAR(int index) throws java.sql.SQLException
index
- the column indexjava.sql.SQLException
void setDatabaseChangeRegistration(DatabaseChangeRegistration registration) throws java.sql.SQLException
Any subsequent queries executed with this statement will be part of the given registration.
If you want this statement to no longer add queries to the registration, call this method again with a 'null' argument. Subsequent queries won't be part of the registration.
registration
- can be either a valid registration or 'null'.java.sql.SQLException
getRegisteredQueryId()
java.lang.String[] getRegisteredTableNames() throws java.sql.SQLException
java.sql.SQLException
long getRegisteredQueryId() throws java.sql.SQLException
java.sql.SQLException
setDatabaseChangeRegistration(oracle.jdbc.dcn.DatabaseChangeRegistration)
java.lang.String getSqlId() throws java.sql.SQLException
java.sql.SQLException
- if the SQL ID could not be retrieved.void closeOnCompletion() throws java.sql.SQLException
closeOnCompletion
in interface java.sql.Statement
java.sql.SQLException
- if this method is called on a closed Statementdefault java.lang.String enquoteLiteral(java.lang.String val) throws java.sql.SQLException
String
enclosed in single quotes. Any occurrence of a
single quote within the string will be replaced by two single quotes.
Examples of the conversion: Value Result Hello 'Hello' G'Day 'G''Day' 'G''Day' '''G''''Day''' I'''M 'I''''''M'
val
- a character stringjava.lang.NullPointerException
- if val is nulljava.sql.SQLException
- if val cannot be transformed into a SQL literaldefault java.lang.String enquoteNCharLiteral(java.lang.String val) throws java.sql.SQLException
String
enclosed in single quotes and prefixed with 'N'.
Any occurrence of a single quote within the string will be replaced by
two single quotes.
Examples of the conversion: Value Result Hello N'Hello' G'Day N'G''Day' N'G''Day' N'''G''''Day''' I'''M N'I''''''M'
val
- a character stringjava.lang.NullPointerException
- if val is nulljava.sql.SQLException
- if val cannot be transformed into a SQL literaldefault boolean isSimpleIdentifier(java.lang.String identifier) throws java.sql.SQLException
identifier
is a simple SQL identifier.identifier
- a SQL identifierjava.lang.NullPointerException
- if identifier is nulljava.sql.SQLException
- if the driver cannot verify that identifier is a
valid simple identifier or notdefault java.lang.String enquoteIdentifier(java.lang.String identifier, boolean alwaysQuote) throws java.sql.SQLException
identifier
is a simple SQL identifier:
alwaysQuote
is
false
alwaysQuote
is
true
identifier
is not a simple SQL identifier, identifier
will be
enclosed in double quotes if not already present. If the datasource does
not support double quotes for delimited identifiers, the
identifier should be enclosed by the string returned from
DatabaseMetaData#getIdentifierQuoteString
. If the datasource
does not support delimited identifiers, a
SQLFeatureNotSupportedException
should be thrown.
A SQLException
will be thrown if identifier
contains any
characters invalid in a delimited identifier or the identifier length is
invalid for the datasource.
identifier
- a SQL identifieralwaysQuote
- indicates if a simple SQL identifier should be
returned as a quoted identifierjava.sql.SQLException
- if identifier is not a valid identifierSQLFeatureNotSupportedException
- if the datasource does not support
delimited identifiersjava.lang.NullPointerException
- if identifier is nullvoid setEscapeProcessing(boolean enable) throws java.sql.SQLException
The Connection and DataSource property escapeProcessing may be used to change the default escape processing behavior. A value of true (the default) enables escape Processing for all Statement objects. A value of false disables escape processing for all Statement objects. The setEscapeProcessing method may be used to specify the escape processing behavior for an individual Statement object.
Alternatively, Oracle JDBC also allows disabling escape sequence processing within a statement. Anything, in a statement, appearing between {\ (2 characters) and \} (2 characters) will be excluded from escape processing and copied as-is by the driver. This is useful to escape something that may look like a JDBC syntax but is not. For example, MATCH_RECOGNIZE allows the use of a question mark for pattern matching:
String sql =
"SELECT DUMMY FROM DUAL MATCH_RECOGNIZE ( " +
"MEASURES match_number() as mno, classifier() as cls " +
"ALL ROWS PER MATCH " +
"PATTERN ( dup? ) " +
"DEFINE " +
" DUP AS DUMMY = prev(DUMMY) " +
")";
By default the driver would process the question mark as a JDBC parameter and would expect the user to provide
a value for it. To make sure the driver does not interpret the question mark as a JDBC parameter and allows
the SQL engine to process it correctly, it can be escaped with:
String sql =
"SELECT DUMMY FROM DUAL MATCH_RECOGNIZE ( " +
"MEASURES match_number() as mno, classifier() as cls" +
"ALL ROWS PER MATCH" +
"PATTERN ( dup{\\?\\} )" +
"DEFINE " +
" DUP AS DUMMY = prev(DUMMY) " +
")";
The string literal \} can be escaped within the escape sequence with \\}. This allows including \} within the escaped sequence without closing it.
String sql = "SELECT NAME FROM EMP WHERE HIREDATE = {d '2023-01-01'} or HIREDATE = {\\{d '2023-01-01' \\\\} } \\}";
The driver will process the first JDBC escape sequence and escape the second one until the end of the statement.
In this case, the statement sent to the SQL engine is:
SELECT NAME FROM EMP WHERE HIREDATE = TO_DATE('2023-01-01', 'YYYY-MM-DD') or HIREDATE = {d '2023-01-01' \} }
setEscapeProcessing
in interface java.sql.Statement
boolean
- - to enable or disable escape processing for this statement.java.sql.SQLException