oracle.ifs.server.sql
Class IfsStatement

java.lang.Object
  |
  +--oracle.ifs.server.sql.IfsStatement

Direct Known Subclasses:

IfsPreparedStatement

public class IfsStatement

extends java.lang.Object

An IfsStatement object is used for executing a static SQL statement and obtaining the results produced by it.

Only one ResultSet per IfsStatement can be open at any point in time. Therefore, if the reading of one ResultSet is interleaved with the reading of another, each must have been generated by different Statements. All statement execute methods implicitly close a statment's current ResultSet if an open one exists.

See Also:

IfsConnection.createStatement()

Constructor Summary

IfsStatement(java.sql.Statement stmt, IfsConnection iconn)
Constructs an IfsStatement.

Method Summary

void	cancel() Cancel can be used by one thread to cancel an Ifstatement that is being executed by another thread.
void	clearWarnings() After this call, getWarnings returns null until a new warning is reported for this IfsStatement.
void	close() In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.
void	dispose() Dispose and close the IfsStatement.
boolean	execute(java.lang.String sql) Execute a SQL statement that may return multiple results.
java.sql.ResultSet	executeQuery(java.lang.String sql) Execute a SQL statement that returns a single ResultSet.
int	executeUpdate(java.lang.String sql) Execute a SQL INSERT, UPDATE or DELETE statement.
int	getMaxFieldSize() The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
int	getMaxRows() The maxRows limit is the maximum number of rows that a ResultSet can contain.
boolean	getMoreResults() Moves to an IfsStatement's next result.
int	getQueryTimeout() The queryTimeout limit is the number of seconds the driver will wait for an IfsStatement to execute.
java.sql.ResultSet	getResultSet() Returns the current result as a ResultSet.
S_LibrarySession	getSession() Return the session that acquired this statement.
int	getUpdateCount() Returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned.
java.sql.SQLWarning	getWarnings() The first warning reported by calls on this IfsStatement is returned.
void	setCursorName(java.lang.String name) Defines the SQL cursor name that will be used by subsequent Statement execute methods.
void	setEscapeProcessing(boolean enable) If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
void	setMaxFieldSize(int max) The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields.
void	setMaxRows(int max) The maxRows limit is set to limit the number of rows that any ResultSet can contain.
void	setQueryTimeout(int seconds) The queryTimeout limit is the number of seconds the driver will wait for an IfsStatement to execute.

Constructor Detail

IfsStatement

public IfsStatement(java.sql.Statement stmt,
                    IfsConnection iconn)

Constructs an IfsStatement. IfsConnection.createStatement() should be used to create the IfsStatement in most cases.

Parameters:

stmt - java.sql.Statement instance

iconn - iFS Jdbc connection instance

Method Detail

getSession

public S_LibrarySession getSession()

Return the session that acquired this statement.

Returns:

the session

executeQuery

public java.sql.ResultSet executeQuery(java.lang.String sql)
                                throws java.sql.SQLException

Execute a SQL statement that returns a single ResultSet.

Parameters:

sql - typically this is a static SQL SELECT statement

Returns:

a ResultSet that contains the data produced by the query; never null

Throws:

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

executeUpdate

public int executeUpdate(java.lang.String sql)
                  throws java.sql.SQLException

Execute a SQL INSERT, UPDATE or DELETE statement. Although SQL DDL statements can be executed, it is not advised since doing so can cause the iFS repository to be non-functional or irreparable.

Parameters:

sql - a SQL INSERT, UPDATE or DELETE statement or a SQL statement that returns nothing

Returns:

either the row count for INSERT, UPDATE or DELETE or 0 for SQL statements that return nothing

Throws:

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

close

public void close()
           throws java.sql.SQLException

In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

Note: A Statement is automatically closed when it is garbage collected. When a Statement is closed, its current ResultSet, if one exists, is also closed.

Throws:

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

getMaxFieldSize

public int getMaxFieldSize()
                    throws java.sql.SQLException

The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data is silently discarded.

Returns:

the current max column size limit; zero means unlimited

Throws:

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

setMaxFieldSize

public void setMaxFieldSize(int max)
                     throws java.sql.SQLException

The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.

Parameters:

max - the new max column size limit; zero means unlimited

Throws:

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

getMaxRows

public int getMaxRows()
               throws java.sql.SQLException

The maxRows limit is the maximum number of rows that a ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.

Returns:

