at.spardat.xma.mdl.util
Class TransAtomTable

java.lang.Object
  extended byat.spardat.xma.mdl.util.TransAtomTable
All Implemented Interfaces:
Descriptive, Synchronization, Transactional

public class TransAtomTable
extends java.lang.Object
implements Transactional, Synchronization, Descriptive

Manages a two dimensional arrays of Atom objects. Each row is uniquely identified by a String-key. No two rows may have the same key. Besides accessing rows by a zero-based row index, rows may be accessed using the key.

Rows are specified using arrays of Atoms. Whereever a Atom array is provided as method parameter (e.g., adding a row), a copy of the array is stored internally. So the caller may freely reuse the array.

This class relies on the fact that class Atom is immutable. Making Atom non immutable would break this class.

Columns are specified with zero-based column indexes. The number of columns a table has is specified at construction time.

A TransAtomTable supports transactional behaviour, so its changes made since the last syncpoint (construction, commit, rollback) may be undone. To support this, the syncpoint state is saved if modifications are done. The modifications themselves are also kept in a list up to a point where the size of the changes approaches the size of the table. In this case, changes are discarded which effects serialization.

Serialization is supported (methods externalize and internalize). The caller may choose to externalize deltas or the complete state. This class internally decides up to which point changes are tracked based on heuristics (actually if the cumulated serialized size of changes approaches the serialized size of the complete state). Thus the caller merely may express its wish that changes should be externalized.


Nested Class Summary
 class TransAtomTable.AddRowChangeEvent
          Adds a row to the table
 class TransAtomTable.ClearEvent
          Clears the table
 class TransAtomTable.RemoveRowChangeEvent
          Removes a row at a given index from this.
 class TransAtomTable.ReplaceAtomChangeEvent
          Replaces an Atom (table cell) in the table.
 class TransAtomTable.ReplaceRowChangeEvent
          Replaces a row at a given index with a new row.
 class TransAtomTable.TableChangeEvent
          Base class for change events on TransAtomTables.
 
Constructor Summary
TransAtomTable(int numCols)
          Constructor.
 
Method Summary
 boolean add(int rowIndex, java.lang.String key, Atom[] atoms)
          Adds a row to this at a provided index.
 boolean add(java.lang.String key, Atom[] atoms)
          Adds a row at the end of this.
 boolean changed()
          Yields true if this WidgetModel has changed since the last syncpoint.
 void clear()
          Removes all rows from this.
 void commit()
          This method clears the change history.
 boolean containsKey(java.lang.String key)
          Returns true if this table contains a row with the provided key.
 void describe(DNode n)
          describe puts all relevant information about this into the provided node.
 boolean equals(java.lang.Object obj)
          Debugging purpose.
 void externalize(XmaOutput xo, boolean ignoreDeltas)
          Externalizing this either serializes the actual state of this or the accumulated changes.
 Atom get(int rowIndex, int colIndex)
          Returns an Atom by providing row and column indexes.
 Atom get(java.lang.String key, int colIndex)
          Returns an Atom by providing a row key and a column index.
 Atom[] getAtoms(java.lang.String key)
          Returns a copy of the Atom array for a particular key or null, if this has no row with the provided key.
 java.lang.String getKey(int rowIndex)
          Returns the key at a provided row index.
 int indexOf(java.lang.String key)
          Returns the index of the row whose key equals the one provided.
 void internalize(XmaInput in)
          Updates the state of this with information of the given XmaInput.
 void remove(int index)
          Removes a row for at a given index from this.
 boolean remove(java.lang.String key)
          Removes a row for a given key from this.
 void replace(int index, Atom[] row)
          Replaces a row at a given index.
 void replace(int rowIndex, int colIndex, Atom cell)
          Replaces a particular cell in the table.
 void rollback()
          This method restores this Widget Model to its last syncpoint (which also becomes the new syncpoint).
 int size()
          Returns the number of rows in this
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TransAtomTable

public TransAtomTable(int numCols)
Constructor.

Parameters:
numCols - number of columns in this table.
Method Detail

changed

public boolean changed()
Description copied from interface: Transactional
Yields true if this WidgetModel has changed since the last syncpoint. Some models have a more complex state, e.g., a table has a domain and a selection, where either may change. In this case, subclasses will provide more detailed information on what aspect of the model really has changed.

Specified by:
changed in interface Transactional
Returns:
true if changed, false otherwise
See Also:
Transactional.changed()

rollback

public void rollback()
Description copied from interface: Transactional
This method restores this Widget Model to its last syncpoint (which also becomes the new syncpoint).

Specified by:
rollback in interface Transactional
See Also:
Transactional.rollback()

commit

public void commit()
Description copied from interface: Transactional
This method clears the change history. Calling rollback afterwards won't have any effect. This method defines a new syncpoint.

Specified by:
commit in interface Transactional
See Also:
Transactional.commit()

