com.scooterframework.orm.activerecord
Class RecordRelation

java.lang.Object
  extended by com.scooterframework.orm.activerecord.RecordRelation
Direct Known Subclasses:
BelongsToRecordRelation, HasManyRecordRelation, HasManyThroughRecordRelation, HasOneRecordRelation

public class RecordRelation
extends java.lang.Object

RecordRelation class represents a relation instance. The relation class specifies a binary relation. The record object is the owner class in the relation.


Field Summary
protected  java.util.Map<java.lang.String,java.lang.Object> associationDataMap
          A cache of associated data.
protected  java.lang.String lastUsedOptions
          Value of options input in the latest method call of either associatedRecord or allAssociatedRecords method.
protected  ActiveRecord owner
           
protected  Relation relation
           
 
Constructor Summary
RecordRelation(ActiveRecord owner, Relation relation)
           
 
Method Summary
 AssociatedRecords allAssociatedRecords()
          Finds all the associated records.
 AssociatedRecords allAssociatedRecords(boolean refresh)
          Finds all the associated records.
 AssociatedRecords allAssociatedRecords(java.lang.String options)
          Finds all the associated records.
 AssociatedRecords allAssociatedRecords(java.lang.String options, boolean refresh)
          Finds all the associated records with some options.
 AssociatedRecord associatedRecord()
          Finds the associated record
 AssociatedRecord associatedRecord(boolean refresh)
          Finds the associated record
 AssociatedRecord associatedRecord(java.lang.String options)
          Finds the associated record with some options.
 AssociatedRecord associatedRecord(java.lang.String options, boolean refresh)
          Finds the associated record with some options.
 java.lang.Object getAssociatedData()
          Retrieves cached associated data.
protected  java.util.Map<java.lang.String,java.lang.Object> getFKDataMapForOther()
          Creates a data map of which key is the foreign key in child record, while the value is the corresponding data from parent record.
protected  java.lang.String getLastUsedOptions()
          Returns the last used options in retrieving data.
protected  java.util.Map<java.lang.String,java.lang.Object> getNullFKDataMapForOther()
          Creates a FK map with null value.
 ActiveRecord getOwner()
          Returns the owner of the relation.
 Relation getRelation()
          Returns the relation.
protected  boolean optionsChangedFromLastRetrieval(java.lang.String options)
          Checks if options changed after last used.
protected  ActiveRecord retrieveAssociatedData()
          Retrieves associated ActiveRecord data.
protected  ActiveRecord retrieveAssociatedData(java.lang.String options)
          Retrieves associated ActiveRecord data.
protected  java.util.List<ActiveRecord> retrieveAssociatedDataList()
          Retrieves a list of associated ActiveRecord data.
protected  java.util.List<ActiveRecord> retrieveAssociatedDataList(java.lang.String options)
          Retrieves a list of associated ActiveRecord data.
 void setAssociatedData(AssociatedRecord data)
          Stores associated data to cache.
 void setAssociatedData(AssociatedRecords data)
          Stores associated data to cache.
protected  void setLastUsedOptions(java.lang.String options)
          Sets options used last time when retrieving data.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

owner

protected ActiveRecord owner

relation

protected Relation relation

lastUsedOptions

protected java.lang.String lastUsedOptions
Value of options input in the latest method call of either associatedRecord or allAssociatedRecords method.


associationDataMap

protected java.util.Map<java.lang.String,java.lang.Object> associationDataMap
A cache of associated data. Key is entity name. Value is AssociatedRecord object for has-one, and belongs-to relation; or AssociatedRecords object for has-many and has-many-through relation.

Constructor Detail

RecordRelation

public RecordRelation(ActiveRecord owner,
                      Relation relation)
Method Detail

getRelation

public Relation getRelation()
Returns the relation.


getOwner

public ActiveRecord getOwner()
Returns the owner of the relation.


associatedRecord

public AssociatedRecord associatedRecord()
Finds the associated record

Returns:
AssociatedRecord

associatedRecord

public AssociatedRecord associatedRecord(boolean refresh)
Finds the associated record

Parameters:
refresh - If true, refresh data from database
Returns:
AssociatedRecord

associatedRecord

public AssociatedRecord associatedRecord(java.lang.String options)

Finds the associated record with some options.

See description on top of the ActiveRecord for details about options.

Note: When the same option has already been specified in the relation method such as hasOne or belongsTo, the value listed here overrides the value defined in the relation for the same option.

Parameters:
options - A string of options.
Returns:
AssociatedRecord

associatedRecord

public AssociatedRecord associatedRecord(java.lang.String options,
                                         boolean refresh)

