av.tob
Class KinSet<R extends TheRelation,T extends TheObject>

java.lang.Object
  av.tob.KinSet<R,T>

Type Parameters:

R - class of the source relations

T - class of the related objects

All Implemented Interfaces:

Iterable<Kin<R,T>>

public final class KinSet<R extends TheRelation,T extends TheObject>
extends Object
implements Iterable<Kin<R,T>>

The KinSet class serves as the type of kin set fields, a kin set contains multiple Kins.

Kin and KinSet fields are means by which persistent objects can reach their related objects that related by existence of corresponding relation objects.

A relation object ties 2 or more persistent objects together with 2 or more Tie fields. The tied objects each performs its own role in the relation, which is reflected by name of the Tie field tying it. These tied objects directly see eachother through their own Kin and KinSet fields.

A relation object can also have only 1 Tie field, which used to tie itself to another object. In this case the tied object can have a direct Kin or KinSet field to see back the relation object.

A kin presents a related object connected via existence of a source relation object. The R type parameter declares the source relation class of the kin, while the T type parameter declares the class of the related object. Roles in the source relation are essential for kins. To define the semantics of a Kin or KinSet field, 2 list of roles are concerned:

Self Roles

A list of names of Tie fields in the source relation class, that may tie the object defines the Kin or KinSet field. This list may be explicitly specified with a IAm annotation. Or TOB can determine it by comparing the defining class to target type of all Tie fields in the source relation class.

Target Roles

A list of names of Tie fields in the source relation class, that may tie the related object. This list may be explicitly specified with a ThisIs annotation for a Kin field or with a TheyAre annotation for a KinSet field. Or TOB can determine it by comparing the related object class (the T) to target type of all Tie fields in the source relation class.

The runtime values of Kin fields and contents of KinSet fields are automatically maintained by TOB, according to corresponsive relation object manipulations. Applications just define and read these fields to traverse across the persistent object topograph.

Applications normally don't initialize kin set fields at their persistent classes, it can be safely assumed that kin set fields of born objects are always properly initialized. Since TOB will generate code to initialize kin set fields for born objects if they are null at runtime. And UseKinComparator annotations are honored on kin set fields, so that if specified, the field will be initilized with a KinSet object constructed with that comparator.

Omitting initializations for kin set fields at application classes improves runtime performance, and is memory economic for fetus objects to be used unborn.

See the Object-Relation-Kin Model.

Author:

Compl

Constructor Summary

KinSet()
Construct a kin set with a FirstCreatedFirst comparator.

KinSet(Comparator<? extends Kin<?,?>> comparator)
Construct a kin set with sorting order determined by the comparator.

Method Summary

boolean	containsObject(TheObject p) Test whether a persistent object is referenced as the target object by at lease one kin in this kin set.
Iterable<T>	distinctObjects() Get a distinct set of related objects.
Comparator<? extends Kin<?,?>>	getComparator() Get the comparator used to sort this kin set.
boolean	isEmpty() Test whether this set is empty.
Iterator<Kin<R,T>>	iterator() Get a snapshot iterator of this kin set.
int	size() Get how many kins in this set.
List<Kin<R,T>>	toList() Get a snapshot of this kin set, as a list of kins.

Methods inherited from class java.lang.Object

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

Constructor Detail

KinSet

public KinSet()

Construct a kin set with a FirstCreatedFirst comparator.

KinSet

public KinSet(Comparator<? extends Kin<?,?>> comparator)

Construct a kin set with sorting order determined by the comparator. If null is specified here as the comparator, a FirstCreatedFirst comparator will be used.

Note:

1. The comparator is required to produce consistent comparation results regardless of the persistent states changes of the compared Kins. That is, only immutable attributes should be used to perform the comparation. The persistent object ID, the creation time of both the source relation object and the related object are good candidates. And values of some persistent fields, e.g. a Person object's Gender value, can be used if they are guarannteed not to change.
2. Even if the comparator reports that a kin equals to another existing one already in the kin set, adding the new kin to the kin set will not overwrite the existing one. In this case the order of such equal kins is undefined.

Parameters:

comparator - A comparator used to sort kins in this set

Method Detail

size

public int size()

Get how many kins in this set.

Returns:

number of kins in this set

isEmpty

public boolean isEmpty()

Test whether this set is empty.

Returns:

true if this set has no kin, false otherwise

toList

public List<Kin<R,T>> toList()

Get a snapshot of this kin set, as a list of kins.

The returned list is immutable.

Returns:

a snapshot list of kins currently in this set

iterator

public Iterator<Kin<R,T>> iterator()

Get a snapshot iterator of this kin set.

The returned iterator is immutable.

Specified by:

iterator in interface Iterable<Kin<R extends TheRelation,T extends TheObject>>

distinctObjects

public Iterable<T> distinctObjects()

Get a distinct set of related objects.

Returns:

an distinct set of related objects

containsObject

public boolean containsObject(TheObject p)

Test whether a persistent object is referenced as the target object by at lease one kin in this kin set.

Parameters:

p - a persistent object

Returns:

whether this kin set contains one or more kins taking p as the related object

getComparator

public Comparator<? extends Kin<?,?>> getComparator()

Get the comparator used to sort this kin set.

Returns:

the comparator of this kin set