wt.fc.collections
Interface WTCollection

All Superinterfaces:

Collection, Iterable

All Known Subinterfaces:

WTList, WTSet

All Known Implementing Classes:

wt.fc.collections.AbstractWTCollection, wt.fc.collections.AbstractWTList, WTArrayList, WTHashSet

public interface WTCollection
extends Collection

A Collection that provides QueryKey, WTReference, and Persistable-based views of its data.

WTCollections can be optimally refreshed using the CollectionsManager refresh API.

Supported API: true

Extendable: false

See Also:

CollectionsManager, Collection

Method Summary

boolean	add(Object o) Adds the given QueryKey, WTReference, Persistable or collection thereof.
boolean	add(Persistable p) Adds the given object to this collection.
boolean	add(QueryKey query_key) Adds the given object to this collection.
boolean	add(WTReference ref) Adds the given object to this collection.
boolean	addAll(Collection c) Adds the given collection of objects to this collection.
boolean	addAll(QueryResult qr) Adds the contents of a QueryResult to this collection.
Iterator	classIterator() Returns an iterator over the classes that have instances in this collection.
boolean	connect(Persistable p, WTCollection source, boolean add_if_not_present) Connects the given object from the source collection to this collection.
boolean	connect(QueryKey query_key, WTCollection source, boolean add_if_not_present) Connects the given object from the source collection to this collection.
boolean	connect(WTReference ref, WTCollection source, boolean add_if_not_present) Connects the given object from the source collection to this collection.
boolean	connectAll(WTCollection source, boolean add_if_not_present) Connects the elements in the source collection to this collection.
boolean	contains(Object o) Returns true if the collection contains the given QueryKey, WTReference, or Persistable, in any form.
boolean	contains(Persistable p) Determines if the collection contains the given object in some form.
boolean	contains(QueryKey query_key) Determines if the collection contains the given object in some form.
boolean	contains(WTReference ref) Determines if the collection contains the given object in some form.
boolean	containsInstance(Class filter) Returns true if there is at least one object in the collection that the filter class is assignable from.
boolean	containsOnly(Class filter) Determines whether this collection only contains objects that are assignable from the given filter.
void	deflate() Dereferences all Persistables in this collection that have QueryKeys.
int	getKeyMask() Returns this collection's key mask.
void	inflate() Retrieves the full persistables for any objects in this collection that currently only have QueryKeys or WTReferences.
boolean	isEnabled(int mask) Returns true if the key types in the given mask are enabled for this collection.
Iterator	iterator() Returns an iterator over the references in the collection, per the contract of the referenceIterator() API.
Collection	persistableCollection() Provides a Persistable-based view of the objects in this WTCollection.
Iterator	persistableIterator() Returns an iterator over the objects in this collection, as Persistables.
Iterator	queryKeyIterator() Returns an iterator over the QueryKeys in this collection.
Iterator	referenceIterator() Returns an Iterator over the objects in this collection, as WTReferences.
boolean	remove(Object o) Removes any form of the object in the collection.
boolean	remove(Persistable p) Removes the object from this collection.
boolean	remove(QueryKey query_key) Removes the object from this collection.
boolean	remove(WTReference ref) Removes the object from this collection.
boolean	removeAll(Class filter, boolean include_subclasses) Removes all objects in this collection that are assignable from the given class.
boolean	retainAll(Class filter, boolean include_subclasses) Removes all objects in this collection that are not assignable from the given class.
WTCollection	subCollection(Class filter, boolean include_subclasses) Returns a sub collection of all the objects in this collection that are either direct or descendent instances of the filter class, depending on the value of include_subclasses.
Object[]	toArray() Returns an object array filled with WTReferences to all the objects in this collection.
long[]	toArray(long[] array) Fills the given array with the long ids from each QueryKey in this collection.
Object[]	toArray(Object[] array) Fills the given array with the objects in this collection.
Persistable[]	toArray(Persistable[] array) Fills the given array with the Persistables in this collection.
QueryKey[]	toArray(QueryKey[] array) Fills the given array with the QueryKeys in this collection.
WTReference[]	toArray(WTReference[] array) Fills the given array with WTReferences to all the objects in this collection.
long[]	toIdArray() Returns an array with the long ids from each QueryKey in this collection.

Methods inherited from interface java.util.Collection

clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, size

Method Detail

add

boolean add(Object o)

Adds the given QueryKey, WTReference, Persistable or collection thereof. Add is overloaded with type-specific methods to allow callers to avoid the overhead of an instanceof check. The generic add() delegates to the appropriate type-specific one.

