|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jdesktop.dataset.DataTable
public class DataTable
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)
.
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 |
---|
protected static final java.lang.String DEFAULT_NAME_PREFIX
protected java.util.Map<java.lang.String,DataColumn> columns
protected java.util.Map<java.lang.Class,java.util.Comparator> classComparators
protected java.util.Map<DataColumn,java.util.Comparator> columnComparators
protected java.util.List<DataRow> rows
protected java.util.Map<java.lang.String,DataSelector> selectors
Constructor Detail |
---|
protected DataTable(DataSet ds)
ds
- The DataSet to which the table will be added.protected DataTable(DataSet ds, java.lang.String name)
ds
- The DataSet to which the table will be added.name
- The name of the table.Method Detail |
---|
public DataColumn createColumn()
public DataColumn createColumn(java.lang.String colName)
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
public void createColumns(java.lang.String... colNames)
colNames
- Array of column names to add to the table.public void dropColumn(java.lang.String colName)
colName
- Name of the column to drop.public java.util.List<DataColumn> getColumns()
public DataColumn getColumn(java.lang.String colName)
colName
- the name of the column that you want to retrieve
public java.util.List<DataRow> getRows()
public DataRow getRow(int index)
index
- the Index in this table associated with the DataRow to be
retrieved. This must be >0, and <rows.size()
public int getRowCount()
public DataSelector createSelector()
public DataSelector createSelector(java.lang.String name)
name
- the name for the new DataSelectorpublic java.util.List<DataSelector> getSelectors()
public DataSelector getSelector(java.lang.String name)
name
- the name of the selector to create or return
public void dropSelector(DataSelector selector)
selector
- the selector to droppublic void dropSelector(java.lang.String selectorName)
selectorName
- the name of the selector to droppublic void setName(java.lang.String name)
name
- The new name of the table; should be unique within the table's DataSet.public java.lang.String getName()
DataTable
.
public boolean isIdentityComparisonEnabled()
DataRow
.
DataRow
.public void setIdentityComparisonEnabled(boolean identityComparisonEnabled)
DataRow
.
identityComparisonEnabled
- if true, table will use identity (==
) comparison in checking for row changes.public void setClassComparator(java.lang.Class klass, java.util.Comparator comp)
DataRow
. Only one Comparator can be assigned
per class; calling this multiple times on the same class will overwrite
the Comparator assignment.
klass
- The Class to bind the Comparator with.comp
- The Comparator used.public void removeClassComparator(java.lang.Class klass)
DataRow
.
klass
- The class for which the Comparator will be removed. Fails silently
if none is assigned.public boolean hasClassComparator(java.lang.Class klass)
DataRow
.public java.util.Comparator getClassComparator(java.lang.Class klass)
klass
- The class for which to retrieve a Comparator
public void setColumnComparator(DataColumn col, java.util.Comparator comp)
DataRow
.
col
- The DataColumn to which the Comparator is bound.comp
- The Comparator instance.public void removeColumnComparator(DataColumn col)
DataRow
.
col
- The DataColumn for which to remove the bound Comparator.public boolean hasColumnComparator(DataColumn col)
setColumnComparator(DataColumn, Comparator)
; see class
JavaDocs, and docs for DataRow
.
col
- The DataColumn to find a Comparator for.
public java.util.Comparator getColumnComparator(DataColumn col)
DataRow
.
col
- The DataColumn for which to find the Comparator.
getClassComparator(Class klass)
public boolean isDeleteRowSupported()
public void setDeleteRowSupported(boolean deleteRowSupported)
deleteRowSupported
- the new value for deleteRowSupportedpublic boolean isAppendRowSupported()
public void setAppendRowSupported(boolean appendRowSupported)
appendRowSupported
- the new value for appendRowSupportedpublic DataProvider getDataProvider()
DataProvider
for this DataTable
. May be null.
public void setDataProvider(DataProvider dataProvider)
dataProvider
- the DataProvider for this DataTable. This may be null.public DataSet getDataSet()
DataSet
that is associated with this DataTable
.
public DataRow appendRow()
public DataRow appendRowNoEvent()
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
public void deleteRow(int rowIndex)
rowIndex
- the index of the row to delete. If the index is invalid,
an assertion will be raisedpublic void deleteRow(DataRow row)
row
- the row to delete. The row must belong to this DataTablepublic void discardRow(int rowIndex)
rowIndex
- Index of the row to discard.public void discardRow(DataRow row)
deleteRow(DataRow)
method,
this does not later remove the record from the data store. Rather, it simply
discards the row entirely.
row
- The row to discard.public void load()
public void loadAndWait()
public void save()
public void saveAndWait()
public void clear()
public void refresh()
clear();
load();
public void refreshAndWait()
clear();
loadAndWait();
public java.lang.Object getValue(int index, java.lang.String columnName)
index
- the row index of the row that you want to retrieve a value
forcolumnName
- the name of the column who's value you want retrieved
public void setValue(int index, java.lang.String columnName, java.lang.Object value)
index
- The row index at which to set the valuecolumnName
- Name of the column to changevalue
- The new value for the cellpublic java.lang.Object getValue(DataRow row, DataColumn col)
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.
public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
listener
- The PropertyChangeListener to notify of changes to this
instance.public void addPropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener listener)
property
- The name of the property to listen to changes for.listener
- The PropertyChangeListener to notify of changes to this
instance.public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
listener
- The listener to stop receiving notifications.public void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
propertyName
- The name of the property to ignore from now on.listener
- The listener to stop receiving notifications.public void addDataTableListener(DataTableListener listener)
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.
listener
- The listener to add for event notification.public void removeDataTableListener(DataTableListener listener)
PropertyChangeListener
, then
it is also removed as a property change listener on the table as well.
listener
- The event listener to remove from the table.public void fireDataTableChanged(TableChangeEvent evt)
TableChangeEvent
.
evt
- The TableChangeEvent
recording the event.public void fireRowChanged(RowChangeEvent evt)
RowChangeEvent
.
evt
- The RowChangeEvent
capturing the event on a row.protected int indexOfRow(DataRow row)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |