org.oreodata
Interface Record

All Known Implementing Classes:

AbstractRecord, RecordProxy

public interface Record

An interface that describes the canonical methods of a data record in the Oreo Object-Relational Layer.

Basically, a Record should have the semantics of an immutable set of values, where the values follow a scheme given by the metadata in the associated RecordDescriptor instance that can be got at via the method getMetadata()

The immutability semantics have a nuance. A record's fields can be modified via set() if the record is in a mutable state. Once a record is frozen its values are immutable. This typically occurs when the record is added to an OreoDataSource container.

In this library, the way to "modify" data is via the getMutableCopy() method. This will give you a copy that can be modified. When that mutable copy is added to the OreoDataSource, the new version will replace the old version. The newer records will be frozen, i.e. immutable. Also, the older record will be marked stale, to indicate to any thread or object holding onto a reference that it has been superseded.

The real virtue of this scheme is that when you are working with a record that is immutable, you have a pretty much iron-clad guarantee that all of the data in the record is "valid" -- at least in the sense that it matches the metadata description given by getMetadata(). You also have none of the typical synchronization worries, where you have to think about the possibility that another thread can change any values out from under you.

Each record has a primary key which may be set automaticaly by the OreoDataSource when the record first put under management using insert().

Author:

Jonathan Revusky

See Also:

RecordDescriptor, DefaultRecord

Method Summary

void	clearFields() reset the fields to their default state The record must be in a mutable state.
void	freeze() make this record immutable.
java.lang.Object	get(FieldDescriptor field) Low-level method to query the value of a field in a Record.
java.lang.Object	get(java.lang.String fieldname) Method to get the value of a field by name.
java.util.List	getChildren()
RecordDescriptor	getMetadata()
Record	getMutableCopy() create a clone.
Record	getParent()
java.lang.Object	getPrimaryKey() Retrieve the value of the record's primary key.
java.lang.String	getType()
boolean	hasChildren() Does this record have children? This should return the same as (!getChildren().isEmpty()) would.
boolean	isImmutable() Have the fields all been set? Once a record is put in a DataSource, its fields are immutable.
boolean	isRootElement() Does this record have a parent? This should return the same as (getParent() == null) but it is worth having a separate method, since, with some schemes, it could be more efficient to ask whether there is a root element or not, as opposed to actually fishing it out.
boolean	isStale() Has this record been deleted or superseded in the associated DataSource?
void	set(FieldDescriptor field, java.lang.Object value) Low-level method to set an individual field value
void	set(java.lang.String fieldname, java.lang.Object value) Method to set the value of a field by name.
void	setMetadata(RecordDescriptor desc) Method only used internally.
void	setPrimaryKey(java.lang.Object o) set the value of this record's primary key.

Method Detail

getType

public java.lang.String getType()

Returns:

the name of this record type subclasses must implement this. e.g. "reminder"

getPrimaryKey

public java.lang.Object getPrimaryKey()

Retrieve the value of the record's primary key.

Returns:

the value of this record's primary key, or null if it has not been set.

setPrimaryKey

public void setPrimaryKey(java.lang.Object o)

set the value of this record's primary key. The record must be in a mutable state AND the primary key must be unset.

getMutableCopy

public Record getMutableCopy()

create a clone. A shallow copy of the record values should be enough for immutable records Note that a newly cloned object is in a mutable state, so that you can modify it.

isImmutable

public boolean isImmutable()

Have the fields all been set? Once a record is put in a DataSource, its fields are immutable.

isStale

public boolean isStale()

Has this record been deleted or superseded in the associated DataSource?

freeze

public void freeze()
            throws DataException

make this record immutable. This will typically only be called by an OreoDataSource object.

DataException

getMetadata

public RecordDescriptor getMetadata()

Returns:

an object that describes the data held in this record.

See Also:

RecordDescriptor

get

public java.lang.Object get(java.lang.String fieldname)

Method to get the value of a field by name. Subclasses may wrap this with a higher-level get/set API.

Parameters:

fieldname -

Throws:

InvalidFieldException - if there is no field of that name.

get

public java.lang.Object get(FieldDescriptor field)

Low-level method to query the value of a field in a Record.

Parameters:

field - to query.

Returns:

an Object wrapper around field value.

set

public void set(FieldDescriptor field,
                java.lang.Object value)

Low-level method to set an individual field value

Parameters:

field - to set.

value - Object wrapping the value

Throws:

InvalidFieldException - if there is no field of that name.

ImmutableDataException - if this record is immutable @see #getMutableCopy()

set

public void set(java.lang.String fieldname,
                java.lang.Object value)

Method to set the value of a field by name. Concrete implementations may wrap this with a higher-level get/set API.

Parameters:

fieldname - the name of the field to set.

Throws:

InvalidFieldException - if there is no field of that name.

ImmutableDataException - if this record is immutable @see #getMutableCopy()

clearFields

public void clearFields()

reset the fields to their default state The record must be in a mutable state.

Throws:

ImmutableDataException - if this record is immutable @see #getMutableCopy()

setMetadata

public void setMetadata(RecordDescriptor desc)

Method only used internally.

getParent

public Record getParent()
                 throws MissingContextException

Returns:

the parent element or null if there is none.

MissingContextException

getChildren

public java.util.List getChildren()
                           throws MissingContextException

Returns:

a List of children.

MissingContextException

isRootElement

public boolean isRootElement()
                      throws MissingContextException

Does this record have a parent? This should return the same as (getParent() == null) but it is worth having a separate method, since, with some schemes, it could be more efficient to ask whether there is a root element or not, as opposed to actually fishing it out.

MissingContextException

hasChildren

public boolean hasChildren()
                    throws MissingContextException

Does this record have children? This should return the same as (!getChildren().isEmpty()) would. But it can be worth having a separate method for this, since, with some schemes, it could be a lot more efficient to simply ask whether child elements are present, as opposed to actually attempting to fish them out.

MissingContextException