The persistable and reference versions of add will also add the given object's QueryKey to the collection, if the object is persisted.

Supported API: true

Specified by:

add in interface Collection

Parameters:

o -

Returns:

true if the collection is modified as a result of this operation

Throws:

ClassCastException - If a QueryKey or WTReference is added that doesn't match the collection's key mask. By default, only accepts ObjectIdentifiers and ObjectReferences. However, if the collection has the CollectionsHelper.VERSION_FOREIGN_KEY key type enabled, then only VersionForeignKeys and VersionReferences are accepted for Iterated objects. For other object types, ObjectIdentifiers and ObjectReferences are still accepted. The enabled key types are determined by calling the isEnabled(int) method.

ClassCastException - If a WTReference is added that isn't the best match for a given object type. For example, AdminDomainRef should be used when adding a reference to an AdministrativeDomain, rather than ObjectReference. The appropriate reference type may change depending upon the collection's key type - WTParts, for example, should be added by ObjectReference with the default key type, but by VersionReference when the VERSION_FOREIGN_KEY type is enabled.

add

boolean add(Persistable p)

Adds the given object to this collection. See add(Object) for documentation for this method.

Supported API: true

Parameters:

p -

Returns:

true if the collections is modified as a result of this operation

add

boolean add(QueryKey query_key)

Adds the given object to this collection. See add(Object) for documentation for this method.

Supported API: true

Parameters:

query_key -

Returns:

true if the collection is modified as a result of this operation

add

boolean add(WTReference ref)

Adds the given object to this collection. See add(Object) for documentation for this method.

Supported API: true

Parameters:

ref -

Returns:

true if the collection is modified as a result of this operation

addAll

boolean addAll(Collection c)

Adds the given collection of objects to this collection. If the given collection is a WTCollection, then the implementation should attempt to copy as much state from the collection to this collection. For example, the implementation should copy all inflated persistables and references from the given collection. See add(Object) for documentation for this method.

Supported API: true

Specified by:

addAll in interface Collection

Parameters:

c -

Returns:

true if the collection is modified as a result of this operation

addAll

boolean addAll(QueryResult qr)

Adds the contents of a QueryResult to this collection.

Supported API: true

Parameters:

qr -

Returns:

true if the operation modifies this collection

Throws:

IllegalArgumentException - If the elements in the QueryResult are not one of he following types:

• Persistables
• Object arrays with a single Persistable element
• 2-element Object arrays with a classname and an id, in that order

classIterator

Iterator classIterator()

Returns an iterator over the classes that have instances in this collection. A remove() from the iterator removes all the instances of the class from the collection.

Supported API: true

Returns:

An iterator of Class objects

Throws:

ConcurrentModificationException - If the collection is modified while the iterator is being processed.

connect

boolean connect(Persistable p,
                WTCollection source,
                boolean add_if_not_present)

Connects the given object from the source collection to this collection. When the object is inflated or refreshed in the source, it is also inflated or refreshed in this collection, and vice versa. If add_if_not_present is true, then if the object does not exist yet in this collection, it is added to it.

Supported API: true

Parameters:

p -

source -

add_if_not_present - When true, the object is added to this collection if it isn't currently contained by it.

Returns:

true If the object was added to the collection

Throws:

IllegalArgumentException - If the source does not have the same key type as this collection

ClassCastException - If this collection does not support connection with the source's implementation of WTCollection.

See Also:

connect(Persistable,WTCollection,boolean)

connect

boolean connect(QueryKey query_key,
                WTCollection source,
                boolean add_if_not_present)

Connects the given object from the source collection to this collection. When the object is inflated or refreshed in the source, it is also inflated or refreshed in this collection, and vice versa. If add_if_not_present is true, then if the object does not exist yet in this collection, it is added to it.

Supported API: true

Parameters:

query_key -

source -

add_if_not_present - When true, the object is added to this collection if it isn't currently contained by it.

Returns:

true If this collection was modified by the operation

Throws:

IllegalArgumentException - If the source does not have the same key type as this collection

ClassCastException - If this collection does not support connection with the source's implementation of WTCollection.

See Also:

connect(QueryKey,WTCollection,boolean)

connect

boolean connect(WTReference ref,
                WTCollection source,
                boolean add_if_not_present)

Connects the given object from the source collection to this collection. When the object is inflated or refreshed in the source, it is also inflated or refreshed in this collection, and vice versa. If add_if_not_present is true, then if the object does not exist yet in this collection, it is added to it.

Supported API: true

Parameters:

ref -

source -

