sqlj.runtime
Interface ResultSetIterator

All Known Subinterfaces:

NamedIterator, PositionedIterator

public 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 Constant to indicate that the rows in an iterator object will be processed in a forward direction first-to-last.
static int	FETCH_REVERSE Constant to indicate that the rows in an iterator object will be processed in a forward direction first-to-last.
static int	FETCH_UNKNOWN Constant to indicate that the rows in an iterator object will be processed in an unknown direction.
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() This method is not supported in Open SQL / SQLJ. Retreives 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	getRow() Retrieves the current row number.
int	getSensitivity() Retrieves the sensitivity of this iterator object.
java.sql.SQLWarning	getWarnings() The first warning reported by calls on this iterator is returned.
boolean	isClosed()
boolean	next() Advances the iterator to the next row.
void	setFetchSize(int rows) This method is not supported in Open SQL / SQLJ. 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

ASENSITIVE

public static final int ASENSITIVE

Constant used by the "sensitivity" field, indicating that the iterator is defined to have an asensitive cursor. This means that the sensitivity is unknown.

INSENSITIVE

public static final int INSENSITIVE

Constant used by the "sensitivity" field, indicating that the iterator is defined to have an insensitive cursor. This means that result set will not see changes made by others.

SENSITIVE

public static final int SENSITIVE

Constant used by the "sensitivity" field, indicating that the iterator is defined to have a sensitive cursor. This means that the result set will see changes made by others.

FETCH_FORWARD

public static final int FETCH_FORWARD

Constant to indicate that the rows in an iterator object will be processed in a forward direction first-to-last.

FETCH_REVERSE

public static final int FETCH_REVERSE

Constant to indicate that the rows in an iterator object will be processed in a forward direction first-to-last.

FETCH_UNKNOWN

public static final int FETCH_UNKNOWN

Constant to indicate that the rows in an iterator object will be processed in an unknown direction.

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: An iterator is not automatically closed when it is garbage collected. Allways close an iterator in the finally block.

Throws:

java.sql.SQLException - If there is a problem closing the iterator.

See Also:

isClosed()

isClosed

public boolean isClosed()
                 throws java.sql.SQLException

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:

• This method is supported in Open SQL / SQLJ.
• Support for this method is implementor defined and not part of Core SQLJ. An SQLException will be thrown if this method is not supported.
• If an implementor supports this method, then any synchronization between the iterator and the produced result set is implementor-defined.
• For maximum portability this method should be invoked before the first next method invocation on the iterator. Once the result set has been produced, all operations to fetch data should be through the result set.

Returns:

a JDBC result set for this iterator.

Throws:

java.sql.SQLException - if no result set is available for this iterator.

See Also:

ResultSet

getRow

public int getRow()
           throws java.sql.SQLException

Retrieves the current row number. The first row is number 1, the second number 2, and so on.

Returns:

the current row number; 0 if there is no current row

Throws:

java.sql.SQLException - if there is no JDBC result set associated with this iterator.

getFetchSize

public int getFetchSize()
                 throws java.sql.SQLException

This method is not supported in Open SQL / SQLJ. Retreives 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 0, then the value returned is implementation-defined.

Returns:

the current fetch size forthe iterator object.

Throws:

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

setFetchSize

public void setFetchSize(int rows)
                  throws java.sql.SQLException

This method is not supported in Open SQL / SQLJ. 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:

- - 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.

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 chain 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.

getSensitivity

public int getSensitivity()
                   throws java.sql.SQLException

Retrieves the sensitivity of this iterator object. The sensitivity is determined by the iterator declaration clause and by the SQLJ runtime implementation that created the iterator object.

Returns:

Case:

• 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, then ResultSetIterator.SENSITIVE.
• If this iterator 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, then ResultSetIterator.INSENSITIVE.
• If this iterator object was declared with the predefined iterator with keyword sensitivity and a corresponding with value ASENSITIVE, then ResultSetIterator.ASENSITIVE.
• Otherwise, an implementation-dependent value.

Note: In Open SQL / SQLJ, this method is not supported.