the current max row limit; zero means unlimited

Throws:

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

setMaxRows

public void setMaxRows(int max)
                throws java.sql.SQLException

The maxRows limit is set to limit the number of rows that any ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.

Parameters:

max - the new max rows limit; zero means unlimited

Throws:

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

setEscapeProcessing

public void setEscapeProcessing(boolean enable)
                         throws java.sql.SQLException

If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database. Note: Since prepared statements have usually been parsed prior to making this call, disabling escape processing for prepared statements will like have no affect.

Parameters:

enable - true to enable; false to disable

Throws:

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

getQueryTimeout

public int getQueryTimeout()
                    throws java.sql.SQLException

The queryTimeout limit is the number of seconds the driver will wait for an IfsStatement to execute. If the limit is exceeded, a SQLException is thrown.

Returns:

the current query timeout limit in seconds; zero means unlimited

Throws:

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

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws java.sql.SQLException

The queryTimeout limit is the number of seconds the driver will wait for an IfsStatement to execute. If the limit is exceeded, a SQLException is thrown.

Parameters:

seconds - the new query timeout limit in seconds; zero means unlimited

Throws:

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

cancel

public void cancel()
            throws java.sql.SQLException

Cancel can be used by one thread to cancel an Ifstatement that is being executed by another thread. Note: NT does not support out-of-band breaks, therefore cancel() is unavailable for NT.

Throws:

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

getWarnings

public java.sql.SQLWarning getWarnings()
                                throws java.sql.SQLException

The first warning reported by calls on this IfsStatement is returned. An IfsStatement's execute methods clear its SQLWarning chain. Subsequent IfsStatement warnings will be chained to this SQLWarning.

The warning chain is automatically cleared each time a statement is (re)executed.

Note: If you are processing a ResultSet then any warnings associated with ResultSet reads will be chained on the ResultSet object.

Returns:

the first SQLWarning or null

Throws:

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

clearWarnings

public void clearWarnings()
                   throws java.sql.SQLException

After this call, getWarnings returns null until a new warning is reported for this IfsStatement.

Throws:

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

setCursorName

public void setCursorName(java.lang.String name)
                   throws java.sql.SQLException

Defines the SQL cursor name that will be used by subsequent Statement execute methods. This name can then be used in SQL positioned update/delete statements to identify the current row in the ResultSet generated by this statement. If the database doesn't support positioned update/delete, this method is a noop.

Note: By definition, positioned update/delete execution must be done by a different Statement than the one which generated the ResultSet being used for positioning. Also, cursor names must be unique within a Connection.

Parameters:

name - the new cursor name.

Throws:

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

execute

public boolean execute(java.lang.String sql)
                throws java.sql.SQLException

Execute a SQL statement that may return multiple results. Under some (uncommon) situations a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this, unless you're executing a stored procedure that you know may return multiple results, or unless you're dynamically executing an unknown SQL string. The "execute", "getMoreResults", "getResultSet" and "getUpdateCount" methods let you navigate through multiple results. The "execute" method executes a SQL statement and indicates the form of the first result. You can then use getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s).

Parameters:

sql - any SQL statement

Returns:

true if the next result is a ResultSet; false if it is an update count or there are no more results

Throws:

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

See Also:

getResultSet(), getUpdateCount(), getMoreResults()

getResultSet

public java.sql.ResultSet getResultSet()
                                throws java.sql.SQLException

Returns the current result as a ResultSet. It should only be called once per result.

Returns:

the current result as a ResultSet; null if the result is an update count or there are no more results

Throws:

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

See Also:

execute(java.lang.String)

getUpdateCount

public int getUpdateCount()
                   throws java.sql.SQLException

Returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned. It should only be called once per result.

Returns:

the current result as an update count; -1 if it is a ResultSet or there are no more results

Throws:

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

See Also:

execute(java.lang.String)

getMoreResults

public boolean getMoreResults()
                       throws java.sql.SQLException

Moves to an IfsStatement's next result. It returns true if this result is a ResultSet. getMoreResults also implicitly closes any current ResultSet obtained with getResultSet. There are no more results when (!getMoreResults() && (getUpdateCount() == -1)

Returns:

true if the next result is a ResultSet; false if it is an update count or there are no more results

Throws:

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

See Also:

execute(java.lang.String)

dispose

public void dispose()

Dispose and close the IfsStatement. This closes the statement. If the close fails, catch and do not re-throw the SQLException.