com.scooterframework.orm.activerecord
Class AssociatedRecords

java.lang.Object
  extended by com.scooterframework.orm.activerecord.AssociatedRecords
Direct Known Subclasses:
AssociatedRecordsHM, AssociatedRecordsHMT

public abstract class AssociatedRecords
extends java.lang.Object

AssociatedRecords class contains a list of ActiveRecord objects and its owner. It also has methods for the association.


Field Summary
protected  java.util.List<ActiveRecord> associatedRecords
          The list of associated records.
protected  boolean latestRecordsLoaded
          Indicates if associated records have been retrieved or not
protected  LogUtil log
           
protected  RecordRelation recordRelation
          The RecordRelation instance for this association.
 
Constructor Summary
AssociatedRecords(RecordRelation recordRelation)
           
AssociatedRecords(RecordRelation recordRelation, java.util.List<? extends ActiveRecord> records)
           
 
Method Summary
 AssociatedRecords add(ActiveRecord record)
          Adds a record to the association.
abstract  AssociatedRecords add(java.util.List<? extends ActiveRecord> records)
          Adds a list of records to the association.
 void cleanCache()
          Cleans up cached data.
 AssociatedRecords clear()
          Removes all associated objects from the associated list by setting their foreign keys to NULL.
 int count()
          Count number of associated records in the database.
protected abstract  int countRecordsInDB()
          Counts number of associated records in the database.
 AssociatedRecords delete(ActiveRecord record)
          Deletes an object from the associated list and delete the record in database whether the object is dependent on the owner or not.
abstract  AssociatedRecords delete(java.util.List<? extends ActiveRecord> records)
          Deletes a list objects from the associated list and delete the records in database whether the objects are dependent on the owner or not.
 AssociatedRecords detach(ActiveRecord record)
          Removes an object from the associated list.
abstract  AssociatedRecords detach(java.util.List<? extends ActiveRecord> records)
          Removes a list of objects from the associated list by setting their foreign keys to NULL.
 boolean findBy(java.lang.String field, java.lang.Object value)
          Checks if a field's value of a record in the association is equal to a specific value.
 ActiveRecord getOwner()
          Returns owner of the association.
 ActiveRecord getRecord(int index)
          Returns a specific associated record at index from the list.
 java.util.List<ActiveRecord> getRecords()
          Returns the associated records.
 java.util.List<ActiveRecord> getRecords(boolean refresh)
          Returns the associated records.
 Relation getRelation()
          Returns relation of the association.
protected  SqlService getSqlService()
          Returns gateway to database
 boolean hasLoadedFromDatabase()
          Checks if the associated record has been loaded from database.
 boolean isEmpty()
          Return true if this list contains no elements.
protected  boolean ownerIsNew()
          Checks if the owner record is a new record.
protected  java.util.List<ActiveRecord> removeRecordFromList(java.util.List<? extends ActiveRecord> records, ActiveRecord record)
          Removes a record from a list of records.
abstract  AssociatedRecords replace(java.util.List<? extends ActiveRecord> records)
          This is equivelent to clear() and add(records).
 int size()
          Returns the number of associated objects.
 void storeLoadedAssociatedRecords(java.util.List<? extends ActiveRecord> records)
          Stores newly loaded database records from database.
protected  void validateRecordType(java.lang.Class<? extends ActiveRecord> expected, java.util.List<? extends ActiveRecord> records)
          Validates that the records are of the same type as expected.
 
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.


associatedRecords

protected java.util.List<ActiveRecord> associatedRecords
The list of associated records.


latestRecordsLoaded

protected boolean latestRecordsLoaded
Indicates if associated records have been retrieved or not


log

protected LogUtil log
Constructor Detail

AssociatedRecords

public AssociatedRecords(RecordRelation recordRelation)

AssociatedRecords

public AssociatedRecords(RecordRelation recordRelation,
                         java.util.List<? extends ActiveRecord> records)
Method Detail

getRecord

public ActiveRecord getRecord(int index)
Returns a specific associated record at index from the list.

Returns:
ActiveRecord at the index

getRecords

public java.util.List<ActiveRecord> getRecords()
Returns the associated records.


getRecords

public java.util.List<ActiveRecord> getRecords(boolean refresh)

Returns the associated records.

If refresh is true, a database retrieval will be tried for the owner object.


getOwner

public ActiveRecord getOwner()
Returns owner of the association.


getRelation

