com.holub.database
Interface Cursor


public interface Cursor

The Cursor provides you with a way of examining a Table, both the ones that you create and the ones that are created as a result of a select or join operation. This is an "updateable" cursor, so you can modify columns or delete rows via the cursor without problems. (Updates and deletes done through the cursor are handled properly with respect to the transactioning system, so they can be committed or rolled back.)

The class is not thread safe, however. It's a serious error for a thread to be modifying a table, either via a Cursor or directly, while another thread is examining or modifying the same table.

Modifications Since Publication of Holub on Patterns:

9/24/02 Added a few methods to make it possible to get column names for the JDBC ResultSetMetaData class.

©2004 Allen I. Holub. All rights reserved.

This code may be used freely by yourself with the following restrictions:

  1. Your splash screen, about box, or equivalent, must include Allen Holub's name, copyright, and URL. For example:

    This program contains Allen Holub's SQL package.
    (c) 2005 Allen I. Holub. All Rights Reserved.
    http://www.holub.com


    If your program does not run interactively, then the foregoing notice must appear in your documentation.
  2. You may not redistribute (or mirror) the source code.
  3. You must report any bugs that you find to me. Use the form at http://www.holub.com/company/contact.html or send email.
  4. The software is supplied as is. Neither Allen Holub nor Holub Associates are responsible for any bugs (or any problems caused by bugs, including lost productivity or data) in any of this code.

Method Summary
 boolean advance()
          Advances to the next row, or if this iterator has never been used, advances to the first row.
 Object column(String columnName)
          Return the contents of the requested column of the current row.
 int columnCount()
          Return the number of columns in the table that we're traversing.
 String columnName(int index)
          Return the name of the column at the indicated index.
 Iterator columns()
          Return a java.util.Iterator across all the columns in the current row.
 void delete()
          Delete the row at the current cursor position.
 boolean isTraversing(Table t)
          Return true if the iterator is traversing the indicated table.
 String tableName()
          Metadata method required by JDBC wrapper--Return the name of the table across which we're iterating.
 Object update(String columnName, Object newValue)
          Replace the value of the indicated column of the current row with the indicated new value.
 

Method Detail

tableName

String tableName()
Metadata method required by JDBC wrapper--Return the name of the table across which we're iterating. I am deliberately not allow access to the Table itself, because this would allow uncontrolled modification of the table via the iterator.

Returns:
the name of the table or null if we're iterating across a nameless table like the one created by a select operation.

advance

boolean advance()
                throws NoSuchElementException
Advances to the next row, or if this iterator has never been used, advances to the first row. That is, the Cursor is initially positioned above the first row and the first call to advance() moves it to the first row.

Returns:
true if the iterator is positioned at a valid row after the advance.
Throws:
NoSuchElementException - if this call would advance past the last row.

columnCount

int columnCount()
Return the number of columns in the table that we're traversing.


columnName

String columnName(int index)
Return the name of the column at the indicated index. Note that this is a zero-referenced index---the leftmost column is columnName(0); The JDBC ResultSet class is 1 indexed, so don't get confused.


column

Object column(String columnName)
Return the contents of the requested column of the current row. You should treat the cells accessed through this method as read only if you ever expect to use the table in a thread-safe environment. Modify the table using Table.update(com.holub.database.Selector).

Throws:
IndexOutOfBoundsException - --- the requested column doesn't exist.

columns

Iterator columns()
Return a java.util.Iterator across all the columns in the current row.


isTraversing

boolean isTraversing(Table t)
Return true if the iterator is traversing the indicated table.


update

Object update(String columnName,
              Object newValue)
Replace the value of the indicated column of the current row with the indicated new value.

Returns:
the former contents of the now-modified cell.
Throws:
IllegalArgumentException - if the newValue is the same as the object that's being updated.

delete

void delete()
Delete the row at the current cursor position.