org.garret.consus
Class TableIterator

java.lang.Object
  extended by org.garret.consus.TableIterator

public abstract class TableIterator
extends java.lang.Object

An Iterator through the table records (is equivalent to ResultSet for a single table select without condition, but is more efficient).


Constructor Summary
TableIterator()
           
 
Method Summary
abstract  boolean absolute(int row)
          Moves the cursor to the given row number in the resultset.
abstract  void afterLast()
          Moves the cursor to the end of the resultset, just after the last row.
abstract  void beforeFirst()
          Moves the cursor to the front of the resultset, just before the first row.
abstract  void close()
          Closes the iterator and releases all related resourses.
abstract  void deleteAllSelectedRows()
          Deletes all records in the table.
abstract  void deleteRow()
          Deletes the current row from the resultset and the underlying database.
abstract  boolean first()
          Moves the cursor to the first row in the resultset.
abstract  java.lang.Object get()
          Fetch the current table row as a Java object.
abstract  int getNumberOfRows()
          Get the number of rows in the table.
abstract  int getRow()
          Retrieves the current row number.
abstract  boolean isAfterLast()
          Indicates whether the cursor is after the last row in the resultset.
abstract  boolean isBeforeFirst()
          Indicates whether the cursor is before the first row in the resultset.
abstract  boolean isFirst()
          Indicates whether the cursor is on the first row of the resultset.
abstract  boolean isLast()
          Indicates whether the cursor is on the last row of the resultset.
abstract  boolean last()
          Moves the cursor to the last row in the resultset.
abstract  boolean next()
          Moves the cursor down one row from its current position.
abstract  boolean previous()
          Moves the cursor to the previous row in the result set.
abstract  boolean relative(int rows)
          Moves the cursor a relative number of rows, either positive or negative.
abstract  java.lang.Object selectByKey(java.lang.String keyName, java.lang.String keyValue)
          Select an object from the table using a unique key.
abstract  java.lang.Object selectByOid(long oid)
          Select an object from the table using an object identifier.
 java.lang.Object[] toArray()
          Returns an array of java.lang.Object objects, containing all the selected elements.
 java.lang.Object[] toArray(java.lang.Object[] a)
          Returns an array containing all of the selected elements.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TableIterator

public TableIterator()
Method Detail

absolute

public abstract boolean absolute(int row)
                          throws java.sql.SQLException

Moves the cursor to the given row number in the resultset.

If the row number is positive, the cursor moves to the given row number with respect to the beginning of the resultset. The first row is row 1, the second is row 2, and so on.

If the given row number is negative, the cursor moves to an absolute row position with respect to the end of the resultset. For example, calling absolute(-1) positions the cursor on the last row, absolute(-2) indicates the next-to-last row, and so on.

An attempt to position the cursor beyond the first or last row in the resultset leaves the cursor before or after the first or last row, respectively.

Note: Calling absolute(1) is the same as calling first(). Calling absolute(-1) is the same as calling last().

Returns:
true if the cursor is on the result set; false otherwise
Throws:
java.sql.SQLException - if a database access error occurs or row is 0, or result set type is TYPE_FORWARD_ONLY.

afterLast

public abstract void afterLast()
                        throws java.sql.SQLException

Moves the cursor to the end of the resultset, just after the last row. Has no effect if the resultset contains no rows.

Throws:
java.sql.SQLException - if a database access error occurs or the result set type is TYPE_FORWARD_ONLY

beforeFirst

public abstract void beforeFirst()
                          throws java.sql.SQLException

Moves the cursor to the front of the resultset, just before the first row. Has no effect if the resultset contains no rows.

Throws:
java.sql.SQLException - if a database access error occurs or the result set type is TYPE_FORWARD_ONLY

close

public abstract void close()
                    throws java.sql.SQLException
Closes the iterator and releases all related resourses.

Throws:
java.sql.SQLException

deleteAllSelectedRows

public abstract void deleteAllSelectedRows()
                                    throws java.sql.SQLException
Deletes all records in the table.

Throws:
java.sql.SQLException - if a database access error occurs or if called when on the insert row.

deleteRow

public abstract void deleteRow()
                        throws java.sql.SQLException
Deletes the current row from the resultset and the underlying database. Cannot be called when on the insert row.

Throws:
java.sql.SQLException - if a database access error occurs or if called when on the insert row.

first

public abstract boolean first()
                       throws java.sql.SQLException

Moves the cursor to the first row in the resultset.

Returns:
true if the cursor is on a valid row; false if there are no rows in the result set
Throws:
java.sql.SQLException - if a database access error occurs or the result set type is TYPE_FORWARD_ONLY

get

