ModSQL
Interface DatabaseTableBase

All Known Subinterfaces:

DatabaseIndex, DatabaseTable

public interface DatabaseTableBase

Base interface for DatabaseTable and DatabaseIndex. This interface is not intended to be implemented directly.

Author:

chris.studholme@utoronto.ca

See Also:

DatabaseManager

Method Summary

void	afterLast() Moves the table cursor to a position after the last row in the table.
void	beforeFirst() Moves the table cursor to a position before the first row in the table.
void	close() In some cases, it is desirable to immediately release a DatabaseTable's database and other resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.
void	commitUpdates() ModSQL will always call this method after performing a series of updateObject() calls on a particular row.
void	deleteRow() Delete the current row from the table and the underlying database.
Object	getObject(int column) Get the value of a column in the current row as a Java object.
long	getRowCount() This method is expected to return the total number of rows in the database.
Object	getRowId() Get database specific rowid value.
boolean	isAfterLast() Determine if the table cursor is positioned after the last row in the table.
boolean	isBeforeFirst() Determine if the table cursor is positioned before the first row in the table.
boolean	next() A DatabaseTable is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, etc.
void	updateObject(int column, Object x) Update a column with an Object value.

Method Detail

close

public void close()
           throws DatabaseException

In some cases, it is desirable to immediately release a DatabaseTable's database and other resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

Note: A DatabaseTable is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results. A DatabaseTable is also automatically closed when it is garbage collected.

Throws:

DatabaseException - if a database-access error occurs

getRowCount

public long getRowCount()
                 throws DatabaseException

This method is expected to return the total number of rows in the database. This value is used by ModSQL for query optimization purposes. If the count cannot be easily determined, the database should return -1 to indicate that the count is unknown.

Returns:

number of rows in table, or -1 for unknown

Throws:

DatabaseException - if a database-access error occurs

next

public boolean next()
             throws DatabaseException

A DatabaseTable is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, etc.

Returns:

true if the new current row is valid; false if there are no more rows

Throws:

DatabaseException - if a database-access error occurs

isBeforeFirst

public boolean isBeforeFirst()
                      throws DatabaseException

Determine if the table cursor is positioned before the first row in the table.

Returns:

true if before the first row, false otherwise

Throws:

DatabaseException - if a database-access error occurs

isAfterLast

public boolean isAfterLast()
                    throws DatabaseException

Determine if the table cursor is positioned after the last row in the table.

Returns:

true if after the last row, false otherwise

Throws:

DatabaseException - if a database-access error occurs

beforeFirst

public void beforeFirst()
                 throws DatabaseException

Moves the table cursor to a position before the first row in the table. The next call to next() will set the cursor to the first row in the table (assuming the table has at least one row).

Throws:

DatabaseException - if a database-access error occurs

afterLast

public void afterLast()
               throws DatabaseException

Moves the table cursor to a position after the last row in the table. All calls to next() will return false until beforeFirst() is called to reset the table.

Throws:

DatabaseException - if a database-access error occurs

getRowId

public Object getRowId()
                throws DatabaseException

Get database specific rowid value. This value can be later used with absolute() to seek to a specific row.

Returns:

object representing current row, or null if no current row

Throws:

DatabaseException - if a database-access error occurs

getObject

public Object getObject(int column)
                 throws DatabaseException

Get the value of a column in the current row as a Java object.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java Object type corresponding to the column's SQL type, following the mapping specified in the JDBC spec.

This method may also be used to read datatabase specific abstract data types.

Parameters:

column - the first column is 1, the second is 2, ...

Returns:

an Object holding the column value

Throws:

DatabaseException - if a database-access error occurs

updateObject

public void updateObject(int column,
                         Object x)
                  throws DatabaseException

Update a column with an Object value.

The updateObject() method is used to update column values in the current row, or a newly inserted row.

Parameters:

column - the first column is 1, the second is 2, ...

x - the new column value

Throws:

DatabaseException - if a database-access error occurs

commitUpdates

public void commitUpdates()
                   throws DatabaseException

ModSQL will always call this method after performing a series of updateObject() calls on a particular row. If this call is not received before the row is changed or the table is closed, the changes made by updateObject() should be discarded. In the case where addRow() was called before the updateObject() calls, the new row can be discarded as well.

Throws:

DatabaseException - if a database-access error occurs

deleteRow

public void deleteRow()
               throws DatabaseException

Delete the current row from the table and the underlying database. Cannot be called when on a newly inserted row.

Throws:

DatabaseException - if a database-access error occurs