org.jdesktop.dataset
Class DataRow

java.lang.Object
  extended by org.jdesktop.dataset.DataRow

public class DataRow
extends java.lang.Object

A DataRow contains a set of values within a DataTable; the DataTable defines the DataColumns in each row, and each row always has a value for each DataColumn. The intersection of a DataColumn in a DataRow is called a cell, though cells are not exposed in the DataRow's API. A DataRow always belongs to a DataTable; rows are added to a table using the table's DataTable.appendRow() or DataTable.appendRowNoEvent() methods and cannot be instantiated directly. Values in each cell can be changed using the setValue(String colName, Object value) or setValue(DataColumn col, Object value) methods; values are always Objects.

A DataRow always has a status, whose state is relative to the persistence mechanism for the table. Statuses are returned using the row's DataRowStatus enumeration, through getStatus() and can be changed using setStatus(DataRowStatus). Statuses are normally managed without developer intervention. Normally, when rows are loaded from a persistent store, they have a status UNCHANGED, which indicates that a DataProvider does not need to synchronize them on the next DataTable.save() operation. A status of INSERTED means the row was added to the table and should be added to the persistent store on the next DataTable.save(), UPDATED means changes to a row loaded from the persistent store must be written back to the store, and DELETED means the row should be removed from the store. Adding a row programmatically through the table's DataTable.appendRow() or DataTable.appendRowNoEvent() methods gives the row a status of INSERTED.

Each cell in a row can hold a reference value and a current value. The reference value is normally the value as last read from the persistent store; this value is usually not modified programatically, but may be overridden by a DataProvider if the row is re-read from the data store. The setReferenceValue(DataColumn col, Object refValue) method changes the reference value for a cell. The current value is the value which is normally changed programmatically or through a user interface. When the current value is different than the reference value, we say the cell has changed. If the row had UNCHANGED status before the change, its status will change to UPDATED; this happens either on both the setValue(DataColumn, Object) or setReferenceValue(DataColumn, Object) methods. An INSERTED or a DELETED row can have its cells changed without affecting the row's status.

For performance, comparing the reference to the current value of a cell is done using the Java == comparison by default, which of course only works for object references that are the same. Identity comparisons are used on all columns if the DataTable's identityComparisonEnabled property is set to true. If this property is false, one can assign a Comparator per-column in the table, or per-class (DataColumn type). If both a per-class and a per-column Comparator have been assigned, the per-column Comparator is used. If the property is false, and no Comparator is assigned, equality comparison (.equals()) is used. Note that if you do not assign Comparators, you may have rows with an UPDATED status when the value is actually the same, if the == comparison fails. For accuracy, you should assign a Comparator, but for efficiency (e.g. columns with large content sizes), you may want a Comparator that just skips the test altogether.

DataRows support both property change listeners and event listeners; note that row status is a property of the row. Events broadcast RowChangeEvent messages.

Author:
Richard Bair, Patrick Wright

Nested Class Summary
static class DataRow.DataRowStatus
          Flag indicating the status of the DataRow; these are described in the class JavaDoc.
 
Constructor Summary
protected DataRow(DataTable table)
          Create a new DataRow.
 
Method Summary
protected  org.jdesktop.dataset.DataRow.DataCell addCell(DataColumn col)
          Used internally to add a cell to the row.
 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.
protected  DataRow.DataRowStatus deriveRowStatus()
          Used internally to determine the row's current status, called after a cell's value is changed.
 void fireDataRowChanged(RowChangeEvent evt)
          Used internally to fire events for row changes.
