org.apache.derby.iapi.sql
Interface ResultSet

All Known Subinterfaces:
CursorResultSet, NoPutResultSet, TargetResultSet
All Known Implementing Classes:
BasicNoPutResultSetImpl, BulkTableScanResultSet, CurrentOfResultSet, DependentResultSet, GroupedAggregateResultSet, HashScanResultSet, HashTableResultSet, IndexRowToBaseRowResultSet, InsertResultSet, JoinResultSet, MaterializedResultSet, NormalizeResultSet, NoRowsResultSetImpl, ProjectRestrictResultSet, RowResultSet, ScalarAggregateResultSet, ScrollInsensitiveResultSet, SortResultSet, TableScanResultSet, TemporaryRowHolderResultSet, UnionResultSet, VTIResultSet

public interface ResultSet

The ResultSet interface provides a method to tell whether a statement returns rows, and if so, a method to get the rows. It also provides a method to get metadata about the contents of the rows. It also provide a method to accept rows as input.

There is no single implementation of the ResultSet interface. Instead, the various support operations involved in executing statements implement this interface.

Although ExecRow is used on the interface, it is not available to users of the API. They should use Row, the exposed super-interface of ExecRow. <>

Valid transitions:

Author:
Jeff Lichtman

Field Summary
static int CURRENT_RESULTSET_ONLY
           
static int ENTIRE_RESULTSET_TREE
           
static int ISAFTERLAST
           
static int ISBEFOREFIRST
           
static int ISFIRST
           
static int ISLAST
           
 
Method Summary
 boolean checkRowPosition(int isType)
          Determine if the result set is at one of the positions according to the constants above (ISBEFOREFIRST etc).
 void cleanUp()
          Tells the system to clean up on an error.
 void close()
          Tells the system that there will be no more calls to getNextRow() (until the next open() call), so it can free up the resources associated with the ResultSet.
 void finish()
          Tells the system that there will be no more access to any database information via this result set; in particular, no more calls to open().
 ExecRow getAbsoluteRow(int row)
          Returns the row at the absolute position from the query, and returns NULL when there is no such position.
 ResultSet getAutoGeneratedKeysResultset()
          ResultSet for rowss inserted into the table (contains auto-generated keys columns only)
 java.sql.Timestamp getBeginExecutionTimestamp()
          Get the Timestamp for the beginning of execution.
 java.lang.String getCursorName()
          Returns the name of the cursor, if this is cursor statement of some type (declare, open, fetch, positioned update, positioned delete, close).
 java.sql.Timestamp getEndExecutionTimestamp()
          Get the Timestamp for the end of execution.
 long getExecuteTime()
          Get the execution time in milliseconds.
 ExecRow getFirstRow()
          Returns the first row from the query, and returns NULL when there are no rows.
 ExecRow getLastRow()
          Returns the last row from the query, and returns NULL when there are no rows.
 ExecRow getNextRow()
          Returns the next row from the query, and returns NULL when there are no more rows.
 ExecRow getPreviousRow()
          Returns the previous row from the query, and returns NULL when there are no more previous rows.
 ExecRow getRelativeRow(int row)
          Returns the row at the relative position from the current cursor position, and returns NULL when there is no such position.
 ResultDescription getResultDescription()
          Returns a ResultDescription object, which describes the results of the statement this ResultSet is in.
 int getRowNumber()
          Returns the row number of the current row.
 NoPutResultSet[] getSubqueryTrackingArray(int numSubqueries)
          Get the subquery ResultSet tracking array from the top ResultSet.
 long getTimeSpent(int type)
          Return the total amount of time spent in this ResultSet
 java.sql.SQLWarning getWarnings()
          Return the set of warnings generated during the execution of this result set.
 boolean isClosed()
          Find out if the ResultSet is closed or not.
 int modifiedRowCount()
          Returns the number of rows affected by the statement.
 void open()
          Needs to be called before the result set will do anything.
 boolean returnsRows()
          Returns TRUE if the statement returns rows (i.e. is a SELECT or FETCH statement), FALSE if it returns no rows.
 ExecRow setAfterLastRow()
          Sets the current position to after the last row and returns NULL because there is no current row.
 ExecRow setBeforeFirstRow()
          Sets the current position to before the first row and returns NULL because there is no current row.
 

