com.niggle.data
Interface Record

All Known Implementing Classes:
DefaultRecord, RecordReference

public interface Record

An interface that describes the canonical methods of a data record in the niggle framework.

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 getFields()

The immutability semantics have a nuance. A record's fields can be modified via set() if the record is in an immutable state. Once a record is frozen its values are immutable. This typically occurs when the record is added to a RecordManager 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 RecordManager, the original version will be deleted and the new version will replace. It will then be initialized, and thus, immutable.

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 getFields(). 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 unique ID which is set by the RecordManager when the record first put under management using insertRecord().

Author:
Jonathan Revusky
See Also:
RecordDescriptor, DefaultRecord

Field Summary
static int INVALID_ID
          By convention, the integral value of the id of a record whose unique_id is unset.
static java.lang.String STATUS_KEY
           
static java.lang.String TYPE_KEY
          The special reserved name of the type key.
 
Method Summary
 void clearFields()
          reset the fields to their default state The record must be in a mutable state.
 java.lang.Object get(FieldDescriptor field)
          Deprecated. still exists for backward compatibility
 java.lang.Object get(int i)
          Low-level method to get the value of a field.
 java.lang.Object get(java.lang.String fieldname)
          Low-level method to set the value of a field.
 java.util.Date getCreationDate()
          convenience method that returns the value of the field that holds the record's creation timestamp.
 java.util.Locale getDisplayLocale()
           
 java.util.Date getLastModified()
          convenience method that returns the value of the field that holds the record's last modified timestamp.
 RecordDescriptor getMetadata()
           
 Record getMutableCopy()
          create a clone.
 java.lang.Object getPrimaryKey()
          Retrieve the value of the record's primary key.
 java.lang.String getType()
           
 int getVersion()
          a hook to be used by versioning schemes.
 boolean isImmutable()
          Have the fields all been set? Once a record is put in a DataSource, its fields are immutable.
 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 concrete implementations will probably wrap this.
 void set(int i, java.lang.Object value)
          Low-level method to set the value of a field.
 void set(java.lang.String fieldname, java.lang.Object value)
          Low-level method to set the value of a field.
 void setMetadata(RecordDescriptor desc)
          Method only used internally by niggle.
 void setPrimaryKey(java.lang.Object o)
          set the value of this record's primary key.
 void touch()
          mark this record as having just been modified.
 

Field Detail

TYPE_KEY

public static final java.lang.String TYPE_KEY
The special reserved name of the type key.

STATUS_KEY

public static final java.lang.String STATUS_KEY

INVALID_ID

public static final int INVALID_ID
By convention, the integral value of the id of a record whose unique_id is unset.
Method Detail

getType

public java.lang.String getType()
Returns:
the name of this record type subclasses must implement this. e.g. "reminder"

getVersion

public int getVersion()
a hook to be used by versioning schemes.

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.

isStale

public boolean isStale()
Has this record been deleted or superseded in the associated DataSource?

isImmutable

public boolean isImmutable()
Have the fields all been set? Once a record is put in a DataSource, its fields are immutable.

getMetadata

public RecordDescriptor getMetadata()
Returns:
an object that describes the data held in this record.
See Also:
RecordDescriptor

get

public java.lang.Object get(FieldDescriptor field)
Deprecated. still exists for backward compatibility

Low-level method to query the value of a field in a Record. concrete implementations will probably wrap this.
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 concrete implementations will probably wrap this.
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()

getDisplayLocale

public java.util.Locale getDisplayLocale()
Returns:
a Locale for displaying the record.

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()

set

public void set(int i,
                java.lang.Object value)
Low-level method to set the value of a field. Concrete implementations will probably wrap this with a higher-level get/set API. In theory, this method breaks encapsulation and should only be called internally from concrete implementing classes. In practice, outside use may sometimes be justified by efficiency considerations.
Throws:
ImmutableDataException - if this record is immutable @see #getMutableCopy()

set

public void set(java.lang.String fieldname,
                java.lang.Object value)
Low-level method to set the value of a field. Concrete implementations will probably 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()

get

public java.lang.Object get(int i)
Low-level method to get the value of a field. Concrete implementations will probably wrap this with a higher-level get/set API. In theory, this method breaks encapsulation and should only be called internally from concrete implementing classes. In practice, outside use might sometimes be justified by efficiency considerations.

get

public java.lang.Object get(java.lang.String fieldname)
Low-level method to set the value of a field. Concrete implementations will probably wrap this with a higher-level get/set API.
Parameters:
fieldname -  
Throws:
InvalidFieldException - if there is no field of that name.

getCreationDate

public java.util.Date getCreationDate()
convenience method that returns the value of the field that holds the record's creation timestamp. This could conceivably throw an UnsupportedOperationException if the object has no creation_date field.

getLastModified

public java.util.Date getLastModified()
convenience method that returns the value of the field that holds the record's last modified timestamp. This could conceivably throw an UnsupportedOperationException if the object has no last_modified field.

touch

public void touch()
mark this record as having just been modified. This could conceivably throw an UnspoortedOperationException if the object has no last_modified field. Also, the record must be in a mutable state.

setMetadata

public void setMetadata(RecordDescriptor desc)
Method only used internally by niggle.