|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jdesktop.dataset.DataRow
public class DataRow
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.
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 |
---|
protected DataRow(DataTable table)
Method Detail |
---|
public void setReferenceValue(java.lang.String colName, java.lang.Object value)
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.public void setReferenceValue(DataColumn col, java.lang.Object value)
col
- The DataColumn to change the value for.value
- The new column reference value; may cause the row status to change, see class
comments.public void setValue(java.lang.String colName, java.lang.Object value)
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.
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.public void setValue(DataColumn col, java.lang.Object value)
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.
col
- The DataColumn for which to set the value.value
- The new column value; may cause the row status to change, see class
comments.public void resetAllToReferenceValue()
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.
public void resetToReferenceValue(java.lang.String colName)
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.
colName
- The column name for which to reset to the reference value.public void resetToReferenceValue(DataColumn col)
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.
col
- The DataColumn for which to reset to the reference value.public java.lang.Object getReferenceValue(java.lang.String colName)
colName
- The column name for which to lookup the reference value.
public java.lang.Object getValue(java.lang.String colName)
colName
- The column for which to return the current value.
public java.lang.Object getReferenceValue(DataColumn col)
col
- The DataColumn for which to return the reference value.
public java.lang.Object getValue(DataColumn col)
col
- The DataColumn for which to return the current value.
protected org.jdesktop.dataset.DataRow.DataCell getCell(DataColumn col)
public DataTable getTable()
public DataRow.DataRowStatus getStatus()
public boolean isModified(java.lang.String colName)
colName
- The column name to check for modification.
public boolean isModified(DataColumn col)
col
- The DataColumn to check for modification.
public java.lang.Object getOriginalValue(java.lang.String colName)
colName
-
public java.lang.Object getOriginalValue(DataColumn col)
col
-
public void setStatus(DataRow.DataRowStatus status)
status
- The new status for the row.public void fireDataRowChanged(RowChangeEvent evt)
evt
- The RowChangeEvent to fire.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 java.lang.String toString()
toString
in class java.lang.Object
protected org.jdesktop.dataset.DataRow.DataCell addCell(DataColumn col)
col
- The DataColumn for which to add the cell.protected DataRow.DataRowStatus deriveRowStatus()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |