com.revusky.niggle.data
Class RecordReference

java.lang.Object
  |
  +--com.revusky.niggle.data.RecordReference
All Implemented Interfaces:
Record

public class RecordReference
extends java.lang.Object
implements Record

An object that represents a weak or soft reference to an underlying Record object. This object implements the Record interface by delegating calls to an underlying record. Most likely this class will be subclassed, since it will be necessary to implement the restoreReferent() method. However, this could still be useful on its own, since if the underlying record gets gc'ed, then the calls to the various get/set methods simply "page-fault" and the client code could simply catch the condition and recover. In any case, the presence of this base class should avoid the need to repeat the same delegation bubble-gum code all over the place.

Author:
Jonathan Revusky

Field Summary
protected  java.lang.ref.Reference ref
           
 
Fields inherited from interface com.revusky.niggle.data.Record
INVALID_ID, STATUS_KEY, TYPE_KEY
 
Constructor Summary
RecordReference(Record underlying)
           
RecordReference(Record underlying, java.lang.ref.ReferenceQueue queue)
           
 
Method Summary
 void clearFields()
          reset the fields to their default state The record must be in a mutable state.
 java.lang.ref.Reference createReference(Record rec, java.lang.ref.ReferenceQueue queue)
           
 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. concrete implementations will probably wrap this.
 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()
           
 Record getUnderlyingRecord()
           
 int getVersion()
          a hook to be used by versioning schemes.
 boolean isImmutable()
          Have the fields all been set?
 boolean isStale()
          Has this record been deleted or superseded in the associated DataSource?
 Record restoreReferent(java.lang.String type, int version, java.lang.Object primaryKey)
          A method that should restore the referent (i.e. the underlying record) from a persistent store such as an RDBMS.
 void set(FieldDescriptor field, java.lang.Object o)
          Low-level method to set an individual field value concrete implementations will probably wrap this.
 void set(int i, java.lang.Object o)
          Low-level method to set the value of a field.
 void set(java.lang.String fieldName, java.lang.Object o)
          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.
 java.lang.String toString()
           
 void touch()
          mark this record as having just been modified.
protected  void updateCacheInfo(Record rec)
          updates the information held in the reference wrapper.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ref

protected java.lang.ref.Reference ref
Constructor Detail

RecordReference

public RecordReference(Record underlying)

RecordReference

public RecordReference(Record underlying,
                       java.lang.ref.ReferenceQueue queue)
Method Detail

createReference

public java.lang.ref.Reference createReference(Record rec,
                                               java.lang.ref.ReferenceQueue queue)

getUnderlyingRecord

public Record getUnderlyingRecord()

restoreReferent

public Record restoreReferent(java.lang.String type,
                              int version,
                              java.lang.Object primaryKey)
A method that should restore the referent (i.e. the underlying record) from a persistent store such as an RDBMS. The base RecordReference has no specific knowledge of how to restore the referent, so it just throws UnsupportedOperationException. Most likely, to make use of this class, you will want to subclass it and implement this method in some useful way for your application.
Returns:
the underlying referenced record.

updateCacheInfo

protected void updateCacheInfo(Record rec)
updates the information held in the reference wrapper.

get

public 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.revusky.niggle.data.Record
Parameters:
fieldname -  
Throws:
InvalidFieldException - if there is no field of that name.

get

public 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

get

public 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.revusky.niggle.data.Record
Parameters:
field - to query.
Returns:
an Object wrapper around field value.

set

public void set(java.lang.String fieldName,
                java.lang.Object o)
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.revusky.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()

set

public void set(int i,
                java.lang.Object o)
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.revusky.niggle.data.Record
Throws:
ImmutableDataException - if this record is immutable @see #getMutableCopy()

set

public void set(FieldDescriptor field,
                java.lang.Object o)
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.revusky.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()

clearFields

public void clearFields()
Description copied from interface: Record
reset the fields to their default state The record must be in a mutable state.
Specified by:
clearFields in interface Record
Following copied from interface: com.revusky.niggle.data.Record
Throws:
ImmutableDataException - if this record is immutable @see #getMutableCopy()

getDisplayLocale

public java.util.Locale getDisplayLocale()
Specified by:
getDisplayLocale in interface Record
Following copied from interface: com.revusky.niggle.data.Record
Returns:
a Locale for displaying the record.

getMetadata

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

getMutableCopy

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

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

getCreationDate

public 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

getLastModified

public 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

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.revusky.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

getVersion

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

isImmutable

public boolean isImmutable()
Description copied from interface: Record
Have the fields all been set? Once a record is put in a DataSource, its fields are immutable.
Specified by:
isImmutable in interface Record

getType

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

touch

public 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

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

equals

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

setMetadata

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