SampleDatabase
Class TableTemplate

java.lang.Object
  |
  +--SampleDatabase.TableTemplate

All Implemented Interfaces:

DatabaseTable, DatabaseTableBase

Direct Known Subclasses:

AntiqueOwners_Table, Antiques_Table, EmployeeAddressTable_Table, EmployeeStatisticsTable_Table, Orders_Table

abstract class TableTemplate

extends Object

implements DatabaseTable

This is an abstract class that should be extended to create individual tables. Table classes should be named 'tablename_Class'. The case of the tablename is preserved, but since SQL is case-insensitive, you should not create two tables with names that only differ in case.

See one of the tables defined in this package for an idea of how to create your own tables. Decendant classes only need to provided a constructor. In addition to creating a table class, you will also need to provide a row class named 'tablename_Row'. This class only needs a list of fields representing columns and a constructor to initialize the row. See the examples provided for more information.

Author:

chris.studholme@utoronto.ca

Field Summary

protected Field[]	fields
protected String	name
protected int	rowid
protected Object[]	rows

Constructor Summary

(package private)

TableTemplate()

Method Summary

boolean	absolute(Object id) Move to an absolute rowid in the table.
void	addColumn(String name, int type, int maxlen) Add a new column to the table.
void	addRow() Add a new row to the database.
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.
int	findColumn(String name) Map a DatabaseTable column name to a DatabaseTable column index.
boolean	findNext(int column, Object data)
int	getColumnCount() What's the number of columns in the DatabaseTable?
int	getColumnDisplaySize(int column) What's the column's normal max width in chars? If the column type is not a string, or the maximum size is not known, this method may return -1.
String	getColumnLabel(int column) What's the suggested column title for use in printouts and displays? In many cases this method should return the same value as getColumnName() below.
String	getColumnName(int column) What's a column's name?
int	getColumnType(int column) What's a column's SQL type?
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.
String	getTableName() What's the table's name?
long	getTableSignature() Calculates a unique signature for this table.
long	getTableSize() Returns the size of the table in bytes.
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	isIndexAvailable(int column) Determines if an index is available for the specified column.
boolean	isReadOnly() Is table read-only (ie.
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.
DatabaseIndex	openIndex(int column) Returns an index on the specified column.
void	updateObject(int columnIndex, Object x) Update a column with an Object value.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

rowid

protected int rowid

name

protected String name

rows

protected Object[] rows

fields

protected Field[] fields

Constructor Detail

TableTemplate

TableTemplate()

Method Detail

openIndex

public DatabaseIndex openIndex(int column)

Description copied from interface: DatabaseTable

Returns an index on the specified column.

Specified by:

openIndex in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

column - index of column to be indexed

Returns:

new DatabaseIndex to use, or null if no index exists

Throws:

DatabaseException - if a database-access error occurs

close

public void close()

Description copied from interface: DatabaseTableBase

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.

Specified by:

close in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Throws:

DatabaseException - if a database-access error occurs

isIndexAvailable

public boolean isIndexAvailable(int column)

Description copied from interface: DatabaseTable

Determines if an index is available for the specified column.

Specified by:

isIndexAvailable in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

column - index of column to be indexed

Returns:

true if index is available, false otherwise

Throws:

DatabaseException - if a database-access error occurs

isReadOnly

public boolean isReadOnly()

Description copied from interface: DatabaseTable

Is table read-only (ie. no update, insert or delete)?

Specified by:

isReadOnly in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Returns:

true if so

Throws:

DatabaseException - if a database-access error occurs

getTableName

public String getTableName()

Description copied from interface: DatabaseTable

What's the table's name?

Specified by:

getTableName in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Returns:

table name or "" if not applicable

Throws:

DatabaseException - if a database-access error occurs

getColumnCount

public int getColumnCount()

Description copied from interface: DatabaseTable

What's the number of columns in the DatabaseTable?

Specified by:

getColumnCount in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Returns:

the number

Throws:

DatabaseException - if a database-access error occurs

getTableSize

public long getTableSize()

Description copied from interface: DatabaseTable

Returns the size of the table in bytes. This method may return an approximation, or -1 is the size is not known.

Specified by:

getTableSize in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Returns:

table size in bytes

Throws:

DatabaseException - if a database-access error occurs

getTableSignature

public long getTableSignature()

Description copied from interface: DatabaseTable

Calculates a unique signature for this table.

The signature should depend on values of:

• table size
• number of data files
• order of data files
• number of columns
• types and order of columns

Any change to the table that would invalidate an index should also change the signature. If this table will never be indexed, this method may return 0.

Specified by:

getTableSignature in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Returns:

unique signature for table

Throws:

DatabaseException - if a database-access error occurs

getRowCount

public long getRowCount()

Description copied from interface: DatabaseTableBase

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.

Specified by:

getRowCount in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Returns:

number of rows in table, or -1 for unknown

Throws:

DatabaseException - if a database-access error occurs

findColumn

public int findColumn(String name)

Description copied from interface: DatabaseTable

Map a DatabaseTable column name to a DatabaseTable column index. Columns should be sequentially numbered 1,2,3,etc.

Specified by:

findColumn in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

columnName - the name of the column

Returns:

the column index

Throws:

DatabaseException - if a database-access error occurs

getColumnDisplaySize

public int getColumnDisplaySize(int column)
                         throws DatabaseException

Description copied from interface: DatabaseTable

What's the column's normal max width in chars? If the column type is not a string, or the maximum size is not known, this method may return -1.

Specified by:

getColumnDisplaySize in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

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

Returns:

max width

Throws:

DatabaseException - if a database-access error occurs

getColumnName

public String getColumnName(int column)

Description copied from interface: DatabaseTable

What's a column's name?

Specified by:

getColumnName in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

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

Returns:

column name

Throws:

DatabaseException - if a database-access error occurs

getColumnLabel

public String getColumnLabel(int column)

Description copied from interface: DatabaseTable

What's the suggested column title for use in printouts and displays? In many cases this method should return the same value as getColumnName() below.

Specified by:

getColumnLabel in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

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

Returns:

true if so

Throws:

DatabaseException - if a database-access error occurs

getColumnType

public int getColumnType(int column)
                  throws DatabaseException

Description copied from interface: DatabaseTable

What's a column's SQL type?

Specified by:

getColumnType in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

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

Returns:

SQL type

Throws:

DatabaseException - if a database-access error occurs

See Also:

Types

addColumn

public void addColumn(String name,
                      int type,
                      int maxlen)
               throws DatabaseException

Description copied from interface: DatabaseTable

Add a new column to the table.

Specified by:

addColumn in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

name - column name

type - SQL type

maxlen - length of data (varying columns only)

Throws:

DatabaseException - if a database-access error occurs

See Also:

Types

next

public boolean next()

Description copied from interface: DatabaseTableBase

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.

Specified by:

next in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Returns:

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

Throws:

DatabaseException - if a database-access error occurs

findNext

public boolean findNext(int column,
                        Object data)
                 throws DatabaseException

deleteRow

public void deleteRow()
               throws DatabaseException

Description copied from interface: DatabaseTableBase

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

Specified by:

deleteRow in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Throws:

DatabaseException - if a database-access error occurs

addRow

public void addRow()
            throws DatabaseException

Description copied from interface: DatabaseTable

Add a new row to the database. This method creates a new row which must have columns set using updateObject().

Specified by:

addRow in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Throws:

DatabaseException - if a database-access error occurs

isBeforeFirst

public boolean isBeforeFirst()

Description copied from interface: DatabaseTableBase

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

Specified by:

isBeforeFirst in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Returns:

true if before the first row, false otherwise

Throws:

DatabaseException - if a database-access error occurs

isAfterLast

public boolean isAfterLast()

Description copied from interface: DatabaseTableBase

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

Specified by:

isAfterLast in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Returns:

true if after the last row, false otherwise

Throws:

DatabaseException - if a database-access error occurs

beforeFirst

public void beforeFirst()

Description copied from interface: DatabaseTableBase

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

Specified by:

beforeFirst in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Throws:

DatabaseException - if a database-access error occurs

afterLast

public void afterLast()

Description copied from interface: DatabaseTableBase

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.

Specified by:

afterLast in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Throws:

DatabaseException - if a database-access error occurs

getRowId

public Object getRowId()

Description copied from interface: DatabaseTableBase

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

Specified by:

getRowId in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Returns:

object representing current row, or null if no current row

Throws:

DatabaseException - if a database-access error occurs

absolute

public boolean absolute(Object id)

Description copied from interface: DatabaseTable

Move to an absolute rowid in the table.

Specified by:

absolute in interface DatabaseTable

Following copied from interface: ModSQL.DatabaseTable

Parameters:

rowid - id of row to seek

Returns:

true if row was found, false otherwise

Throws:

DatabaseException - if a database-access error occurs

getObject

public Object getObject(int column)
                 throws DatabaseException

Description copied from interface: DatabaseTableBase

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.

Specified by:

getObject in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

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 columnIndex,
                         Object x)
                  throws DatabaseException

Description copied from interface: DatabaseTableBase

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.

Specified by:

updateObject in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

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

Description copied from interface: DatabaseTableBase

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.

Specified by:

commitUpdates in interface DatabaseTableBase

Following copied from interface: ModSQL.DatabaseTableBase

Throws:

DatabaseException - if a database-access error occurs