protected  org.jdesktop.dataset.DataRow.DataCell getCell(DataColumn col)
          Returns the DataCell for the column; if there is none, creates one initialized to the column's default value.
 java.lang.Object getOriginalValue(DataColumn col)
          Deprecated. use getReferenceValue(DataColumn col)
 java.lang.Object getOriginalValue(java.lang.String colName)
          Deprecated. use getReferenceValue(String colName)
 java.lang.Object getReferenceValue(DataColumn col)
          Returns the reference value for the column.
 java.lang.Object getReferenceValue(java.lang.String colName)
          Returns the current reference value for the column.
 DataRow.DataRowStatus getStatus()
          Returns the current row status.
 DataTable getTable()
          Returns the DataTable that owns this row.
 java.lang.Object getValue(DataColumn col)
          Returns the current value for the column.
 java.lang.Object getValue(java.lang.String colName)
          Returns the value for the given column.
 boolean isModified(DataColumn col)
          Returns true if the current value for the column is different from its reference value.
 boolean isModified(java.lang.String colName)
          Returns true if the current value for the column is different from its reference value.
 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 resetAllToReferenceValue()
          Resets all columns in the row to have their current value be their reference value, effectively reverting the effects of calling setValue(DataColumn, Object) till now.
 void resetToReferenceValue(DataColumn col)
          Resets the DataColumn in the row to its reference value, effectively reverting the effects of calling setValue(DataColumn, Object) till now.
 void resetToReferenceValue(java.lang.String colName)
          Resets the named column in the row to its reference value, effectively reverting the effects of calling setValue(DataColumn, Object) till now.
 void setReferenceValue(DataColumn col, java.lang.Object value)
          Sets the given refence value to the specified DataColumn.
 void setReferenceValue(java.lang.String colName, java.lang.Object value)
          Sets the given refence value to the column with the given name.
 void setStatus(DataRow.DataRowStatus status)
          Changes the row's status; a status change event will be broadcast if the status is different from the current status.
 void setValue(DataColumn col, java.lang.Object value)
          Sets the given value to the specified DataColumn with the given name.
 void setValue(java.lang.String colName, java.lang.Object value)
          Sets the given value to the column with the given name.
 java.lang.String toString()
          
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DataRow

protected DataRow(DataTable table)
Create a new DataRow. The table creating this row must be passed in; rows are normally created by calling the DataTable's appendRow() or appendRowNoEvent methods. The new row will have a cell for each column the the table, with the value being the default value for that DataColumn.

Method Detail

setReferenceValue

public void setReferenceValue(java.lang.String colName,
                              java.lang.Object value)
Sets the given refence value to the column with the given name.

Parameters:
colName - The name of the DataColumn to change the value for.
value - The new column reference value; may cause the row status to change, see class comments.

setReferenceValue

public void setReferenceValue(DataColumn col,
                              java.lang.Object value)
Sets the given refence value to the specified DataColumn.

Parameters:
col - The DataColumn to change the value for.
value - The new column reference value; may cause the row status to change, see class comments.

setValue

public void setValue(java.lang.String colName,
                     java.lang.Object value)
Sets the given value to the column with the given name. This will fire a RowChangeEvent to DataTableListeners if the value changed; the RCE will be fired after the status change, so you can check for status changes there. If the status changes, a property change event will also be broadcast, for the status property.

Parameters:
colName - The name of the DataColumn to change the value for.
value - The new column value; may cause the row status to change, see class comments.

setValue

public void setValue(DataColumn col,
                     java.lang.Object value)
Sets the given value to the specified DataColumn with the given name. This will fire a RowChangeEvent to DataTableListeners if the value changed; the RCE will be fired after the status change, so you can check for status changes there. If the status changes, a property change event will also be broadcast, for the status property.

Parameters:
col - The DataColumn for which to set the value.
value - The new column value; may cause the row status to change, see class comments.

resetAllToReferenceValue

public void resetAllToReferenceValue()
Resets all columns in the row to have their current value be their reference value, effectively reverting the effects of calling setValue(DataColumn, Object) till now. After this method call, the row will once again regain its normal status (INSERTED or UNCHANGED). For a discussion on reference values, see the class docs.


resetToReferenceValue

public void resetToReferenceValue(java.lang.String colName)
Resets the named column in the row to its reference value, effectively reverting the effects of calling setValue(DataColumn, Object) till now. After this method call, the row may once again regain its normal status (INSERTED or UNCHANGED) if there are no longer any modified columns. For a discussion on reference values, see the class docs.

Parameters:
colName - The column name for which to reset to the reference value.

resetToReferenceValue

