com.scooterframework.orm.activerecord
Class AssociatedRecords

java.lang.Object
  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