com.niggle.data
Class DefaultRecord

java.lang.Object
  |
  +--com.niggle.data.DefaultRecord
All Implemented Interfaces:
java.lang.Cloneable, java.io.Externalizable, Record, java.io.Serializable
Direct Known Subclasses:
AbstractJNDIRecord, AntiRecord, SessionImpl

public class DefaultRecord
extends java.lang.Object
implements Record, java.io.Externalizable, java.lang.Cloneable

A concrete implementation of the Record interface In this implementation, the records can be written out as a human-readable string. This is the scheme used for serialization. DefaultRecord implements the java.io.Externalizable interface in order to avoid the general-purpose serialization scheme. The goal was that the resulting storage format should be human-readable and modifiable in a text editor in a pinch.

Author:
Serialized Form

Fields inherited from interface com.niggle.data.Record
INVALID_ID, STATUS_KEY, TYPE_KEY
 
Constructor Summary
DefaultRecord()
           
 
Method Summary
 void checkValidity()
          Check if the record's data is valid.
 void clearFields()
          set the fields to their default values.
 boolean equals(java.lang.Object o)
           
 java.lang.Object get(FieldDescriptor field)
          Low-level method to query the value of a field in a Record.
 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()
          Simply returns the default locale, subclasses can override this to do something more useful.
 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()
          Once a record is immutable, attempts to change data will result in an ImmutableDataException being thrown.
 boolean isStale()
          Has this record been deleted or superseded in the associated DataSource?
protected  void postCheck()
          Called after checking the fields.
protected  void preCheck()
          Called before checking the fields.
 void readExternal(java.io.ObjectInput in)
           
 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 descriptor)
          Method only used internally by niggle.
 void setPrimaryKey(java.lang.Object o)
          set the value of this record's primary key.
 java.lang.String setValuesFromTable(java.util.Map table)
          Set the values of the record's fields from a key-value mapping of the fields (or field names) to values.
 java.lang.String toString()
          Provides a default string representation of the record for a human-readable flat-file persistence scheme.
 void touch()
          mark this record as having just been modified.
 void writeExternal(java.io.ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DefaultRecord

public DefaultRecord()
Method Detail

isImmutable

public boolean isImmutable()
Once a record is immutable, attempts to change data will result in an ImmutableDataException being thrown.
Specified by:
isImmutable in interface Record
Returns:
boolean value representing whether the record is immutable.

checkValidity

public final void checkValidity()
                         throws java.io.IOException
Check if the record's data is valid.
Throws:
java.io.IOException - if any of the fields are not valid. The appropriate error message is encoded in the exception.

isStale

public boolean isStale()
Description copied from interface: Record
Has this record been deleted or superseded in the associated DataSource?
Specified by:
isStale in interface Record

getPrimaryKey

public java.lang.Object getPrimaryKey()
Description copied from interface: Record
Retrieve the value of the record's primary key.
Specified by:
getPrimaryKey in interface Record
Following copied from interface: com.niggle.data.Record
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)
Description copied from interface: Record
set the value of this record's primary key. The record must be in a mutable state AND the primary key must be unset.
Specified by:
setPrimaryKey in interface Record

toString

public java.lang.String toString()
Provides a default string representation of the record for a human-readable flat-file persistence scheme.
Overrides:
toString in class java.lang.Object
Returns:
string of form field=value \n field=value \n\n

preCheck

protected void preCheck()
                 throws java.io.IOException
Called before checking the fields. Does nothing in the base implementation. Overriding this method allows you to apply certain (possibly ad hoc) fixups before doing any validity checks. Basically, this gives a class a chance to massage data that wouldn't pass the validity check.

postCheck

protected void postCheck()
                  throws java.io.IOException
Called after checking the fields. Does nothing in the base implementaiton. If you want more, possibly cross-field or cross-record validity checks, override this method and put the checks here. If the data flunks, throw the appropriate exception.