Finds the associated record with some options. Subclass of this class must override this method in order to provide specific data retrieval mechanism.

See description on top of the ActiveRecord for details about options.

Note: When the same option has already been specified in the relation method such as hasOne or belongsTo, the value listed here overrides the value defined in the relation for the same option.

Parameters:
options - A string of options.
refresh - If true, refresh data from database
Returns:
AssociatedRecord

allAssociatedRecords

public AssociatedRecords allAssociatedRecords()
Finds all the associated records. If there is data in cache, then return the data in cache.

Returns:
AssociatedRecords contains list of ActiveRecord

allAssociatedRecords

public AssociatedRecords allAssociatedRecords(boolean refresh)
Finds all the associated records.

Parameters:
refresh - If true, refresh data from database
Returns:
AssociatedRecords contains list of ActiveRecord

allAssociatedRecords

public AssociatedRecords allAssociatedRecords(java.lang.String options)

Finds all the associated records. If there is data in cache, then return the data in cache.

See description on top of the ActiveRecord for details about options.

Note: When the same option has already been specified in the relation method such as hasMany or hasManyThrough, the value listed here overrides the value defined in the relation for the same option.

Parameters:
options - A string of options.
Returns:
AssociatedRecords contains list of ActiveRecord

allAssociatedRecords

public AssociatedRecords allAssociatedRecords(java.lang.String options,
                                              boolean refresh)

Finds all the associated records with some options. Subclass of this class must override this method in order to provide specific data retrieval mechanism.

See description on top of the ActiveRecord for details about options.

Note: When the same option has already been specified in the relation method such as hasMany or hasManyThrough, the value listed here overrides the value defined in the relation for the same option.

Parameters:
options - A string of options.
refresh - If true, refresh data from database
Returns:
AssociatedRecords contains list of ActiveRecord

getAssociatedData

public java.lang.Object getAssociatedData()
Retrieves cached associated data.

Returns:
an AssociatedRecord or AssociatedRecords object.

setAssociatedData

public void setAssociatedData(AssociatedRecord data)
Stores associated data to cache.

Parameters:
data - should be an AssociatedRecord object.

setAssociatedData

public void setAssociatedData(AssociatedRecords data)
Stores associated data to cache.

Parameters:
data - should be an AssociatedRecords object.

retrieveAssociatedData

protected ActiveRecord retrieveAssociatedData()
Retrieves associated ActiveRecord data.

Returns:
retrieved active record instance

retrieveAssociatedData

protected ActiveRecord retrieveAssociatedData(java.lang.String options)
Retrieves associated ActiveRecord data. This method must be implemented by the subclass of this class for either belongs-to type or has-one type.

Parameters:
options - options used in retrieving the record
Returns:
retrieved active record instance

retrieveAssociatedDataList

protected java.util.List<ActiveRecord> retrieveAssociatedDataList()
Retrieves a list of associated ActiveRecord data.

Returns:
retrieved active record instance list

retrieveAssociatedDataList

protected java.util.List<ActiveRecord> retrieveAssociatedDataList(java.lang.String options)
Retrieves a list of associated ActiveRecord data. This method must be implemented by the subclass of this class for either has-many type or has-many-through type.

Parameters:
options - options used in retrieving the record
Returns:
retrieved active record instance list

getLastUsedOptions

protected java.lang.String getLastUsedOptions()
Returns the last used options in retrieving data.

Returns:
options used last time

setLastUsedOptions

protected void setLastUsedOptions(java.lang.String options)
Sets options used last time when retrieving data.

Parameters:
options - options used last time

optionsChangedFromLastRetrieval

protected boolean optionsChangedFromLastRetrieval(java.lang.String options)
Checks if options changed after last used.

Parameters:
options - options to be used in retrieving data
Returns:
true if changed

getFKDataMapForOther

protected java.util.Map<java.lang.String,java.lang.Object> getFKDataMapForOther()

Creates a data map of which key is the foreign key in child record, while the value is the corresponding data from parent record. But if the data from parent record is null, then a null map is returned.

Note: This method is used in a belongs-to, has-one, has-many or has-many-through relation.

Example, order has-one status: order.oid = status.order_id. In this case, order is owner and status is target. This method sets target's FK with owner's PK field for relationship mapping: owner.oid = status.order_id. Therefore, in the created map, the key is order_id, while the value is the data from owner.oid field.


getNullFKDataMapForOther

protected java.util.Map<java.lang.String,java.lang.Object> getNullFKDataMapForOther()
Creates a FK map with null value.

Returns:
map