public void resetToReferenceValue(DataColumn col)
Resets the DataColumn in the row to its reference value, effectively reverting the effects of calling setValue(DataColumn, Object) till now. After this method call, the row may once again regain its normal status (INSERTED or UNCHANGED) if there are no longer any modified columns. For a discussion on reference values, see the class docs.

Parameters:
col - The DataColumn for which to reset to the reference value.

getReferenceValue

public java.lang.Object getReferenceValue(java.lang.String colName)
Returns the current reference value for the column.

Parameters:
colName - The column name for which to lookup the reference value.
Returns:
the reference value at the given column name; see class documentation for a discussion of reference values.

getValue

public java.lang.Object getValue(java.lang.String colName)
Returns the value for the given column.

Parameters:
colName - The column for which to return the current value.
Returns:
the value at the given column name

getReferenceValue

public java.lang.Object getReferenceValue(DataColumn col)
Returns the reference value for the column.

Parameters:
col - The DataColumn for which to return the reference value.
Returns:
the reference value for the given DataColumn; see class documentation for a discussion of reference values.

getValue

public java.lang.Object getValue(DataColumn col)
Returns the current value for the column.

Parameters:
col - The DataColumn for which to return the current value.
Returns:
the value for the given DataColumn.

getCell

protected org.jdesktop.dataset.DataRow.DataCell getCell(DataColumn col)
Returns the DataCell for the column; if there is none, creates one initialized to the column's default value.


getTable

public DataTable getTable()
Returns the DataTable that owns this row.

Returns:
The DataTable that owns this DataRow.

getStatus

public DataRow.DataRowStatus getStatus()
Returns the current row status.

Returns:
The current DataRowStatus enumerated value for this DataRow; see class comments.

isModified

public boolean isModified(java.lang.String colName)
Returns true if the current value for the column is different from its reference value.

Parameters:
colName - The column name to check for modification.
Returns:
true if the given column has been modified; see class comments.

isModified

public boolean isModified(DataColumn col)
Returns true if the current value for the column is different from its reference value.

Parameters:
col - The DataColumn to check for modification.
Returns:
true if the given column has been modified; see class comments.

getOriginalValue

public java.lang.Object getOriginalValue(java.lang.String colName)
Deprecated. use getReferenceValue(String colName)

CLEAN: remove these once getReference... methods have been approved (they replace getOriginal...)

Parameters:
colName -
Returns:
the original value for the column in this row. If the cell was not assigned a value explicitly, this is the column's default value. Otherwise it is the first value assigned to the column on this row.

getOriginalValue

public java.lang.Object getOriginalValue(DataColumn col)
Deprecated. use getReferenceValue(DataColumn col)

CLEAN: remove these once getReference... methods have been approved (they replace getOriginal...)

Parameters:
col -
Returns:
the original value for the column in this row. If the cell was not assigned a value explicitly, this is the column's default value. Otherwise it is the first value assigned to the column on this row.

setStatus

public void setStatus(DataRow.DataRowStatus status)
Changes the row's status; a status change event will be broadcast if the status is different from the current status. Changing an UPDATED row's status to UNCHANGED will overwrite reference values in all cells with the current values; modifying any column subsequently will change the row status if the columns new value is different than this reference value.

Parameters:
status - The new status for the row.

fireDataRowChanged

public void fireDataRowChanged(RowChangeEvent evt)
Used internally to fire events for row changes.

Parameters:
evt - The RowChangeEvent to fire.

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.

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

addCell

protected org.jdesktop.dataset.DataRow.DataCell addCell(DataColumn col)
Used internally to add a cell to the row. If a cell for this column already exists, returns that cell.

Parameters:
col - The DataColumn for which to add the cell.

deriveRowStatus

protected DataRow.DataRowStatus deriveRowStatus()
Used internally to determine the row's current status, called after a cell's value is changed. The general rule is that UNCHANGED rows will be marked UPDATED if at least one cell is changed, and UPDATED rows will be marked UNCHANGED if no cells are changed. INSERTED and DELETED rows do not change status in this method.



Copyright © 2005 Sun Microsystems All Rights Reserved.