sqlj.runtime
Interface ResultSetIterator

All Known Subinterfaces:
NamedIterator, PositionedIterator
All Known Implementing Classes:
ResultSetIterImpl

public abstract interface ResultSetIterator

An interface that defines the shared functionality of those objects used to iterate over the contents of a result set.


Field Summary
static int ASENSITIVE
          Constant used by the "sensitivity" field, indicating that the iterator is defined to have an asensitive cursor.
static int FETCH_FORWARD
          The rows in an iterator object will be processed in a forward direction; first-to-last.
static int FETCH_REVERSE
          The rows in an iterator object will be processed in a reverse direction; last-to-first.
static int FETCH_UNKNOWN
          The order in which rows in an iterator object will be processed is unknown.
static int INSENSITIVE
          Constant used by the "sensitivity" field, indicating that the iterator is defined to have an insensitive cursor.
static int SENSITIVE
          Constant used by the "sensitivity" field, indicating that the iterator is defined to have a sensitive cursor.
 
Method Summary
 void clearWarnings()
          After this call getWarnings returns null until a new warning is reported for this iterator.
 void close()
          Closes the iterator object, releasing any underlying resources.
 int getFetchSize()
          Retrieves the number of rows that is the current fetch size for this iterator object.
 java.sql.ResultSet getResultSet()
          Returns the JDBC result set associated with this iterator.
 int getSensitivity()
          Returns the sensitivity of this iterator object.
 java.sql.SQLWarning getWarnings()
          The first warning reported by calls on this iterator is returned.
 boolean isClosed()
          check if the iterator has been closed or not.
 boolean next()
          Advances the iterator to the next row.
 void setFetchSize(int rows)
          Gives the SQLJ runtime a hint as to the number of rows that should be fetched when more rows are needed from this iterator object.
 

Field Detail

INSENSITIVE

public static final int INSENSITIVE
Constant used by the "sensitivity" field, indicating that the iterator is defined to have an insensitive cursor.

SENSITIVE

public static final int SENSITIVE
Constant used by the "sensitivity" field, indicating that the iterator is defined to have a sensitive cursor.

ASENSITIVE

public static final int ASENSITIVE
Constant used by the "sensitivity" field, indicating that the iterator is defined to have an asensitive cursor.

FETCH_FORWARD

public static final int FETCH_FORWARD
The rows in an iterator object will be processed in a forward direction; first-to-last.

FETCH_REVERSE

public static final int FETCH_REVERSE
The rows in an iterator object will be processed in a reverse direction; last-to-first.

FETCH_UNKNOWN

public static final int FETCH_UNKNOWN
The order in which rows in an iterator object will be processed is unknown.
Method Detail

close

public void close()
           throws java.sql.SQLException
Closes the iterator object, releasing any underlying resources. It is recommended that iterators be explicitely closed as soon as they are no longer needed to allow for the immediate release of resources that are no longer needed.

Note: If it is not already closed, an iterator is automatically closed when it is garbage collected.

Throws:
java.sql.SQLException - If there is a problem closing the iterator.
See Also:
isClosed()

isClosed

public boolean isClosed()
                 throws java.sql.SQLException
check if the iterator has been closed or not.
Returns:
true if the close method on this iterator has been called, false otherwise.
Throws:
java.sql.SQLException - if an error occurs determining the close-status of the iterator.
See Also:
close()

next

public boolean next()
             throws java.sql.SQLException
Advances the iterator to the next row. At the begining the iterator is positioned before the first row.

Note: A FETCH..INTO statement performs an implicit next call on the iterator passed.

Returns:
true if there was a next row in the iterator, false otherwise.
Throws:
java.sql.SQLException - If an exception occurs while changing the position of the iterator.

getResultSet

public java.sql.ResultSet getResultSet()
                                throws java.sql.SQLException
Returns the JDBC result set associated with this iterator. The result set produced must have normal JDBC functionality, as defined in the JDBC specification (in particular, SQL NULL values fetched with primitive accessor methods will not raise a SQLNullException). This method is provided to facilitate interoperablity with JDBC.

Notes:

Returns:
a JDBC result set for this iterator.
Throws:
java.sql.SQLException - if no result set is available for this iterator.

getWarnings

public java.sql.SQLWarning getWarnings()
                                throws java.sql.SQLException
The first warning reported by calls on this iterator is returned. Subsequent iterator warings will be chained to this SQLWarning.

The warning chain is automatically cleared each time a new role is read.

Note: This warning cheain only covers warnings caused by iterator methods. Any warning caused by statement execution (such as fetching OUT parameters) will be chained on the ExecutionContext object.

Returns:
the first SQLWarning or null it there are no errors
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 iterator.
Throws:
java.sql.SQLException - if a database-access error occurs.

getFetchSize

public int getFetchSize()
                 throws java.sql.SQLException
Retrieves the number of rows that is the current fetch size for this iterator object. If this iterator object has not set a fetch size by calling the method setFetchSize, or has set a fetch size of zero, then the value returned is implementation-dependent.
Returns:
the default fetch size for the iterator object.
Throws:
java.sql.SQLException - if a database access error occurs.

setFetchSize

public void setFetchSize(int rows)
                  throws java.sql.SQLException
Gives the SQLJ runtime a hint as to the number of rows that should be fetched when more rows are needed from this iterator object. If the value specified is zero, then the the runtime is free to choose an implementation-dependent fetch size.
Parameters:
rows - the default fetch size for result sets generated from this iterator object.
Throws:
java.sql.SQLException - if a database access error occurs, or the condition 0 <= rows <= ECtxt.getMaxRows() is not satisfied, where ECtxt is the ExecutionContext object that was used to create this iterator object.

getSensitivity

public int getSensitivity()
                   throws java.sql.SQLException
Returns the sensitivity of this iterator object. The type is determined by the declaration of the iterator object and by the SQLJ runtime implementation that created the iterator object.
Returns:
  • ResultSetIterator.SENSITIVE - if this iterator object was declared with the <predefined iterator with keyword> sensitivity and a corresponding <with value> SENSITIVE, and the SQLJ runtime that created this iterator object supports sensitive iterators.
  • ResultSetIterator.INSENSITIVE - if this iterator object object was declared with the <predefined iterator with keyword> sensitivity and a corresponding <with value> INSENSITIVE, and the SQLJ runtime that created this iterator object supports insensitive iterators.
  • ResultSetIterator.ASENSITIVE - if this iterator object was declared with the <predefined iterator with keyword> sensitivity and a corresponding <with value> ASENSITIVE.
  • An implementation-dependent value otherwise.
Throws:
java.sql.SQLException - if a database access error occurs