public Relation getRelation()
Returns relation of the association.


add

public AssociatedRecords add(ActiveRecord record)
Adds a record to the association. If the owner object is already in the database, the record will be either inserted or updated in the database. If the owner record is not in the database, the record will not be saved to the database.

Parameters:
record - a record to be added to the relation.
Returns:
updated AssociatedRecords

add

public abstract AssociatedRecords add(java.util.List<? extends ActiveRecord> records)
Adds a list of records to the association. If the owner object is already in the database, the records will be either inserted or updated in the database. If the owner record is not in the database, the records will not be saved to the database.

Parameters:
records - a list of records to be added to the relation.
Returns:
updated AssociatedRecords.

detach

public AssociatedRecords detach(ActiveRecord record)

Removes an object from the associated list. If the object is a record in database, its foreign key will be set to NULL. The record is not deleted unless it depends on the owner.

If the owner object doesn't exist in database, only the object that has been added to the relation before can be detached.

Parameters:
record - a record to be detached.
Returns:
updated AssociatedRecords.

detach

public abstract AssociatedRecords detach(java.util.List<? extends ActiveRecord> records)

Removes a list of objects from the associated list by setting their foreign keys to NULL. The objects are not deleted unless they depend on the owner.

If the owner object doesn't exist in database, only those objects that have been added to the relation before can be detached.

Parameters:
records - list of records to be detached.
Returns:
updated AssociatedRecords.

delete

public AssociatedRecords delete(ActiveRecord record)

Deletes an object from the associated list and delete the record in database whether the object is dependent on the owner or not.

If the owner object doesn't exist in database, only the object that has been added to the relation before can be deleted.

Parameters:
record - The record to be deleted.
Returns:
updated AssociatedRecords.

delete

public abstract AssociatedRecords delete(java.util.List<? extends ActiveRecord> records)

Deletes a list objects from the associated list and delete the records in database whether the objects are dependent on the owner or not.

If the owner object doesn't exist in database, only those objects that have been added to the relation before can be detached.

Parameters:
records - a list of records to be deleted.
Returns:
updated AssociatedRecords.

clear

public AssociatedRecords clear()
Removes all associated objects from the associated list by setting their foreign keys to NULL. The records are not deleted unless they depend on the owner.

Returns:
updated AssociatedRecords

replace

public abstract AssociatedRecords replace(java.util.List<? extends ActiveRecord> records)

This is equivelent to clear() and add(records).

Removes all existing associated objects from the associated list by setting their foreign keys to NULL. The records are not deleted unless they depend on the owner.

Adds the new records to the association.

Returns:
updated AssociatedRecords

isEmpty

public boolean isEmpty()
Return true if this list contains no elements.

Returns:
true if this list contains no elements.

size

public int size()

Returns the number of associated objects. If the associated collection has already been loaded or the owner is new, this method simply returns the length of the current associated collection. If it hasn't been loaded yet, it calls count to get the length.

If you want to force a data load before calling size(), call getRecords(true) first.

Returns:
the number of associated objects.

count

public int count()
Count number of associated records in the database.

Returns:
number of associated records

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.

storeLoadedAssociatedRecords

public void storeLoadedAssociatedRecords(java.util.List<? extends ActiveRecord> records)
Stores newly loaded database records from database.

Parameters:
records - newly loaded database records from database.

findBy

public boolean findBy(java.lang.String field,
                      java.lang.Object value)
Checks if a field's value of a record in the association is equal to a specific value.

Parameters:
field - a field name
value - a specific value to compare
Returns:
true if the value is found

getSqlService

protected SqlService getSqlService()
Returns gateway to database


countRecordsInDB

protected abstract int countRecordsInDB()
Counts number of associated records in the database.

Returns:
number of associated records

ownerIsNew

protected boolean ownerIsNew()
Checks if the owner record is a new record.

Returns:
true if new record

validateRecordType

protected void validateRecordType(java.lang.Class<? extends ActiveRecord> expected,
                                  java.util.List<? extends ActiveRecord> records)
Validates that the records are of the same type as expected.

Parameters:
expected - expected class type
records - list of records to be checked

removeRecordFromList

protected java.util.List<ActiveRecord> removeRecordFromList(java.util.List<? extends ActiveRecord> records,
                                                            ActiveRecord record)
Removes a record from a list of records.

Parameters:
records - list of records
record - the record to be removed
Returns:
the remaining list