Field Detail

CURRENT_RESULTSET_ONLY

public static final int CURRENT_RESULTSET_ONLY
See Also:
Constant Field Values

ENTIRE_RESULTSET_TREE

public static final int ENTIRE_RESULTSET_TREE
See Also:
Constant Field Values

ISBEFOREFIRST

public static final int ISBEFOREFIRST
See Also:
Constant Field Values

ISFIRST

public static final int ISFIRST
See Also:
Constant Field Values

ISLAST

public static final int ISLAST
See Also:
Constant Field Values

ISAFTERLAST

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

returnsRows

public boolean returnsRows()
Returns TRUE if the statement returns rows (i.e. is a SELECT or FETCH statement), FALSE if it returns no rows.

Returns:
TRUE if the statement returns rows, FALSE if not.

modifiedRowCount

public int modifiedRowCount()
Returns the number of rows affected by the statement. Only valid of returnsRows() returns false. For other DML statements, it returns the number of rows modified by the statement. For statements that do not affect rows (like DDL statements), it returns zero.

Returns:
The number of rows affect by the statement, so far.

getResultDescription

public ResultDescription getResultDescription()
Returns a ResultDescription object, which describes the results of the statement this ResultSet is in. This will *not* be a description of this particular ResultSet, if this is not the outermost ResultSet.

Returns:
A ResultDescription describing the results of the statement.

open

public void open()
          throws StandardException
Needs to be called before the result set will do anything. Need to call before getNextRow(), or for a result set that doesn't return rows, this is the call that will cause all the work to be done.

Returns:
Nothing
Throws:
StandardException - Thrown on failure

getAbsoluteRow

public ExecRow getAbsoluteRow(int row)
                       throws StandardException
Returns the row at the absolute position from the query, and returns NULL when there is no such position. (Negative position means from the end of the result set.) Moving the cursor to an invalid position leaves the cursor positioned either before the first row (negative position) or after the last row (positive position). NOTE: An exception will be thrown on 0.

Parameters:
row - The position.
Returns:
The row at the absolute position, or NULL if no such position.
Throws:
StandardException - Thrown on failure
See Also:
Row

getRelativeRow

public ExecRow getRelativeRow(int row)
                       throws StandardException
Returns the row at the relative position from the current cursor position, and returns NULL when there is no such position. (Negative position means toward the beginning of the result set.) Moving the cursor to an invalid position leaves the cursor positioned either before the first row (negative position) or after the last row (positive position). NOTE: 0 is valid. NOTE: An exception is thrown if the cursor is not currently positioned on a row.

Parameters:
row - The position.
Returns:
The row at the relative position, or NULL if no such position.
Throws:
StandardException - Thrown on failure
See Also:
Row

setBeforeFirstRow

public ExecRow setBeforeFirstRow()
                          throws StandardException
Sets the current position to before the first row and returns NULL because there is no current row.

Returns:
NULL.
Throws:
StandardException - Thrown on failure
See Also:
Row

getFirstRow

public ExecRow getFirstRow()
                    throws StandardException
Returns the first row from the query, and returns NULL when there are no rows.

Returns:
The first row, or NULL if no rows.
Throws:
StandardException - Thrown on failure
See Also:
Row

getNextRow

public ExecRow getNextRow()
                   throws StandardException
Returns the next row from the query, and returns NULL when there are no more rows.

Returns:
The next row, or NULL if no more rows.
Throws:
StandardException - Thrown on failure
See Also:
Row

getPreviousRow

public ExecRow getPreviousRow()
                       throws StandardException
Returns the previous row from the query, and returns NULL when there are no more previous rows.

