: Interface ResultSetIterator

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

sqlj.runtime
Interface ResultSetIterator

All Known Subinterfaces:: NamedIterator, PositionedIterator

All Known Implementing Classes:: ResultSetIterImpl

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

boolean endFetch()
          Returns true iff the iterator is not positioned on a row.

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()

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.

endFetch

public boolean endFetch()
                 throws java.sql.SQLException

Returns true iff the iterator is not positioned on a row. This method is used to determine the success of a FETCH..INTO statement; it returns true if the last attempt to fetch a row failed, false if the last attempt was successful. Rows are attempted to be fetched when the next method is called (which is called implicitely during the execution of a FETCH..INTO statement). Note: If next has not yet been called, this method returns true;

A common usage of this method is as follows:

while (true) {
 #sql { FETCH :c INTO ... };
 if (c.endFetch()) break;
 ...
}

Throws:: java.sql.SQLException - if a databse access error occurs
See Also:: next()

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:

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.

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