com.revusky.oreo
Class RecordReference

java.lang.Object
  |
  +--com.revusky.oreo.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
           
 
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)
           
 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.
 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()
           
 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?
 Record restoreReferent(java.lang.String type, java.lang.Object primaryKey)
          A method that should restore the referent (i.e.
 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(java.lang.String fieldName, java.lang.Object o)
          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.
 java.lang.String toString()
           
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,
                              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
Method to get the value of a field by name. Concrete implementations may wrap this with a higher-level get/set API.
Specified by:
get in interface Record
Following copied from interface: com.revusky.oreo.Record
Parameters:
fieldname -  
Throws:
InvalidFieldException - if there is no field of that name.

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.oreo.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
Method to set the value of a field by name. Concrete implementations may wrap this with a higher-level get/set API.
Specified by:
set in interface Record
Following copied from interface: com.revusky.oreo.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(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.oreo.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.oreo.Record
Throws:
ImmutableDataException - if this record is immutable @see #getMutableCopy()

getMetadata

public RecordDescriptor getMetadata()
Specified by:
getMetadata in interface Record
Following copied from interface: com.revusky.oreo.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

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

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.oreo.Record
Returns:
the name of this record type subclasses must implement this. e.g. "reminder"

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

freeze

public void freeze()
            throws java.io.IOException
Description copied from interface: Record
make this record immutable. This will typically only be called by a MutableDataSource object.
Specified by:
freeze in interface Record

setMetadata

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