com.holub.database
Class UnmodifiableTable

java.lang.Object
  extended by com.holub.database.UnmodifiableTable
All Implemented Interfaces:
Table, Serializable, Cloneable

public class UnmodifiableTable
extends Object
implements Table

This decorator of the Table class just wraps another table, but restricts access to methods that don't modify the table. The following methods toss an UnsupportedOperationException when called:

        public void  insert( String[] columnNames, Object[] values )
        public void  insert( Object[] values )
        public void  update( Selector where )
        public void  delete( Selector where )
        public void  store ()
  
Other methods delegate to the wrapped Table. All methods of the Table that are declared to return a Table actually return an UnmodifiableTable.

Refer to the Table interface for method documentation.

See Also:
Serialized Form
©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
 
Nested classes/interfaces inherited from interface com.holub.database.Table
Table.Exporter, Table.Importer
 
Field Summary
 
Fields inherited from interface com.holub.database.Table
ALL, THIS_LEVEL
 
Constructor Summary
UnmodifiableTable(Table wrapped)
           
 
Method Summary
 void begin()
          begin a transaction
 Object clone()
          Return an UnmodifieableTable that wraps a clone of the currently wrapped table.
 void commit(boolean all)
          Commit a transaction.
 int delete(com.holub.database.Selector w)
          Delete from the table all rows approved by the Selector.
 void export(Table.Exporter exporter)
          Build a representation of the Table using the specified Exporter.
 Table extract()
          Extract the wrapped table.
 int insert(Collection v)
          A convenience overload of Table.insert(Object[])
 int insert(Collection c, Collection v)
          A convenience overload of Table.insert(String[],Object[])
 int insert(Object[] v)
          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[] c, Object[] v)
          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 s)
          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 w, Collection r)
          Convenience method, translates Collection to String array, then calls String-array version.
 Table select(com.holub.database.Selector w, Collection r, Collection o)
          A convenience method that translates Collections to arrays, then calls Table.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 w, String[] r, Table[] o)
          Create an unmodifiable table that contains selected rows from the current table.
 String toString()
           
 int update(com.holub.database.Selector w)
          Update cells in the table.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

UnmodifiableTable

public UnmodifiableTable(Table wrapped)
Method Detail

clone

public Object clone()
             throws CloneNotSupportedException
Return an UnmodifieableTable that wraps a clone of the currently wrapped table. (A deep copy is used.)

Specified by:
clone in interface Table
Overrides:
clone in class Object
Throws:
CloneNotSupportedException

insert

public int insert(String[] c,
                  Object[] v)
Description copied from interface: Table
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.

Specified by:
insert in interface Table
Returns:
the number of rows affected by the operation.

insert

public int insert(Object[] v)
Description copied from interface: Table
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.

Specified by:
insert in interface Table
Returns:
the number of rows affected by the operation.

insert

public int insert(Collection c,
                  Collection v)
Description copied from interface: Table
A convenience overload of Table.insert(String[],Object[])

Specified by:
insert in interface Table

insert

public int insert(Collection v)
Description copied from interface: Table
A convenience overload of Table.insert(Object[])

Specified by:
insert in interface Table

update

public int update(com.holub.database.Selector w)
Description copied from interface: Table
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.

Specified by:
update in interface Table
Returns:
the number of rows affected by the operation.

delete

public int delete(com.holub.database.Selector w)
Description copied from interface: Table
Delete from the table all rows approved by the Selector.

Specified by:
delete in interface Table
Returns:
the number of rows affected by the operation.

begin

public void begin()
Description copied from interface: Table
begin a transaction

Specified by:
begin in interface Table

commit

public void commit(boolean all)
Description copied from interface: Table
Commit a transaction.

Specified by:
commit in interface Table
Parameters:
all - if false, commit only the innermost transaction, otherwise commit all transactions at all levels.
See Also:
Table.THIS_LEVEL, Table.ALL

rollback

public void rollback(boolean all)
Description copied from interface: Table
Roll back a transaction.

Specified by:
rollback in interface Table
Parameters:
all - if false, commit only the innermost transaction, otherwise commit all transactions at all levels.
See Also:
Table.THIS_LEVEL, Table.ALL

select

public Table select(com.holub.database.Selector w,
                    String[] r,
                    Table[] o)
Description copied from interface: Table
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 Table.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.

Specified by:
select in interface Table
Parameters:
w - a selector that determines which rows to include in the result. Use Selector.ALL to include all rows.
r - columns to include in the result. null for all columns.
o - 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.

select

public Table select(com.holub.database.Selector where,
                    String[] requestedColumns)
Description copied from interface: Table
A more efficient version of select(where, requestedColumns, null);

Specified by:
select in interface Table

select

public Table select(com.holub.database.Selector where)
Description copied from interface: Table
A more efficient version of select(where, null, null);

Specified by:
select in interface Table

select

public Table select(com.holub.database.Selector w,
                    Collection r,
                    Collection o)
Description copied from interface: Table
A convenience method that translates Collections to arrays, then calls Table.select(Selector,String[],Table[]);

Specified by:
select in interface Table
r - a collection of String objects representing the desired columns.
o - a collection of additional Table objects to join to the current one for the purposes of this SELECT operation.

select

public Table select(com.holub.database.Selector w,
                    Collection r)
Description copied from interface: Table
Convenience method, translates Collection to String array, then calls String-array version.

Specified by:
select in interface Table

rows

public Cursor rows()
Description copied from interface: Table
Return an iterator across the rows of the current table.

Specified by:
rows in interface Table

export

public void export(Table.Exporter exporter)
            throws IOException
Description copied from interface: Table
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.

Specified by:
export in interface Table
Throws:
IOException
See Also:
Table.isDirty()

toString

public String toString()
Overrides:
toString in class Object

name

public String name()
Description copied from interface: Table
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.

Specified by:
name in interface Table

rename

public void rename(String s)
Description copied from interface: Table
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.

Specified by:
rename in interface Table

isDirty

public boolean isDirty()
Description copied from interface: Table
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.

Specified by:
isDirty in interface Table

extract

public Table extract()
Extract the wrapped table. The existence of this method is problematic, since it allows someone to defeat the unmodifiability of the table. On the other hand, the wrapped table came in from outside, so external access is possible through the reference that was passed to the constructor. Use the method with care.