size

public int size()
Returns the number of rows in this


get

public Atom get(int rowIndex,
                int colIndex)
Returns an Atom by providing row and column indexes.

Parameters:
rowIndex - the index of the row
colIndex - the index of the column
Returns:
the retrieved Atom
Throws:
java.lang.ArrayIndexOutOfBoundsException - if a provided index is invalid

get

public Atom get(java.lang.String key,
                int colIndex)
Returns an Atom by providing a row key and a column index.

Parameters:
key - the key of the row
colIndex - the index of the columns
Returns:
the retrieved Atom or null if this table has no row with the provided key.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if colIndex is invalid.

getAtoms

public Atom[] getAtoms(java.lang.String key)
Returns a copy of the Atom array for a particular key or null, if this has no row with the provided key.

Parameters:
key - of the wanted row
Returns:
null, if key not found, copied Atom [] otherwise.

indexOf

public int indexOf(java.lang.String key)
Returns the index of the row whose key equals the one provided.

This is a time consuming operation of O(n).

Parameters:
key - the key of the entry whose row is wanted.
Returns:
the index of the found entry or -1 if the key is not in the table.

getKey

public java.lang.String getKey(int rowIndex)
Returns the key at a provided row index.

Throws:
java.lang.ArrayIndexOutOfBoundsException - if index out of range.

add

public boolean add(int rowIndex,
                   java.lang.String key,
                   Atom[] atoms)
Adds a row to this at a provided index.

Parameters:
rowIndex - the index at which the row should be added. Must lie in the range [0, size()].
key - the key of the newly inserted row
atoms - an array of Atoms.
Returns:
true if added, false if this already contains a row with the provided key and the row was not added.
Throws:
java.lang.IllegalArgumentException - if rowIndex out of range or the length of atoms is unequal to the number of columns provided at construction time.

add

public boolean add(java.lang.String key,
                   Atom[] atoms)
Adds a row at the end of this.

Parameters:
key - the key of the newly inserted row
atoms - an array of Atoms.
Returns:
true if added, false if this already contains a row with the provided key
Throws:
java.lang.IllegalArgumentException - if the length of atoms is unequal to the number of columns provided at construction time.

remove

public boolean remove(java.lang.String key)
Removes a row for a given key from this. This operation is of O(n).

Parameters:
key - the key whose row should be removed
Returns:
true if this has contained a row with the given key, false otherwise

remove

public void remove(int index)
Removes a row for at a given index from this. This operation is of O(n).

Parameters:
index - the index of the row that should be removed.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index out of range

replace

public void replace(int index,
                    Atom[] row)
Replaces a row at a given index.

Parameters:
index - the index at which the row is to be replaced.
row - the new row
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is out of bounds.
java.lang.IllegalArgumentException - if the length of atoms is unequal to the number of columns provided at construction time.

replace

public void replace(int rowIndex,
                    int colIndex,
                    Atom cell)
Replaces a particular cell in the table.

Parameters:
rowIndex - the row index at which the new cell is to be replaced
colIndex - the column index of the cell
cell - the new Atom
Throws:
java.lang.ArrayIndexOutOfBoundsException - if rowIndex or colIndex are out of bounds.

containsKey

public boolean containsKey(java.lang.String key)
Returns true if this table contains a row with the provided key.


clear

public void clear()
Removes all rows from this.


externalize

public void externalize(XmaOutput xo,
                        boolean ignoreDeltas)
                 throws java.io.IOException
Externalizing this either serializes the actual state of this or the accumulated changes. The default behaviour is to serialize the changes if changes are beeing tracked. This behaviour may be overwritten by ignoreDeltas. If true, changes are never written.

Specified by:
externalize in interface Synchronization
Parameters:
xo - the serialization destination
ignoreDeltas - if true, the actual state of this (all rows) is written and deltas are ignored.
Throws:
java.io.IOException - on serialization errors

internalize

public void internalize(XmaInput in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Updates the state of this with information of the given XmaInput. Before doing this, the changes in this are committed (i.e., history is discarded). Then, if in contains changes, they are read and applied to the preexisting state. Otherwise, all rows are replaced with the rows from in.

In either case, the state after calling internalize is !changed().

Specified by:
internalize in interface Synchronization
Parameters:
in - the XmaInput.
Throws:
java.io.IOException - on serialization errors
java.lang.ClassNotFoundException - on serialization errors

describe

public void describe(DNode n)
Description copied from interface: Descriptive
describe puts all relevant information about this into the provided node. The implementing method may construct subnodes of node.

Specified by:
describe in interface Descriptive
Parameters:
n - the node going to hold information about this.
See Also:
Descriptive.describe(at.spardat.xma.mdl.util.DNode)

equals

public boolean equals(java.lang.Object obj)
Debugging purpose. Do not call it for other usage.

See Also:
Object.equals(java.lang.Object)