|
OpMath | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object
|
+--java.util.Dictionary
|
+--java.util.Hashtable
|
+--com.opmath.util.datastruct.OrderedHashtable
|
+--com.opmath.util.datastruct.UCHashtable
|
+--com.opmath.util.datastruct.ComparableTable
ComparableTable provides a flexible and well-managed container for the data which is used
to repeatedly instantiate a DMLDoc instance.
This class assumes that the data which is used to instantiate the DMLDoc instance is
tabular, and is identified by columns with unique names. However, no assumptions are made about
the way in which a ComparableTable instance is created or populated - it is possible to create
or update data by column, row or field.
All field values must implement the java.util.Comparable interface - otherwise sorting of
ComparableTables would not be practical. Since this is the only restriction on the nature of field
values, it is up to the programmer to ensure that 'sensible' comparisons are being made.
Because the class Boolean does not implement java.util.Comparable, convention
dictates that boolean true values are stored at the String "true",
and boolean false values as any other String.
Copyright: (c) 2002 The Open Math Company Limited
The Terms of Distribution of this software are stipulated in the javadoc Overview for this project.
| Constructor Summary | |
ComparableTable()
Constructs a new ComparableTable instance. |
|
ComparableTable(ComparableList newKeys)
Constructs a new ComparableTable instance. |
|
ComparableTable(String[] newStrKeys)
Constructs a new ComparableTable instance. |
|
| Method Summary | |
void |
addColumn(Comparable newKey)
Puts a new column into this ComparableTable instance. |
void |
addColumn(Comparable newKey,
ComparableList newVal)
Puts a new column into this ComparableTable instance. |
void |
appendObject(Object element)
Appends the all of the appropriate constituent values of element to the
corresponding columns in this ComparableTable. |
void |
appendTo(Comparable oldKey,
Comparable newVal)
Appends an Comparable to the column identified by oldKey. |
void |
clear()
Clears the data held in all the columns of this ComparableTable instance. |
int |
columnSize(Comparable key)
Returns the current size of the column identified by key. |
Comparable |
getAt(Comparable key,
int i)
Returns the Comparable identified by the column key and the index into
the column i. |
ComparableList |
getColumn(Comparable key)
returns the column identified by key in the form of a ComparableList. |
Vector |
getColumns()
Returns a new Vector, containing one Vector for each coulumn in
this ComparableTable instance. |
Vector |
getRows()
Returns a new Vector, containing one Vector for each row in
this ComparableTable instance. |
int |
maxColumnSize()
Returns the size of the longest column in this ComparableTable instance. |
void |
register(ComparableTable dt)
Registers a ComparableTable with this ComparableTable instance. |
void |
register(ResultSet rs)
Registers a java.sql.ResultSet with this ComparableTable instance. |
void |
register(ResultSet rs,
int startRowIndex,
int endRowIndex)
Registers a java.sql.ResultSet with this ComparableTable instance. |
void |
registerColumn(Comparable oldKey,
ResultSet rs)
Updates a column which already exists in this ComparableTable instance, by registering
one column of a ResultSet with this ComparableTable. |
void |
sort(ComparableList columnKeys)
Creates a sorted index for the rows contained in this ComparableTable. |
void |
sort(String[] columnStrKeys)
Creates a sorted index for the rows contained in this ComparableTable. |
String |
toString()
Returns a new String, detailing the contents of this ComparableTable instance. |
void |
updateAt(Comparable oldKey,
int i,
Comparable newVal)
Updates the field of column key and row i to the Comparable
newVal. |
void |
updateColumn(Comparable oldKey,
ComparableList newVal)
Updates a column which already exists in this ComparableTable instance, using data
presented in a ComparableList. |
| Methods inherited from class com.opmath.util.datastruct.UCHashtable |
normalized |
| Methods inherited from class com.opmath.util.datastruct.OrderedHashtable |
containsKey, elements, get, keys, put, putAll, remove |
| Methods inherited from class java.util.Hashtable |
clone, contains, containsValue, entrySet, equals, hashCode, isEmpty, keySet, rehash, size, values |
| Methods inherited from class java.lang.Object |
finalize, getClass, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
public ComparableTable()
ComparableTable instance. The named columns will be added later.
public ComparableTable(ComparableList newKeys)
ComparableTable instance. The named columns are identified by elements
of a ComparableList of Comparables.
NOTE: Multiple instances of the same column key Comparable are discarded.
newKeys - the ComparableList supplying the column names.public ComparableTable(String[] newStrKeys)
ComparableTable instance. The named columns are identified by elements
of a String array.
NOTE: Multiple instances of the same column key String are discarded.
newStrKeys - the String[] supplying the column names.| Method Detail |
public void clear()
ComparableTable instance. However,
clear() does not alter the keys known to the ComparableTable instance.
This method will clear the sorted index established by sort(String[]).
It is anticipated that a DMLDoc instance will be instantiated multiple times
during its lifecycle. Likewise, the ComparableTable instance can be re-used (this is more
efficient than constructing a new ComparableTable each time the DMLDoc
is to be re-instantiated). It is therefore necessary to perform a clear() operation
before re-populating the ComparableTable.
clear in interface Mapclear in class Hashtable
public void register(ResultSet rs,
int startRowIndex,
int endRowIndex)
throws ComparableTableException
java.sql.ResultSet with this ComparableTable instance.
This method will clear the sorted index established by sort(String[]).
The ResultSet must be a subset of the ComparableTable in the sense that
all of the columns in the ResultSet must already be known to the ComparableTable
instance. If so, all of the coulmns in the ResultSet are registered in the
ComparableTable; if not, none are registered and a ComparableTableException
is thrown.
If register(ResultSet, int, int) is sucessful, then any data held by this
ComparableTable for colums whose names match those in the ResultSet are lost.
The parameters startRowIndex and endRowIndex indicate the first and last rows
inclusive of the ResultSet which will be accessible to the ComparableTable. Note
that the ResultSet is numbered starting at 1 and the ComparableTable is
numbered starting at 0. Thus, following:
myTable.register(myResults, 10, 20);
it is legal to do:
myTable.getAt("myColumn", 0);
...
myTable.getAt("myColumn", 9);
NOTE: If one or both of startRowIndex and endRowIndex lie outside of the
result set range, then they are clipped to fit, without warning.
WARNING: The ResultSet must remain open as long as this ComparableTable's
contents are use - normally until a close() is done, or the ComparableTable
is discarded.
rs - the java.sql.ResultSet supplying some columns.startRowIndex - the int identifying the first relevant row in the
java.sql.ResultSet (first position is 1).endRowIndex - the int identifying the last relevant row in the
java.sql.ResultSet.
ComparableTableException - An exception thrown if
any of the column names in the ResultSet are not known to this
ComparableTable instance or the java.sql.ResultSet
could not be accessed.ComparableResultSet.ComparableResultSet(ResultSet, String, int, int)
public void register(ResultSet rs)
throws ComparableTableException
java.sql.ResultSet with this ComparableTable instance.
This method will clear the sorted index established by sort(String[]).
The ResultSet must be a subset of the ComparableTable in the sense that
all of the columns in the ResultSet must already be known to the ComparableTable
instance. If so, all of the coulmns in the ResultSet are registered in the
ComparableTable; if not, none are registered and a ComparableTableException
is thrown.
If register(ResultSet) is sucessful, then any data held by this
ComparableTable for colums whose names match those in the ResultSet are lost.
All rows in the result set will be accessible to the ComparableTable.
WARNING: The ResultSet must remain open as long as this ComparableTable's
contents are use - normally until a close() is done, or the ComparableTable
is discarded.
rs - the java.sql.ResultSet supplying some columns.
ComparableTableException - An exception thrown if
any of the column names in the ResultSet are not known to this
ComparableTable instance.
public void register(ComparableTable dt)
throws ComparableTableException
ComparableTable with this ComparableTable instance.
This method will clear the sorted index established by sort(String[]).
The ComparableTable dt must be a subset of this ComparableTable
in the sense that all of the columns in dt must already be known to this
ComparableTable instance. If so, then all of the coulmns in dt are
registered in this ComparableTable; if not, none are registered and a
ComparableTableException is thrown.
If register(ComparableTable) is sucessful, then any data held by this
ComparableTable for colums whose names match those in dt are lost.
NOTE: register(ComparableTable) establishes shared values between the two
ComparableTable instances. Thus, if dt is subsequently updated, then
the receiving ComparableTable values will appear to change.
dt - the ComparableTable supplying some columns.
ComparableTableException - An exception thrown if
any of the column names in the dt are not known to this
ComparableTable instance.
public void addColumn(Comparable newKey,
ComparableList newVal)
throws ComparableTableException
ComparableTable instance. The column will be named
newKey. Its data are held in newVal.
This method will clear the sorted index established by sort(String[]).
The key newKey must be unique and not null. Likewise, newVal
must not be null. If these restrictions are not adhered to, a
com.opmath.util.datastruct.ComparableTableException is raised.
newKey - the Comparable identifying the column.newVal - the ComparableList supplying the column values.
ComparableTableException - An exception thrown if
newKey is not unique, or either argument is null.
public void addColumn(Comparable newKey)
throws ComparableTableException
ComparableTable instance. The column will be named
newKey. The data for this column should be added later.
The key newKey must be unique and not null. If these restrictions are not
adhered to, a com.opmath.util.datastruct.ComparableTableException is raised.
newKey - the Comparable identifying the column.
ComparableTableException - An exception thrown if
newKey is not unique or null.
public void updateColumn(Comparable oldKey,
ComparableList newVal)
throws ComparableTableException
ComparableTable instance, using data
presented in a ComparableList. Any data previously associated with this column is lost.
This method will clear the sorted index established by sort(String[]).
The key oldKey must already be known to the ComparableTable instance
and must not be null. Likewise, newVal must not be null.
If these restrictions are not adhered to, a com.opmath.util.datastruct.ComparableTableException is raised.
oldKey - the Comparable identifying the column.newVal - the ComparableList supplying the column values.
ComparableTableException - An exception thrown if
oldKey is not known to the ComparableTable instance, or
either argument is null.
public void registerColumn(Comparable oldKey,
ResultSet rs)
throws ComparableTableException
ComparableTable instance, by registering
one column of a ResultSet with this ComparableTable.
This method will not clear the sorted index established by sort(String[]), but
may render the order invalid.
The ResultSet must contain a colum whose name matches a column in the
ComparableTable instance. If not, none are registered and a ComparableTableException
is thrown.
If registerColumn(Comparable, ResultSet) is sucessful, then any data held by this
ComparableTable for the column in the ResultSet are lost.
All rows in the result set will be accessible to the ComparableTable.
NOTE: If a connection cannot be made with the reult set, then register(ResultSet)
throws a ComparableTableException.
oldKey - the Comparable identifying the column.rs - the ResultSet supplying the column values.
ComparableTableException - An exception thrown if
oldKey is not known to the ComparableTable instance, or
oldKey is not found in the ResultSet.
public void updateAt(Comparable oldKey,
int i,
Comparable newVal)
throws ComparableTableException
key and row i to the Comparable
newVal. Any data previously associated with this field is lost.
This method will not clear the sorted index established by sort(String[]), but
may render the sorted index invalid.
The oldKey must already be known to the ComparableTable instance
and must not be null. Likewise, i must have already been set. If these
restrictions are not adhered to, a com.opmath.util.datastruct.ComparableTableException is raised.
oldKey - the Comparable identifying the column.i - the int identifying the row.newVal - the Comparable supplying the field value.
ComparableTableException - An exception thrown if
oldKey is not known to the ComparableTable instance, or row
i has not previously been set.updateColumn(Comparable, ComparableList)
public void appendTo(Comparable oldKey,
Comparable newVal)
throws ComparableTableException
Comparable to the column identified by oldKey. Any data previously
associated with this column is retained.
This method will clear the sorted index established by sort(String[]).
The key oldKey must already be known to the ComparableTable instance
and must not be null. If these restrictions are not adhered to, a
com.opmath.util.datastruct.ComparableTableException is raised.
oldKey - the Comparable identifying the column.newVal - the Comparable supplying the field value.
ComparableTableException - An exception thrown if
oldKey is not known to the ComparableTable instance, or
either argument is null.
public void appendObject(Object element)
throws ComparableTableException
element to the
corresponding columns in this ComparableTable.
This method will clear the sorted index established by sort(String[]).
appendObject(Object) is intended to be used where data is obtained from an
object-based source such as an Enterprise Java Bean (EJB). In this case each object obtained
from the EJB can be passed to the ComparableTable directly, thus:
ComparableTable model = viewDMLDoc.model;
Iterator itr = contacts.findAll().iterator();
Contact thisContact;
model.clear();
while (itr.hasNext()) {
thisContact = (Contact) itr.next();
}
model.appendObject(thisContact);
Requirements: appendObject(Object) examines all of the methods declared in
element's class. For all methods of the form getFieldName() where
FieldName matches the name of a column in this ComparableTable,
getFieldName() is invoked, and the result appended to the corresponding
ComparableTable column with the value cast to Comparable.
NOTE 1: appendObject(Object) processes the naming intersection of the given object
element and the receiving ComparableTable. Thus, object fields with non-matching
names remain unused, and ComparableTable columns with non-matching names remain untouched.
NOTE 2: Matching of names is case-insensitive. Thus, the method <getFieldName()
matches the column FIELDNAME.
NOTE 3: If an exception is raised during the execution of any of element's methods, then
appendObject(Object) throws a ComparableTableException with an appropriate
message. Some columns in the ComparableTable may have been updated at this point, and any
updates are not rolled back.
element - the Object carrying the fields to be appended.
ComparableTableException - An exception thrown if
something untoward happens with element's methods.
public ComparableList getColumn(Comparable key)
throws ComparableTableException
key in the form of a ComparableList.
The key key must already be known to the ComparableTable instance.
If it is not known, a com.opmath.util.datastruct.ComparableTableException is raised.
key - the Comparable identifying the column.
ComparableList.
ComparableTableException - An exception thrown if
key is not known to the ComparableTable instance, or
either argument is null.
public Comparable getAt(Comparable key,
int i)
throws ComparableTableException
Comparable identified by the column key and the index into
the column i.
The key key must already be known to the ComparableTable instance and the
index must be within the length of the column. If not, a
com.opmath.util.datastruct.ComparableTableException is raised.
NOTE: getAt(Comparable, int) makes use of the sorted index, should it exist for
this ComparableTable instance.
key - the Comparable identifying the column.i - the int identifying the row.
Comparable.
ComparableTableException - An exception thrown if
oldKey is not known to the ComparableTable instance, or
either argument is null.sort(ComparableList)
public int columnSize(Comparable key)
throws ComparableTableException
key.
The key key must already be known to the ComparableTable instance. If not, a
com.opmath.util.datastruct.ComparableTableException is raised.
key - the Comparable identifying the column.
int.
ComparableTableException - An exception thrown if
oldKey is not known to the ComparableTable instance,
or either argument is null.public int maxColumnSize()
ComparableTable instance.
int.public Vector getRows()
Vector, containing one Vector for each row in
this ComparableTable instance.
Column names are not included in the rows Vector, but within each row, field
values are given in the order in which the column name keys were given to this
ComparableTable instance.
The number of elements in each row Vector is the same as the number of keys
known to the ComparableTable instance. In the case where different lengths of columns
result in non-existant values, these are filled in with Comparables.
NOTE: getRows() makes use of the sorted index, should it exist for
this ComparableTable instance.
Vector of Vectors of Comparable elements.sort(ComparableList)public Vector getColumns()
Vector, containing one Vector for each coulumn in
this ComparableTable instance.
Column names are not included in the returned Vector, but columns are given the
same order in which the column name keys were given to this ComparableTable instance.
NOTE: getColumns() does not make use of the sorted index which may exist for
this ComparableTable instance.
Vector of Vectors of Comparable elements.
public void sort(ComparableList columnKeys)
throws ComparableTableException
ComparableTable. The specifics of the
sorting operation can be found in the class com.opmath.util.datastruct.SortedTableIndex.
sort(String[]) does not alter the contents of the ComparableTable. Instead, it
builds a sorted index, which is used by getAt(Comparable, int) and getRows()
to map requested row indices onto actual row indices.
The argument columnKeys specifies the order of significance of the columns of this
ComparableTable: element 0 of columnKeys specifies the first column to be
used for the sort, element 1 the next (when equal values are found in the first), and so on. Sorting
is always in ascending order.
Whether getAt(Comparable, int) and getRows() make use of the sorted index
is determined by the following rules:
ComparableTable is unsorted. It remains unsorted until sort(String[])
is invoked.
sort(String[]) is invoked, the ComparableTable remains sorted until
some access method is invoked which could alter the number of rows in the ComparableTable.
In this case, the sorted index is discarded. Access methods in this group are:
addColumn(Comparable, ComparableList)
appendObject(Object)
appendTo(Comparable, Comparable)
clear()
register(ResultSet)
register(ResultSet, int, int)
updateColumn(Comparable, ComparableList)
updateColumn(Comparable, String[])
updateAt(Comparable, int, Comparable)
registerColumn(Comparable, ResultSet)
ComparableTable is not returned to its
unsorted state - it is left to the programmer to determine if sort(String[]) should be
invoked again.
sort(ComparableList) throws a com.opmath.util.datastruct.ComparableTableException if any of the
columns identified by argument columnKeys are not found in this ComparableTable.
columnKeys - the ComparableList of Comparable objects
identifying the sort columns.
ComparableTableException - An exception thrown if
any column is not known to the ComparableTable instance.SortedTableIndex,
sort(String[])
public void sort(String[] columnStrKeys)
throws ComparableTableException
ComparableTable. The specifics of the
sorting operation can be found in the class com.opmath.util.datastruct.SortedTableIndex.
NOTE: This method, namely sort(String[]), is less efficient and less flexible
than the similar method sort(ComparableList). It is intended to be used only
where the data is defined as an array of String literals. For example:
String[] keys = { "firstKey", "secondKey" };
displayTable.sort(keys);
columnStrKeys - the String[] identifying the sort columns.
ComparableTableException - An exception thrown if
any column is not known to the ComparableTable instance.SortedTableIndex,
sort(ComparableList)public String toString()
String, detailing the contents of this ComparableTable instance.
toString in class OrderedHashtableString.
|
OpMath | ||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||