com.holub.database
Interface Table

All Superinterfaces:
Cloneable, Serializable
All Known Implementing Classes:
UnmodifiableTable

public interface Table
extends Serializable, Cloneable

A table is a database-like table that provides support for queries.

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

Nested Class Summary
static interface Table.Exporter
          Used for exporting tables in various formats.
static interface Table.Importer
          Used for importing tables in various formats.
 
Field Summary
static boolean ALL
          A convenience constant that makes calls to commit(boolean) and rollback(boolean) more readable when used as an argument to those methods.
static boolean THIS_LEVEL
          A convenience constant that makes calls to commit(boolean) and rollback(boolean) more readable when used as an argument to those methods.
 
Method Summary
 void begin()
          begin a transaction
 Object clone()
          Return a shallow copy of the table (the contents are not copied.
 void commit(boolean all)
          Commit a transaction.
 int delete(com.holub.database.Selector where)
          Delete from the table all rows approved by the Selector.
 void export(Table.Exporter importer)
          Build a representation of the Table using the specified Exporter.
 int insert(Collection values)
          A convenience overload of insert(Object[])
 int insert(Collection columnNames, Collection values)
          A convenience overload of insert(String[],Object[])
 int insert(Object[] values)
          In this version of insert, values must have as many elements as there are columns, and the values must be in the order specified when the Table was created.
 int insert(String[] columnNames, Object[] values)
          Insert new values into the table corresponding to the specified column names.
 boolean isDirty()
          Return true if this table has changed since it was created.
 String name()
          Return the table name that was passed to the constructor (or read from the disk in the case of a table that was loaded from the disk.)
 void rename(String newName)
          Rename the table to the indicated name.
 void rollback(boolean all)
          Roll back a transaction.
 Cursor rows()
          Return an iterator across the rows of the current table.
 Table select(com.holub.database.Selector where)
          A more efficient version of select(where, null, null);
 Table select(com.holub.database.Selector where, Collection requestedColumns)
          Convenience method, translates Collection to String array, then calls String-array version.
 Table select(com.holub.database.Selector where, Collection requestedColumns, Collection other)
          A convenience method that translates Collections to arrays, then calls select(Selector,String[],Table[]);
 Table select(com.holub.database.Selector where, String[] requestedColumns)
          A more efficient version of select(where, requestedColumns, null);
 Table select(com.holub.database.Selector where, String[] requestedColumns, Table[] other)
          Create an unmodifiable table that contains selected rows from the current table.
 int update(com.holub.database.Selector where)
          Update cells in the table.
 

Field Detail

THIS_LEVEL

static final boolean THIS_LEVEL
A convenience constant that makes calls to commit(boolean) and rollback(boolean) more readable when used as an argument to those methods. Use commit(Table.THIS_LEVEL) rather than commit(false), for example.

See Also:
Constant Field Values

ALL

static final boolean ALL
A convenience constant that makes calls to commit(boolean) and rollback(boolean) more readable when used as an argument to those methods. Use commit(Table.ALL) rather than commit(true), for example.

See Also:
Constant Field Values
Method Detail

clone

Object clone()
             throws CloneNotSupportedException
Return a shallow copy of the table (the contents are not copied.

Throws:
CloneNotSupportedException

name

String name()
Return the table name that was passed to the constructor (or read from the disk in the case of a table that was loaded from the disk.) THis is a "getter," but it's a harmless one since it's just giving back a piece of information that it was given.


rename

void rename(String newName)
Rename the table to the indicated name. This method can also be used for naming the anonymous table that's returned from select(...) or one of its variants.


isDirty

boolean isDirty()
Return true if this table has changed since it was created. This status isn't entirely accurate since it's possible for a user to change some object that's in the table without telling the table about the change, so a certain amount of user discipline is required. Returns true if you modify the table using a Table method (like update, insert, etc.). The dirty bit is cleared when you export the table.


insert

int insert(String[] columnNames,
           Object[] values)
Insert new values into the table corresponding to the specified column names. For example, the value at values[i] is put into the column specified in columnNames[i]. Columns that are not specified are initialized to null.

Returns:
the number of rows affected by the operation.
Throws:
IndexOutOfBoundsException - One of the requested columns doesn't exist in either table.

insert

int insert(Collection columnNames,
           Collection values)
A convenience overload of insert(String[],Object[])


insert

int insert(Object[] values)
In this version of insert, values must have as many elements as there are columns, and the values must be in the order specified when the Table was created.

Returns:
the number of rows affected by the operation.

insert

int insert(Collection values)
A convenience overload of insert(Object[])


update

int update(com.holub.database.Selector where)
Update cells in the table. The Selector object serves as a visitor whose includeInSelect(...) method is called for each row in the table. The return value is ignored, but the Selector can modify cells as it examines them. Its your responsibility not to modify primary-key and other constant fields.

Returns:
the number of rows affected by the operation.

delete

int delete(com.holub.database.Selector where)
Delete from the table all rows approved by the Selector.

Returns:
the number of rows affected by the operation.

begin

void begin()
begin a transaction


commit

void commit(boolean all)
            throws IllegalStateException
Commit a transaction.

Parameters:
all - if false, commit only the innermost transaction, otherwise commit all transactions at all levels.
Throws:
IllegalStateException - if no begin() was issued.
See Also:
THIS_LEVEL, ALL

rollback

void rollback(boolean all)
              throws IllegalStateException
Roll back a transaction.

Parameters:
all - if false, commit only the innermost transaction, otherwise commit all transactions at all levels.
Throws:
IllegalStateException - if no begin() was issued.
See Also:
THIS_LEVEL, ALL

select

Table select(com.holub.database.Selector where,
             String[] requestedColumns,
             Table[] other)
Create an unmodifiable table that contains selected rows from the current table. The Selector argument specifies a strategy object that determines which rows will be included in the result. Table. If the other argument is present, this methods "joins" all rows from the current table and the other table and then selects rows from the "join." If the two tables contain identically named columns, then only the column from the current table is included in the result.

Joins are performed by creating the Cartesian product of the current and "other" tables, using the Selector to determine which rows of the product to include in the returned Table. For example, If one table contains:

  a b
  c d
  
and the other table contains
  e f
  g h
  
then the Cartesian product is the table
  a b e f
  a b g h
  c d e f
  c d g h
  
In the case of a join, the selector is presented with rows from this product.

The Table returned from select(com.holub.database.Selector, java.lang.String[], com.holub.database.Table[]) cannot be modified by you. The methods Table methods that normally modify the table (insert, update, delete, store) throw an UnsupportedOperationException if call them.

Parameters:
where - a selector that determines which rows to include in the result. Use Selector.ALL to include all rows.
requestedColumns - columns to include in the result. null for all columns.
other - Other tables to join to this one. At most three other tables may be specified. This argument must be null if you're not doing a join.
Returns:
a Table that holds those rows from the Cartesian product of this table and the other table that were accepted by the Selector.
Throws:
IndexOutOfBoundsException - One of the requested columns doesn't exist in either table.

select

Table select(com.holub.database.Selector where,
             String[] requestedColumns)
A more efficient version of select(where, requestedColumns, null);


select

Table select(com.holub.database.Selector where)
A more efficient version of select(where, null, null);


select

Table select(com.holub.database.Selector where,
             Collection requestedColumns,
             Collection other)
A convenience method that translates Collections to arrays, then calls select(Selector,String[],Table[]);

Parameters:
requestedColumns - a collection of String objects representing the desired columns.
other - a collection of additional Table objects to join to the current one for the purposes of this SELECT operation.

select

Table select(com.holub.database.Selector where,
             Collection requestedColumns)
Convenience method, translates Collection to String array, then calls String-array version.


rows

Cursor rows()
Return an iterator across the rows of the current table.


export

void export(Table.Exporter importer)
            throws IOException
Build a representation of the Table using the specified Exporter. Create an object from an Table.Importer using the constructor with an Table.Importer argument. The table's "dirty" status is cleared (set false) on an export.

Throws:
IOException
See Also:
isDirty()