org.jdesktop.dataset
Class DataTable

java.lang.Object
  extended by org.jdesktop.dataset.DataTable
Direct Known Subclasses:
DataRelationTable

public class DataTable
extends java.lang.Object

A DataTable represents a two-dimensional non-visual data structure composed of DataRows, where each row has one or more DataColumns; the set of columns is specified in the table, and applies to all rows. A DataTable always belongs to a DataSet, and in fact must be created using the DataSet.createTable() method, as a table cannot exist outside of a DataSet. For an overview of the DataSet API, see the DataSet documentation. Table data is loaded either programmatically (by your code, one row and one value at a time) or by a DataProvider. A table can have a single DataProvider, which is responsible for loading the table from, and storing table changes back to, some data source. See documentation for DataProvider and its subclasses to see what sources are supported. A table has a name property, which is unique within the DataSet that owns it. Names can be specified when the table is created, or will be assigned automatically. A table must have columns assigned to it in order to store data in any row. The intersection of a column and row is called a cell. Columns are instances of DataColumn, and each has a name unique within the table. Columns add added using createColumn(), createColumn(String) or createColumns(String...) and are attached to the table from which they are created. As a rule, any methods that are column-specific (like setValue(int, String, Object) can take either the DataColumn instance or the name of the DataColumn as a parameter. Columns can be removed from the table using dropColumn(String). Adding a column to a table with rows in it will give the cells for the new column the column's default value. Dropping a column from a table will cause the data in the cells of that column to be lost. A table has 0...n rows at any time. Blank rows are added using appendRow() and appendRowNoEvent() and remain in the table in the order they were added to it, so can be retrieved by a 0-based index using getRow(int). New rows start with the current set of columns in the table, and adding or dropping columns from a table will have those automatically added or dropped from all rows in the table. To remove a row, use deleteRow(int) or deleteRow(DataRow) if you want the table's DataProvider to remove the row as well from the table's data source. Deleted rows are maked with a row status of DELETED and remain in memory until the DataProvider removes them. To drop a row completely, use discardRow(int) or discardRow(DataRow). Discarding rows causes them to be dropped immediately from the table, and the deletion will not be recorded by the table's DataProvider. Once you have rows in the table, you can change values in the row using setValue(int, String, Object), or through the equivalent methods on the DataRow itself. You can retrieve row values using getValue(int, String) or equivalent methods on the row. Rows have a certain status within the table, as described in the documentation for the DataRow class. To list rows in the table, use getRows() or getRow(int).

Author:
Richard Bair, Patrick Wright

Field Summary
protected  java.util.Map<java.lang.Class,java.util.Comparator> classComparators
          A map of Comparators by Class type; only one Comparator is allowed per class.
protected  java.util.Map<DataColumn,java.util.Comparator> columnComparators
          A map of Comparators by DataColumn; only one Comparator is allowed per column.
protected  java.util.Map<java.lang.String,DataColumn> columns
          Mapping of DataColumn.name to DataColumn.
protected static java.lang.String DEFAULT_NAME_PREFIX
          Used as a prefix for auto-generated names.
protected  java.util.List<DataRow> rows
          The list of DataRows in this DataTable.
protected  java.util.Map<java.lang.String,DataSelector> selectors
          Every DataTable contains a list of selectors, which manage tracking "selected" state in a DataTable.
 
Constructor Summary
protected DataTable(DataSet ds)
          Create a new DataTable for a specified DataSet, with an automatically-generated name unique to the DataSet.
protected DataTable(DataSet ds, java.lang.String name)
          Create a new DataTable for a specified DataSet, with the specified name.
 
Method Summary
 void addDataTableListener(DataTableListener listener)
          Adds a DataTableListener to the table for event propagation.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to this class for any changes to bean properties.
 void addPropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to this class for specific property changes.
 DataRow appendRow()
          Append a new DataRow to this DataTable, and return the newly appended Row.
 DataRow appendRowNoEvent()
          Appends a new DataRow to this DataTable, and returns the newly appended row.
 void clear()
          Clears all of the rows from this DataTable.
 DataColumn createColumn()
          creates a new DataColumn, and adds it to this DataTable.
 DataColumn createColumn(java.lang.String colName)
          Creates a new DataColumn with the given name, and adds it to this DataTable.
 void createColumns(java.lang.String... colNames)
          Adds a column to the table for each name in the supplied array of Strings.
 DataSelector createSelector()
          Creates and returns a selector.
 DataSelector createSelector(java.lang.String name)
          Creates and returns a selector with the given name.
 void deleteRow(DataRow row)
          Doesn't actually remove the row, just marks it for deletion.
 void deleteRow(int rowIndex)
          Doesn't actually remove the row, just marks it for deletion.
 void discardRow(DataRow row)
          Actually removes the row from the DataTable.
 void discardRow(int rowIndex)
          Actually removes the row from the DataTable.
 void dropColumn(java.lang.String colName)
          Drops the column with the given name.
 void dropSelector(DataSelector selector)
          Drop the given selector
 void dropSelector(java.lang.String selectorName)
          drops the given named selector.
 void fireDataTableChanged(TableChangeEvent evt)
          Broadcasts to listeners on the table that the table has changed, using a TableChangeEvent.
 void fireRowChanged(RowChangeEvent evt)
          Broadcasts to listeners on the table that a row has changed using a RowChangeEvent.
 java.util.Comparator getClassComparator(java.lang.Class klass)
          Returns a Comparator bound to a given Class for comparison of current and reference values in a DataRow.
 DataColumn getColumn(java.lang.String colName)
           
 java.util.Comparator getColumnComparator(DataColumn col)
          Returns a Comparator bound to a given Column.
 java.util.List<DataColumn> getColumns()
           
 DataProvider getDataProvider()
          Returns the DataProvider for this DataTable.
 DataSet getDataSet()
          Returns the DataSet that is associated with this DataTable.
 java.lang.String getName()
          Returns the name of this DataTable.
 DataRow getRow(int index)
           
 int getRowCount()
           
 java.util.List<DataRow> getRows()
           
 DataSelector getSelector(java.lang.String name)
           
 java.util.List<DataSelector> getSelectors()
           
 java.lang.Object getValue(DataRow row, DataColumn col)
          Retrieves the current value for the given row and column.
 java.lang.Object getValue(int index, java.lang.String columnName)
          Returns the current value for the row at the given row index, for the given column.
 boolean hasClassComparator(java.lang.Class klass)
           
 boolean hasColumnComparator(DataColumn col)
          Returns true if the column has a specific comparator assigned to it; with setColumnComparator(DataColumn, Comparator); see class JavaDocs, and docs for DataRow.
protected  int indexOfRow(DataRow row)
          Internal method that returns the int index of the given DataRow.
 boolean isAppendRowSupported()
          Returns true if appending rows is supported.
 boolean isDeleteRowSupported()
          Returns true if deletion of rows is supported.
 boolean isIdentityComparisonEnabled()
          Returns true if rows in this table compare reference with current values using the Java identity comparison (==); see class JavaDocs, and docs for DataRow.
 void load()
          Loads this DataTable using this tables DataProvider.
 void loadAndWait()
          Loads this DataTable synchronously using this table&s DataProvider.
 void refresh()
          Refreshes the DataSet.
 void refreshAndWait()
          Refreshes the DataSet synchronously.
 void removeClassComparator(java.lang.Class klass)
          Removes assignment of a Comparator for a DataColumn type/class; see class JavaDocs, and docs for DataRow.
 void removeColumnComparator(DataColumn col)
          Removes the specific Comparator assigned to the column, if any; fails silently if none assigned; see class JavaDocs, and docs for DataRow.
 void removeDataTableListener(DataTableListener listener)
          Removes an event listener from the table; if the listener is also a PropertyChangeListener, then it is also removed as a property change listener on the table as well.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Stops notifying a specific listener of any changes to bean properties.
 void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
          Stops notifying a specific listener of changes to a specific property.
 void save()
          Saves this DataTable to the underlying DataStore.
 void saveAndWait()
          Saves this DataTable to the underyling DataStore synchronously.
 void setAppendRowSupported(boolean appendRowSupported)
          Sets whether appending rows is supported
 void setClassComparator(java.lang.Class klass, java.util.Comparator comp)
          Assigns a Comparator to use in comparing current and reference values in DataRow cells, according to a DataColumn's type/class; see class JavaDocs, and docs for DataRow.
 void setColumnComparator(DataColumn col, java.util.Comparator comp)
          Assigns a specific Comparator to a DataColumn, for use in comparing changes to DataRow cells; see class JavaDocs, and docs for DataRow.
 void setDataProvider(DataProvider dataProvider)
          Sets the DataProvider for this DataTable.
 void setDeleteRowSupported(boolean deleteRowSupported)
          Sets the deleteRowSupported flag
 void setIdentityComparisonEnabled(boolean identityComparisonEnabled)
          Sets whether rows in this table compare reference with current values using the Java identity comparison (==); see class JavaDocs, and docs for DataRow.
 void setName(java.lang.String name)
          Sets the given name to be the name of this DataTable
 void setValue(int index, java.lang.String columnName, java.lang.Object value)
          Sets the field value at the given row idnex and column to the given value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_NAME_PREFIX

protected static final java.lang.String DEFAULT_NAME_PREFIX
Used as a prefix for auto-generated names.

See Also:
Constant Field Values

columns

protected java.util.Map<java.lang.String,DataColumn> columns
Mapping of DataColumn.name to DataColumn. Extremely useful for discovering the column object associated with a name. The resolver code responsible for locating a particular data cell will first convert the column name to a DataColumn, and then use the DataColumn in the hash for locating the data. This is done so that:
  1. The lookup is constant time (or close to it)
  2. Avoid looping through a columns list looking for the column
  3. More efficient handling if the column name changes in a large table, which would not be possible if the column name was used in the hash


classComparators

protected java.util.Map<java.lang.Class,java.util.Comparator> classComparators
A map of Comparators by Class type; only one Comparator is allowed per class. This is used by DataRows to compare a new value for a cell with the reference value, to determine if the cell is "changed" or not.


columnComparators

protected java.util.Map<DataColumn,java.util.Comparator> columnComparators
A map of Comparators by DataColumn; only one Comparator is allowed per column. This is used by DataRows to compare a new value for a cell with the reference value, to determine if the cell is "changed" or not.


rows

protected java.util.List<DataRow> rows
The list of DataRows in this DataTable. The DataRow actually contains the data at the various cells.


selectors

protected java.util.Map<java.lang.String,DataSelector> selectors
Every DataTable contains a list of selectors, which manage tracking "selected" state in a DataTable. This is necessary for proper handling of master/detail relationships, also known as parent/child. This data structure maps the data selectors name to the selector itself.

Constructor Detail

DataTable

protected DataTable(DataSet ds)
Create a new DataTable for a specified DataSet, with an automatically-generated name unique to the DataSet.

Parameters:
ds - The DataSet to which the table will be added.

DataTable

protected DataTable(DataSet ds,
                    java.lang.String name)
Create a new DataTable for a specified DataSet, with the specified name.

Parameters:
ds - The DataSet to which the table will be added.
name - The name of the table.
Method Detail

createColumn

public DataColumn createColumn()
creates a new DataColumn, and adds it to this DataTable. A name will be automatically generated for the DataColumn.

Returns:
the DataColumn that was created

createColumn

public DataColumn createColumn(java.lang.String colName)
Creates a new DataColumn with the given name, and adds it to this DataTable.

Parameters:
colName - the name to give the DataColumn. If the name is invalid or has already been used in the DataSet, an assertion will be raised
Returns:
the new DataColumn

createColumns

public void createColumns(java.lang.String... colNames)
Adds a column to the table for each name in the supplied array of Strings.

Parameters:
colNames - Array of column names to add to the table.

dropColumn

public void dropColumn(java.lang.String colName)
Drops the column with the given name. If there is no column by the specified name, then nothing is done.

Parameters:
colName - Name of the column to drop.

getColumns

public java.util.List<DataColumn> getColumns()
Returns:
a List of DataColumns representing all of the columns in this DataTable.

getColumn

public DataColumn getColumn(java.lang.String colName)
Parameters:
colName - the name of the column that you want to retrieve
Returns:
the DataColumn with the given name. If the given name does not map to a DataColumn in this DataTable, then null is returned.

getRows

public java.util.List<DataRow> getRows()
Returns:
an unmodifiable list of all of the rows in this DataTable. The individual DataRow elements are modifiable, but the List is not. This includes all rows, regardless of status--inserted, updated, deleted and unchanged.

getRow

public DataRow getRow(int index)
Parameters:
index - the Index in this table associated with the DataRow to be retrieved. This must be >0, and <rows.size()
Returns:
the DataRow at the given 0 based index. The index must be valid

getRowCount

public int getRowCount()
Returns:
the number of DataRows in this DataTable; this includes all rows, regardless of status--inserted, updated, deleted and unchanged.

createSelector

public DataSelector createSelector()
Creates and returns a selector. The DataSelector will have a generated name by default.

Returns:
a selector on the table.

createSelector

public DataSelector createSelector(java.lang.String name)
Creates and returns a selector with the given name. If the name is invalid, an assertion will be raised

Parameters:
name - the name for the new DataSelector

getSelectors

public java.util.List<DataSelector> getSelectors()
Returns:
a List of DataSelectors associated with this DataTable.

getSelector

public DataSelector getSelector(java.lang.String name)
Parameters:
name - the name of the selector to create or return
Returns:
the DataSelector with the given name. If no such DataSelector exists, then a new DataSelector will be created and added to this DataTable by the given name.

dropSelector

public void dropSelector(DataSelector selector)
Drop the given selector

Parameters:
selector - the selector to drop

dropSelector

public void dropSelector(java.lang.String selectorName)
drops the given named selector. If a selector by that name does not exist, then do nothing

Parameters:
selectorName - the name of the selector to drop

setName

public void setName(java.lang.String name)
Sets the given name to be the name of this DataTable

Parameters:
name - The new name of the table; should be unique within the table's DataSet.

getName

public java.lang.String getName()
Returns the name of this DataTable.

Returns:
the name of this DataTable

isIdentityComparisonEnabled

public boolean isIdentityComparisonEnabled()
Returns true if rows in this table compare reference with current values using the Java identity comparison (==); see class JavaDocs, and docs for DataRow.

Returns:
true if rows in this table compare reference with current values using the Java identity comparison (==); see class JavaDocs, and docs for DataRow.

setIdentityComparisonEnabled

public void setIdentityComparisonEnabled(boolean identityComparisonEnabled)
Sets whether rows in this table compare reference with current values using the Java identity comparison (==); see class JavaDocs, and docs for DataRow.

Parameters:
identityComparisonEnabled - if true, table will use identity (==) comparison in checking for row changes.

setClassComparator

public void setClassComparator(java.lang.Class klass,
                               java.util.Comparator comp)
Assigns a Comparator to use in comparing current and reference values in DataRow cells, according to a DataColumn's type/class; see class JavaDocs, and docs for DataRow. Only one Comparator can be assigned per class; calling this multiple times on the same class will overwrite the Comparator assignment.

Parameters:
klass - The Class to bind the Comparator with.
comp - The Comparator used.

removeClassComparator

public void removeClassComparator(java.lang.Class klass)
Removes assignment of a Comparator for a DataColumn type/class; see class JavaDocs, and docs for DataRow.

Parameters:
klass - The class for which the Comparator will be removed. Fails silently if none is assigned.

hasClassComparator

public boolean hasClassComparator(java.lang.Class klass)
Returns:
true if the given Class has a Comparator assigned; see class JavaDocs, and docs for DataRow.

getClassComparator

public java.util.Comparator getClassComparator(java.lang.Class klass)
Returns a Comparator bound to a given Class for comparison of current and reference values in a DataRow. Will return a default Comparator that uses .equals() comparison if none was explicitly assigned.

Parameters:
klass - The class for which to retrieve a Comparator
Returns:
The Comparator bound to the Class, or a default Comparator.

setColumnComparator

public void setColumnComparator(DataColumn col,
                                java.util.Comparator comp)
Assigns a specific Comparator to a DataColumn, for use in comparing changes to DataRow cells; see class JavaDocs, and docs for DataRow.

Parameters:
col - The DataColumn to which the Comparator is bound.
comp - The Comparator instance.

removeColumnComparator

public void removeColumnComparator(DataColumn col)
Removes the specific Comparator assigned to the column, if any; fails silently if none assigned; see class JavaDocs, and docs for DataRow.

Parameters:
col - The DataColumn for which to remove the bound Comparator.

hasColumnComparator

public boolean hasColumnComparator(DataColumn col)
Returns true if the column has a specific comparator assigned to it; with setColumnComparator(DataColumn, Comparator); see class JavaDocs, and docs for DataRow.

Parameters:
col - The DataColumn to find a Comparator for.
Returns:
true if a Comparator has been bound to this DataColumn.

getColumnComparator

public java.util.Comparator getColumnComparator(DataColumn col)
Returns a Comparator bound to a given Column. Will return the comparator for the column's class if no specific comparator was assigned to the column; see class JavaDocs, and docs for DataRow.

Parameters:
col - The DataColumn for which to find the Comparator.
Returns:
The Comparator bound to this column, or the Comparator bound to the column's class; see getClassComparator(Class klass)

isDeleteRowSupported

public boolean isDeleteRowSupported()
Returns true if deletion of rows is supported.

Returns:
true if deletion of rows is supported

setDeleteRowSupported

public void setDeleteRowSupported(boolean deleteRowSupported)
Sets the deleteRowSupported flag

Parameters:
deleteRowSupported - the new value for deleteRowSupported

isAppendRowSupported

public boolean isAppendRowSupported()
Returns true if appending rows is supported.

Returns:
true if appending rows is supported

setAppendRowSupported

public void setAppendRowSupported(boolean appendRowSupported)
Sets whether appending rows is supported

Parameters:
appendRowSupported - the new value for appendRowSupported

getDataProvider

public DataProvider getDataProvider()
Returns the DataProvider for this DataTable. May be null.

Returns:
the DataProvider for this DataTable. May be null.

setDataProvider

public void setDataProvider(DataProvider dataProvider)
Sets the DataProvider for this DataTable.

Parameters:
dataProvider - the DataProvider for this DataTable. This may be null.

getDataSet

public DataSet getDataSet()
Returns the DataSet that is associated with this DataTable.

Returns:
the DataSet that is associated with this DataTable

appendRow

public DataRow appendRow()
Append a new DataRow to this DataTable, and return the newly appended Row. If appendRowSupported is false, then this method returns null

Returns:
null if !appendRowSupported, else the newly created row

appendRowNoEvent

public DataRow appendRowNoEvent()
Appends a new DataRow to this DataTable, and returns the newly appended row. This method differs from appendRow() in that it does not fire any event. This is useful to the DataProvider, which will be adding many rows and may not want many event notifications

Returns:
The row added to the table.

deleteRow

public void deleteRow(int rowIndex)
Doesn't actually remove the row, just marks it for deletion. If deletion of rows is not supported, nothing happens.

Parameters:
rowIndex - the index of the row to delete. If the index is invalid, an assertion will be raised

deleteRow

public void deleteRow(DataRow row)
Doesn't actually remove the row, just marks it for deletion. If deletion of rows is not supported, nothing happens.

Parameters:
row - the row to delete. The row must belong to this DataTable

discardRow

public void discardRow(int rowIndex)
Actually removes the row from the DataTable. Unlike the #deleteRow method, this does not later remove the record from the data store. Rather, it simply discards the row entirely

Parameters:
rowIndex - Index of the row to discard.

discardRow

public void discardRow(DataRow row)
Actually removes the row from the DataTable. Unlike the deleteRow(DataRow) method, this does not later remove the record from the data store. Rather, it simply discards the row entirely.

Parameters:
row - The row to discard.

load

public void load()
Loads this DataTable using this tables DataProvider. If DataProvider is null, then nothing is loaded. This method does not clear out the DataTable prior to loading. Calling load() n times will cause the DataTable to contain rowCount * n rows to be added.


loadAndWait

public void loadAndWait()
Loads this DataTable synchronously using this table&s DataProvider. That is, this method blocks until the load is completed. If DataProvider is null, then nothing is loaded. This method does not clear out the DataTable prior to loading. Calling load() n times will cause the DataTable to contain rowCount * n rows to be added


save

public void save()
Saves this DataTable to the underlying DataStore. This calls the DataProviders save method. If no DataProvider is specified, then nothing is done.


saveAndWait

public void saveAndWait()
Saves this DataTable to the underyling DataStore synchronously. That is, this method blocks until the save is complete. This calls the DataProvider&s save method. If no DataProvider is specified, then nothing is done.


clear

public void clear()
Clears all of the rows from this DataTable. If any rows were altered, these changes are lost!. Call #save to save the changes before clearing. An event is posted indicating that the table was cleared.


refresh

public void refresh()
Refreshes the DataSet. This is symantically the same as: clear(); load();


refreshAndWait

public void refreshAndWait()
Refreshes the DataSet synchronously. That is, this method blocks until the refresh is completed. This is symantically the same as: clear(); loadAndWait();


getValue

public java.lang.Object getValue(int index,
                                 java.lang.String columnName)
Returns the current value for the row at the given row index, for the given column.

Parameters:
index - the row index of the row that you want to retrieve a value for
columnName - the name of the column who's value you want retrieved
Returns:
the value at the given rowIndex, for the given columnName. If either the index is invalid or the columnName, assertions will be raised.

setValue

public void setValue(int index,
                     java.lang.String columnName,
                     java.lang.Object value)
Sets the field value at the given row idnex and column to the given value. If either the index is invalid or the columnName, assertions will be raised.

Parameters:
index - The row index at which to set the value
columnName - Name of the column to change
value - The new value for the cell

getValue

public java.lang.Object getValue(DataRow row,
                                 DataColumn col)
Retrieves the current value for the given row and column.

Parameters:
row - The DataRow to retrieve the value from. This row must be a member of this table, or an assertion will be raised. If null, a NullPointerException will be thrown.
col - The DataColumn to retrieve the value from. This col must be a member of this table, or an assertion will be raised. If null, a NullPointerException will be thrown.
Returns:
the current value for the given row and column.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to this class for any changes to bean properties.

Parameters:
listener - The PropertyChangeListener to notify of changes to this instance.

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String property,
                                      java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to this class for specific property changes.

Parameters:
property - The name of the property to listen to changes for.
listener - The PropertyChangeListener to notify of changes to this instance.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Stops notifying a specific listener of any changes to bean properties.

Parameters:
listener - The listener to stop receiving notifications.

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)
Stops notifying a specific listener of changes to a specific property.

