com.scooterframework.orm.activerecord
Class AssociatedRecord

java.lang.Object
  com.scooterframework.orm.activerecord.AssociatedRecord

public class AssociatedRecord
extends java.lang.Object

AssociatedRecord class contains an associated ActiveRecord object and its owner. It also has methods for the association.

Field Summary

protected ActiveRecord	associatedRecord The associated record
protected boolean	latestRecordsLoaded Indicates if the associated record have been retrieved or not
protected RecordRelation	recordRelation The RecordRelation instance for this association.

Constructor Summary

AssociatedRecord(RecordRelation recordRelation)

AssociatedRecord(RecordRelation recordRelation, ActiveRecord associatedRecord)

Method Summary

AssociatedRecord	attach(ActiveRecord newTarget) Associates with another record object.
void	cleanCache() Cleans up cached data.
void	delete() Deletes the associated record in database whether the object is dependent on the owner or not.
void	detach() Disassociates the associated object in the association by setting its foreign key to NULL.
void	detach(boolean removeDependent) Disassociates the associated object in the association by setting its foreign key to NULL.
ActiveRecord	getOwner() Returns owner of the association.
ActiveRecord	getRecord() Returns the associated record.
ActiveRecord	getRecord(boolean refresh) Returns the associated record.
Relation	getRelation() Returns relation of the association.
boolean	hasLoadedFromDatabase() Checks if the associated record has been loaded from database.
boolean	isEmpty() Returns true if there is no associated record.
AssociatedRecord	replace(ActiveRecord record) This is equivalent to detach() first and attach(record) later.
void	storeLoadedAssociatedRecord(ActiveRecord record) Stores loaded database record from database.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

recordRelation

protected RecordRelation recordRelation

The RecordRelation instance for this association.

associatedRecord

protected ActiveRecord associatedRecord

The associated record

latestRecordsLoaded

protected boolean latestRecordsLoaded

Indicates if the associated record have been retrieved or not

Constructor Detail

AssociatedRecord

public AssociatedRecord(RecordRelation recordRelation)

AssociatedRecord

public AssociatedRecord(RecordRelation recordRelation,
                        ActiveRecord associatedRecord)

Method Detail

getRecord

public ActiveRecord getRecord()

Returns the associated record.

getRecord

public ActiveRecord getRecord(boolean refresh)

Returns the associated record. If refresh is true, a database retrieval will be fired for existing owner object.

getOwner

public ActiveRecord getOwner()

Returns owner of the association.

getRelation

public Relation getRelation()

Returns relation of the association.

attach

public AssociatedRecord attach(ActiveRecord newTarget)

Associates with another record object.

How does attach(record) work for has-one relation?

 Example: Person has-one Address
          person1 <--- address1
          person2 <--- address2
          
          If we assign address2 to person1, the following will happen:
          1. The foreign key person_id in address2 should switch from 
             person2.pk to person1.pk.
          2. person1 must detach from address1. Whether address1 should be  
             deleted or not, depends on how you specify the dependent 
             attribute. 
 

Attaching a child object to a parent object (relation owner) in a has-one relation automatically saves the child object unless the parent object is new (not in database, therefore can't set up FK relation). If the parent object is new, parent.save() must be used if you want to store the association into database. The parent's previously associated child object is also updated by setting its FK value to null.

How does attach(record) work for belongs-to relation?

 Example: Address belongs-to Person
          address1 ---> person1
          address2 ---> person2
          
          If we assign person2 to address1, the following will happen:
          1. The foreign key person_id in address1 should switch from 
             person1.pk to person2.pk.
          2. person2 must detach from address2. Whether address2 should be  
             deleted or not, depends on how you specify the dependent 
             attribute. 
          3. If the reverse relation is has-many type, the address 
             counter in person1 must be decremented, while incremented in 
             person2.
 

Attaching a parent object to a child object (relation owner) in a belongs-to relation automatically saves the child object unless the parent object is new (not in database, therefore can't set up FK relation). If the parent object is new, child.save() must be used if you want to store the association into database. The parent object's previously associated child object is also detached if the reverse relation is has-one.

Parameters:

newTarget - a record to be attached

Returns:

updated AssociatedRecord

detach

public void detach()

Disassociates the associated object in the association by setting its foreign key to NULL. The child object in the association is not deleted even if it depends on the parent object.

See the method ActiveRecord.isDependentOf(ActiveRecord) for definition of dependent record.

To delete a dependent record in detach operation, use detach(true).

detach

public void detach(boolean removeDependent)

Disassociates the associated object in the association by setting its foreign key to NULL. The child object in the association may be deleted if it depends on the parent object and the removeDependent flag is true.

See the method ActiveRecord.isDependentOf(ActiveRecord) for definition of dependent record.

Parameters:

removeDependent - whether dependent record should be deleted or now.

delete

public void delete()

Deletes the associated record in database whether the object is dependent on the owner or not.

This method has no effect if the reverse relation is has-many.

replace

public AssociatedRecord replace(ActiveRecord record)

This is equivalent to detach() first and attach(record) later.

Returns:

updated AssociatedRecord

isEmpty

public boolean isEmpty()

Returns true if there is no associated record.

Returns:

true if there is no associated record.

cleanCache

public void cleanCache()

Cleans up cached data.

hasLoadedFromDatabase

public boolean hasLoadedFromDatabase()

Checks if the associated record has been loaded from database.

Returns:

true if the associated record has been loaded from database.

storeLoadedAssociatedRecord

public void storeLoadedAssociatedRecord(ActiveRecord record)

Stores loaded database record from database.

Parameters:

record - newly loaded database record from database.