public abstract java.lang.Object get()
                              throws java.sql.SQLException
Fetch the current table row as a Java object.

Throws:
java.sql.SQLException

getNumberOfRows

public abstract int getNumberOfRows()
                             throws java.sql.SQLException
Get the number of rows in the table.

Returns:
number of rows in the table
Throws:
java.sql.SQLException

getRow

public abstract 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 a database access error occurs

isAfterLast

public abstract boolean isAfterLast()
                             throws java.sql.SQLException

Indicates whether the cursor is after the last row in the resultset.

Returns:
true if the cursor is after the last row, false otherwise. Returns false when the resultset contains no rows.
Throws:
java.sql.SQLException - if a database access error occurs

isBeforeFirst

public abstract boolean isBeforeFirst()
                               throws java.sql.SQLException

Indicates whether the cursor is before the first row in the resultset.

Returns:
true if the cursor is before the first row, false otherwise. Returns false when the resultset contains no rows.
Throws:
java.sql.SQLException - if a database access error occurs

isFirst

public abstract boolean isFirst()
                         throws java.sql.SQLException

Indicates whether the cursor is on the first row of the resultset.

Returns:
true if the cursor is on the first row, false otherwise.
Throws:
java.sql.SQLException - if a database access error occurs

isLast

public abstract boolean isLast()
                        throws java.sql.SQLException

Indicates whether the cursor is on the last row of the resultset.

Returns:
true if the cursor is on the last row, false otherwise.
Throws:
java.sql.SQLException - if a database access error occurs

last

public abstract boolean last()
                      throws java.sql.SQLException

Moves the cursor to the last row in the resultset.

Returns:
true if the cursor is on a valid row; false if there are no rows in the resultset
Throws:
java.sql.SQLException - if a database access error occurs or the result set type is TYPE_FORWARD_ONLY.

next

public abstract boolean next()
                      throws java.sql.SQLException
Moves the cursor down one row from its current position. A ResultSet cursor is initially positioned before the first row; the first call to the next, makes the first row the current row; the second call makes the second row the current row, and so on.

Returns:
true if the new current row is valid; false if there are no more rows
Throws:
java.sql.SQLException - if a database access error occurs

previous

public abstract boolean previous()
                          throws java.sql.SQLException

Moves the cursor to the previous row in the result set.

Note: previous() is not the same as relative(-1) because it makes sense to callprevious() when there is no current row.

Returns:
true if the cursor is on a valid row; false if it is off the result set
Throws:
java.sql.SQLException - if a database access error occurs or the result set type is TYPE_FORWARD_ONLY

relative

public abstract boolean relative(int rows)
                          throws java.sql.SQLException

Moves the cursor a relative number of rows, either positive or negative. Attempting to move beyond the first or last row in the result set positions the cursor before or after the the first or last row. Calling relative(0) is valid, but does not change the cursors position.

Note: Calling relative(1) is different from calling next() because it makes sense to call next() when there is no current row, for example, when the cursor is positioned before the first row or after the last row of the resultset.

Returns:
true if the cursor is on a row; false otherwise
Throws:
java.sql.SQLException - if a database access error occurs, there is no current row, or the result set type is TYPE_FORWARD_ONLY

selectByKey

public abstract java.lang.Object selectByKey(java.lang.String keyName,
                                             java.lang.String keyValue)
                                      throws java.sql.SQLException
Select an object from the table using a unique key.

Parameters:
keyName - table column with a unique key
keyValue - value of the key to look for
Returns:
object with specified value of the key or null otherwise
Throws:
ConsusRuntimeException - when there is no such column in the table or it is not indexed; ConsusNotUniqueException when the key is not unique
java.sql.SQLException

selectByOid

public abstract java.lang.Object selectByOid(long oid)
                                      throws java.sql.SQLException
Select an object from the table using an object identifier.

Parameters:
oid - object identifier
Returns:
object with the specified identifier
Throws:
java.sql.SQLException

toArray

public java.lang.Object[] toArray()
                           throws java.sql.SQLException
Returns an array of java.lang.Object objects, containing all the selected elements.

Returns:
an array containing all the selected records
Throws:
java.sql.SQLException

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)
                           throws java.sql.SQLException
Returns an array containing all of the selected elements. The runtime type of the returned array is that of the specified array. If the number of selected elements is not greater then specified array length, then they are returned. Otherwise, a new array is allocated with the runtime type of the specified array and a length equal to the number of selected elements.

If the list fits into the specified array with room to spare (i.e. the array has more elements than the selection), the element in the array immediately following the end of the collection is set to null.

Returns:
an array containing all of the selected records
Throws:
java.sql.SQLException