add_if_not_present - When true, the object is added to this collection if it isn't currently contained by it.

Returns:

true If this collection was modified by the operation

Throws:

IllegalArgumentException - If the source does not have the same key type as this collection

ClassCastException - If this collection does not support connection with the source's implementation of WTCollection.

See Also:

connect(WTReference,WTCollection,boolean)

connectAll

boolean connectAll(WTCollection source,
                   boolean add_if_not_present)

Connects the elements in the source collection to this collection. When an object is inflated or refreshed in source, it is also inflated or refreshed in this collection, and vice versa. When add_if_not_present is true, all of the objects in the source collection are added to this collection.

Supported API: true

Parameters:

source -

add_if_not_present - When true, objects in source that aren't currently in this collection are added to this collection.

Returns:

true If the operation modifies this collection.

Throws:

IllegalArgumentException - If connect is true and source does not have the same key type as this collection

ClassCastException - If this collection does not support connection with the source''s implementation of WTCollection.

contains

boolean contains(Object o)

Returns true if the collection contains the given QueryKey, WTReference, or Persistable, in any form. Thus if the collection contained only an ObjectIdentifier for an object, and the method is passed the oid's corresponding Persistable, then the result will be true.

Contains is overloaded with type-specific methods to allow callers to avoid the overhead of an instanceof check. The generic contains() delegates to the appropriate type-specific one.

Supported API: true

Specified by:

contains in interface Collection

Parameters:

o -

Returns:

boolean

contains

boolean contains(Persistable p)

Determines if the collection contains the given object in some form. See contains(Object) for further documentation.

Supported API: true

Parameters:

p -

Returns:

true if the collection contains this object

contains

boolean contains(QueryKey query_key)

Determines if the collection contains the given object in some form. See contains(Object) for further documentation.

Supported API: true

Parameters:

query_key -

Returns:

true if the collection contains this object

contains

boolean contains(WTReference ref)

Determines if the collection contains the given object in some form. See contains(Object) for further documentation.

Supported API: true

Parameters:

ref -

Returns:

true if the collection contains this object

containsInstance

boolean containsInstance(Class filter)

Returns true if there is at least one object in the collection that the filter class is assignable from.

Supported API: true

Parameters:

filter -

Returns:

boolean

containsOnly

boolean containsOnly(Class filter)

Determines whether this collection only contains objects that are assignable from the given filter.

Supported API: true

Parameters:

filter -

Returns:

boolean

deflate

void deflate()

Dereferences all Persistables in this collection that have QueryKeys. Also deflates any WTReferences in this collection. References to non-persisted Persistables are preserved.

Supported API: true

getKeyMask

int getKeyMask()

Returns this collection's key mask. The key mask is a combination of the constants defined in CollectionsHelper.

Supported API: true

Returns:

int

See Also:

CollectionsHelper.OBJECT_IDENTIFIER, CollectionsHelper.VERSION_FOREIGN_KEY

inflate

void inflate()
             throws WTException

Retrieves the full persistables for any objects in this collection that currently only have QueryKeys or WTReferences. The WTReferences are inflated with the new object. Existing Persistables in the collection are not refreshed.

Supported API: true

Throws:

WTException

isEnabled

boolean isEnabled(int mask)

Returns true if the key types in the given mask are enabled for this collection.

Supported API: true

Parameters:

mask -

Returns:

boolean

See Also:

getKeyMask()

iterator

Iterator iterator()

Returns an iterator over the references in the collection, per the contract of the referenceIterator() API.

Supported API: true

Specified by:

iterator in interface Collection

Specified by:

iterator in interface Iterable

Returns:

An iterator of WTReferences.

Throws:

ConcurrentModificationException - If the collection is modified while the iterator is being processed.

persistableCollection

Collection persistableCollection()

Provides a Persistable-based view of the objects in this WTCollection. This means the iterator method returns Persistables, and the contains and remove operations only work with Persistable arguments.

The resulting collection is backed by this collection, so changes to one are reflected in the other.

Supported API: true

Returns:

A Collection of Persistables

persistableIterator

Iterator persistableIterator()
                             throws WTException

Returns an iterator over the objects in this collection, as Persistables. Inflates all the QueryKeys and references in this collection that don't have Persistables yet. Persistables that are already in the collection are not refreshed.

Supported API: true

Returns:

An iterator of Persistables

Throws:

ConcurrentModificationException - If the collection is modified while the iterator is being processed.

WTException

queryKeyIterator

Iterator queryKeyIterator()

