org.xorm.datastore
Class Row

java.lang.Object
  |
  +--org.xorm.datastore.Row

All Implemented Interfaces:

Cloneable

public class Row

extends Object

implements Cloneable

A row represents a single instance of a data object. The structure of a Row is defined by its reference to a Table. The terms Row and Table could be changed to "Data Object" and "Datatype"; they were chosen to correspond to a relational database notion but are in no way tied to any particular implementation. A Row contains only primitive values; that is, there are no references to first class objects. When used with a relational database, an instance of the Row class is meant to correspond exactly with a single row in a database table. Foreign keys and primary keys are typically expressed as numeric IDs. Each instance of a Row tracks values for each Column specified for a Table. The column values may or may not have been loaded from persistent storage. This can be tested for using the containsValue() method. If the value has been set -- even to null -- containsValue() will return "true". A row also tracks dirty bits for each Column. A value is said to be dirty if it has been changed since the first time it was set. DatastoreDriver implementations are encouraged to use this information to optimize the update() operation. Finally, a Row is said to be "hollow" if no values other than the primary key have been set. Because it is possible to have a Table without a primary key (for example, a many-to-many table in a relational database), the getPrimaryKeyValue() method is not guaranteed to return a value.

Constructor Summary

Row(Table table)
Constructs a new, hollow row that references the given Table.

Row(Table table, Object primaryKey)
Constructs a new, hollow row with the given primary key.

Method Summary

void	clean() Clears all dirty bits.
Object	clone() Creates a clone of this Row's contents.
boolean	containsValue(Column column) Returns true if the row contains a value for the given column, even if the value is null.
boolean	equals(Object o) Tests row equality.
Object	getPrimaryKeyValue() Convenience method.
Table	getTable() Returns the Table that this Row is conceptually part of.
Object	getValue(Column column) Get the value for the given column.
boolean	isCached() Is this Row cached?
boolean	isDirty() Returns true if any column values are dirty.
boolean	isDirty(Column column) Returns true if the specified column value is dirty.
boolean	isHollow() Returns true if the row is hollow.
void	makeDirty(Column column) Explicitly makes a column dirty.
void	makeHollow() Makes the Row hollow by clearing all values except the primaryKey.
void	setCached(boolean val) Set the cached flag
void	setPrimaryKeyValue(Object value)
boolean	setValue(Column column, Object value) Set the value for the given column.
String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Row

public Row(Table table)

Constructs a new, hollow row that references the given Table.

Row

public Row(Table table,
           Object primaryKey)

Constructs a new, hollow row with the given primary key.

Method Detail

getTable

public Table getTable()

Returns the Table that this Row is conceptually part of.

equals

public boolean equals(Object o)

Tests row equality. Two rows are equal if their entire state matches. That is, they are both for the same table and each column configured for their table is equal.

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

clone

public Object clone()

Creates a clone of this Row's contents. Because a Row only contains immutable data (Integer, String, etc.) the contents are merely shallow-cloned. A cloned Row becomes clean if it wasn't already.

Overrides:

clone in class Object

getValue

public Object getValue(Column column)

Get the value for the given column. If no value has been set, returns null. To differentiate between a null value and a "not present" status, use the containsValue() method.

containsValue

public boolean containsValue(Column column)

Returns true if the row contains a value for the given column, even if the value is null.

setValue

public boolean setValue(Column column,
                        Object value)

Set the value for the given column. Currently this does no typechecking. If the field is being set for the first time (i.e., containsValue(column) would return false before this call) the dirty bit will not be set. Otherwise, if the new value is different from the old value, the dirty bit will be set.

Returns:

the new value of the dirty bit for the column

makeDirty

public void makeDirty(Column column)

Explicitly makes a column dirty. Generally this is not necessary, but it can be used to force an update.

isDirty

public boolean isDirty(Column column)

Returns true if the specified column value is dirty.

isDirty

public boolean isDirty()

Returns true if any column values are dirty.

clean

public void clean()

Clears all dirty bits.

isHollow

public boolean isHollow()

Returns true if the row is hollow. See the description above.

makeHollow

public void makeHollow()

Makes the Row hollow by clearing all values except the primaryKey.

getPrimaryKeyValue

public Object getPrimaryKeyValue()

Convenience method. Returns the value of the primary key for this row, or null if no key has been assigned.

setPrimaryKeyValue

public void setPrimaryKeyValue(Object value)

isCached

public boolean isCached()

Is this Row cached?

setCached

public void setCached(boolean val)

Set the cached flag