setValuesFromTable

public java.lang.String setValuesFromTable(java.util.Map table)
                                    throws java.io.IOException
Set the values of the record's fields from a key-value mapping of the fields (or field names) to values.
Parameters:
table - key-value string pairs to set values of fields.
Returns:
a string representing the status info contained in the table if any, possibly null.

getDisplayLocale

public java.util.Locale getDisplayLocale()
Simply returns the default locale, subclasses can override this to do something more useful.
Specified by:
getDisplayLocale in interface Record
Following copied from interface: com.niggle.data.Record
Returns:
a Locale for displaying the record.

get

public final java.lang.Object get(java.lang.String fieldname)
Description copied from interface: Record
Low-level method to set the value of a field. Concrete implementations will probably wrap this with a higher-level get/set API.
Specified by:
get in interface Record
Following copied from interface: com.niggle.data.Record
Parameters:
fieldname -  
Throws:
InvalidFieldException - if there is no field of that name.

set

public final void set(java.lang.String fieldname,
                      java.lang.Object value)
Description copied from interface: Record
Low-level method to set the value of a field. Concrete implementations will probably wrap this with a higher-level get/set API.
Specified by:
set in interface Record
Following copied from interface: com.niggle.data.Record
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 final java.lang.Object get(FieldDescriptor field)
Description copied from interface: Record
Low-level method to query the value of a field in a Record. concrete implementations will probably wrap this.
Specified by:
get in interface Record
Following copied from interface: com.niggle.data.Record
Parameters:
field - to query.
Returns:
an Object wrapper around field value.

set

public final void set(FieldDescriptor field,
                      java.lang.Object value)
Description copied from interface: Record
Low-level method to set an individual field value concrete implementations will probably wrap this.
Specified by:
set in interface Record
Following copied from interface: com.niggle.data.Record
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()

getMetadata

public final RecordDescriptor getMetadata()
Specified by:
getMetadata in interface Record
Following copied from interface: com.niggle.data.Record
Returns:
an object that describes the data held in this record.
See Also:
RecordDescriptor

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
Specified by:
readExternal in interface java.io.Externalizable

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Specified by:
writeExternal in interface java.io.Externalizable

getMutableCopy

public Record getMutableCopy()
create a clone. A shallow copy of the values array should be enough for immutable records Note that a newly cloned object has its immutable flag set to false, so that it is in a modifiable state.
Specified by:
getMutableCopy in interface Record

set

public final void set(int i,
                      java.lang.Object value)
Description copied from interface: Record
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.
Specified by:
set in interface Record
Following copied from interface: com.niggle.data.Record
Throws:
ImmutableDataException - if this record is immutable @see #getMutableCopy()

get

public final java.lang.Object get(int i)
Description copied from interface: Record
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.
Specified by:
get in interface Record

clearFields

public void clearFields()
set the fields to their default values.
Specified by:
clearFields in interface Record
Following copied from interface: com.niggle.data.Record
Throws:
ImmutableDataException - if this record is immutable @see #getMutableCopy()

getLastModified

public final java.util.Date getLastModified()
Description copied from interface: Record
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.
Specified by:
getLastModified in interface Record

touch

public final void touch()
Description copied from interface: Record
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.
Specified by:
touch in interface Record

getCreationDate

public final java.util.Date getCreationDate()
Description copied from interface: Record
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.
Specified by:
getCreationDate in interface Record

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

setMetadata

public final void setMetadata(RecordDescriptor descriptor)
Description copied from interface: Record
Method only used internally by niggle.
Specified by:
setMetadata in interface Record

getType

public final java.lang.String getType()
Specified by:
getType in interface Record
Following copied from interface: com.niggle.data.Record
Returns:
the name of this record type subclasses must implement this. e.g. "reminder"

getVersion

public final int getVersion()
Description copied from interface: Record
a hook to be used by versioning schemes.
Specified by:
getVersion in interface Record