Package wt.fc.collections

Interface WTCollection

All Superinterfaces:
Collection, Iterable
All Known Subinterfaces:
wt.facade.dataops.objectcol.BaseCollectionGraph, CollectionGraph, 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:

  • Method Summary

    Modifier and Type
    Method
    Description
    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, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray

    Methods inherited from interface java.lang.Iterable

    forEach

  • Method Details

    • 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

      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

      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:

    • 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:

    • 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:

    • 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[]