Returns an iterator over the QueryKeys in this collection. These will typically be ObjectIdentifiers, but may be other QueryKey types depending on how the collection is constructed. Nonpersisted objects will not be included in the id iterator.

Supported API: true

Returns:

An iterator of QueryKeys

Throws:

ConcurrentModificationException - If the collection is modified while the iterator is being processed.

referenceIterator

Iterator referenceIterator()

Returns an Iterator over the objects in this collection, as WTReferences. The precise subclass of WTReference is determined by the referenced class, and by this collection's key mask. The references in the iterator may or may not be inflated, depending upon how they were added to the collection and when the collection was last refreshed. Non-persisted objects will still have references in the iterator; they will have null keys.

Supported API: true

Returns:

An iterator of WTReferences

Throws:

ConcurrentModificationException - If the collection is modified while the iterator is being processed.

remove

boolean remove(Object o)

Removes any form of the object in the collection. So if remove is passed a Persistable, but the collection only contained a QueryKey for the Persistable, that QueryKey is removed and the method returns true.

Remove is overloaded with type-specific methods to allow callers to avoid the overhead of an instanceof check. The generic remove() delegates to the appropriate type-specific one.

Supported API: true

Specified by:

remove in interface Collection

Parameters:

o -

Returns:

true if the operation modifies this collection

remove

boolean remove(Persistable p)

Removes the object from this collection. See remove(Object) for further documentation. Removes the object from this collection. See remove(Object) for further documentation.

Supported API: true

Parameters:

p -

Returns:

true if the operation modifies this collection

remove

boolean remove(QueryKey query_key)

Removes the object from this collection. See remove(Object) for further documentation. See remove(Object) for further documentation.

Supported API: true

Parameters:

query_key -

Returns:

true if the operation modifies this collection

remove

boolean remove(WTReference ref)

Removes the object from this collection. See remove(Object) for further documentation. See remove(Object) for further documentation.

Supported API: true

Parameters:

ref -

Returns:

true if the operation modifies this collection

removeAll

boolean removeAll(Class filter,
                  boolean include_subclasses)

Removes all objects in this collection that are assignable from the given class.

Supported API: true

Parameters:

filter -

include_subclasses -

Returns:

true if the operation modifies this collection

retainAll

boolean retainAll(Class filter,
                  boolean include_subclasses)

Removes all objects in this collection that are not assignable from the given class.

Supported API: true

Parameters:

filter -

include_subclasses -

Returns:

true if the operation modifies this collection

subCollection

WTCollection subCollection(Class filter,
                           boolean include_subclasses)

Returns a sub collection of all the objects in this collection that are either direct or descendent instances of the filter class, depending on the value of include_subclasses. The resulting collection is backed by this collection; modifications to one are reflected in the other. Refreshes to the subcollection should not result in the refresh of the entire collection.

Supported API: true

Parameters:

filter -

include_subclasses -

Returns:

A WTCollection of the same interface type as this WTCollection. For example, if this collection is a WTSet, then the subcollection will also be a WTSet.

Throws:

ClassCastException - If an attempt is made to add an object that is not assignable from the subcollection's filter

toArray

Object[] toArray()

Returns an object array filled with WTReferences to all the objects in this collection.

Supported API: true

Specified by:

toArray in interface Collection

Returns:

An array of type Object[] filled with WTReferences

toArray

Object[] toArray(Object[] array)

Fills the given array with the objects in this collection. If the array is of type Persistable[], QueryKey[], or WTReference[], then the corresponding type-specific toArray() is called. Otherwise the array is filled with WTReferences.

Supported API: true

Specified by:

toArray in interface Collection

Parameters:

array -

Returns:

Object[]

toArray

Persistable[] toArray(Persistable[] array)

Fills the given array with the Persistables in this collection. Inflates all QueryKeys in the collection that don't yet have corresponding Persistables.

Supported API: true

Parameters:

array -

Returns:

Persistable[]

toArray

QueryKey[] toArray(QueryKey[] array)

Fills the given array with the QueryKeys in this collection.

Supported API: true

Parameters:

array -

Returns:

QueryKey[]

toArray

WTReference[] toArray(WTReference[] array)

Fills the given array with WTReferences to all the objects in this collection.

Supported API: true

Parameters:

array -

Returns:

WTReference[]

toArray

long[] toArray(long[] array)

Fills the given array with the long ids from each QueryKey in this collection.

Supported API: true

Parameters:

array -

Returns:

long[]

toIdArray

long[] toIdArray()

Returns an array with the long ids from each QueryKey in this collection.

Supported API: true

Returns:

long[]