Returns:
The previous row, or NULL if no more previous rows.
Throws:
StandardException - Thrown on failure
See Also:
Row

getLastRow

public ExecRow getLastRow()
                   throws StandardException
Returns the last row from the query, and returns NULL when there are no rows.

Returns:
The last row, or NULL if no rows.
Throws:
StandardException - Thrown on failure
See Also:
Row

setAfterLastRow

public ExecRow setAfterLastRow()
                        throws StandardException
Sets the current position to after the last row and returns NULL because there is no current row.

Returns:
NULL.
Throws:
StandardException - Thrown on failure
See Also:
Row

checkRowPosition

public boolean checkRowPosition(int isType)
                         throws StandardException
Determine if the result set is at one of the positions according to the constants above (ISBEFOREFIRST etc). Only valid and called for scrollable cursors.

Returns:
true if at the requested position.
Throws:
StandardException - Thrown on error.

getRowNumber

public int getRowNumber()
Returns the row number of the current row. Row numbers start from 1 and go to 'n'. Corresponds to row numbering used to position current row in the result set (as per JDBC). Only valid and called for scrollable cursors.

Returns:
the row number, or 0 if not on a row

close

public void close()
           throws StandardException
Tells the system that there will be no more calls to getNextRow() (until the next open() call), so it can free up the resources associated with the ResultSet.

Returns:
Nothing
Throws:
StandardException - Thrown on error.

cleanUp

public void cleanUp()
             throws StandardException
Tells the system to clean up on an error.

Returns:
Nothing
Throws:
StandardException - Thrown on error.

isClosed

public boolean isClosed()
Find out if the ResultSet is closed or not. Will report true for result sets that do not return rows.

Returns:
true if the ResultSet has been closed.

finish

public void finish()
            throws StandardException
Tells the system that there will be no more access to any database information via this result set; in particular, no more calls to open(). Will close the result set if it is not already closed.

Returns:
Nothing
Throws:
StandardException - on error

getExecuteTime

public long getExecuteTime()
Get the execution time in milliseconds.

Returns:
long The execution time in milliseconds.

getBeginExecutionTimestamp

public java.sql.Timestamp getBeginExecutionTimestamp()
Get the Timestamp for the beginning of execution.

Returns:
Timestamp The Timestamp for the beginning of execution.

getEndExecutionTimestamp

public java.sql.Timestamp getEndExecutionTimestamp()
Get the Timestamp for the end of execution.

Returns:
Timestamp The Timestamp for the end of execution.

getTimeSpent

public long getTimeSpent(int type)
Return the total amount of time spent in this ResultSet

Parameters:
type - CURRENT_RESULTSET_ONLY - time spent only in this ResultSet ENTIRE_RESULTSET_TREE - time spent in this ResultSet and below.
Returns:
long The total amount of time spent (in milliseconds).

getSubqueryTrackingArray

public NoPutResultSet[] getSubqueryTrackingArray(int numSubqueries)
Get the subquery ResultSet tracking array from the top ResultSet. (Used for tracking open subqueries when closing down on an error.)

Parameters:
numSubqueries - The size of the array (For allocation on demand.)
Returns:
NoPutResultSet[] Array of NoPutResultSets for subqueries.

getAutoGeneratedKeysResultset

public ResultSet getAutoGeneratedKeysResultset()
ResultSet for rowss inserted into the table (contains auto-generated keys columns only)

Returns:
NoPutResultSet NoPutResultSets for rows inserted into the table.

getCursorName

public java.lang.String getCursorName()
Returns the name of the cursor, if this is cursor statement of some type (declare, open, fetch, positioned update, positioned delete, close).

Returns:
A String with the name of the cursor, if any. Returns NULL if this is not a cursor statement.

getWarnings

public java.sql.SQLWarning getWarnings()
Return the set of warnings generated during the execution of this result set. The warnings are cleared once this call returns.



Apache Derby V10.0 Engine Documentation - Copyright © 1997,2004 The Apache Software Foundation or its licensors, as applicable.