Parameters:
propertyName - The name of the property to ignore from now on.
listener - The listener to stop receiving notifications.

addDataTableListener

public void addDataTableListener(DataTableListener listener)
Adds a DataTableListener to the table for event propagation. If the DTL is also a PropertyChangeListener, like DataTableEventAdapter, then this is automatically added as a property change listener on the table as well.

Parameters:
listener - The listener to add for event notification.

removeDataTableListener

public void removeDataTableListener(DataTableListener listener)
Removes an event listener from the table; if the listener is also a PropertyChangeListener, then it is also removed as a property change listener on the table as well.

Parameters:
listener - The event listener to remove from the table.

fireDataTableChanged

public void fireDataTableChanged(TableChangeEvent evt)
Broadcasts to listeners on the table that the table has changed, using a TableChangeEvent.

Parameters:
evt - The TableChangeEvent recording the event.

fireRowChanged

public void fireRowChanged(RowChangeEvent evt)
Broadcasts to listeners on the table that a row has changed using a RowChangeEvent.

Parameters:
evt - The RowChangeEvent capturing the event on a row.

indexOfRow

protected int indexOfRow(DataRow row)
Internal method that returns the int index of the given DataRow. This is currently only used for constructing toString on DataRow, and testing.



Copyright © 2005 Sun Microsystems All Rights Reserved.