goldman.collection.tagged.bucket
Interface TaggedBucketCollection<T,E>

All Superinterfaces:
Iterable<TaggedElement<T,Collection<E>>>
All Known Implementing Classes:
TaggedBucketCollectionWrapper

public interface TaggedBucketCollection<T,E>
extends Iterable<TaggedElement<T,Collection<E>>>

In a tagged bucket collection, the elements are bucketed into sets based on their tags. The semantics of put is modified to put a new bucket into the collection when the given tag is not yet in use. The new bucket is created by a bucket factory, which gives the application the flexibility to specify the collection type of the bucket. This can be done either by providing a bucket factory to the constructor, or by providing the constructor with a class to be instantiated when a new bucket is required. When the given tag is already in use, then the element is simply added to the existing bucket. Likewise, when an element is removed form a bucket of size 1, then the tag is also removed. In a tagged collection, the cost associated with locating a desired element generally depends on the number of tagged elements in the collection, whereas the cost associated with locating a desired element generally depends on the number of unique tags.


Method Summary
 void accept(Visitor<TaggedElement<T,Collection<E>>> v)
          Traverses each element of this collection, in the iteration order, on behalf of the visitor.
 int bucketSize(T tag)
          Returns the number of elements with the given tag.
 void clear()
          Removes all tagged elements from this tagged bucket collection.
 boolean contains(T tag)
          Returns true if an equivalent tag exists in this tagged bucket collection.
 void ensureCapacity(int capacity)
          Increases the capacity of this tagged collection, if necessary, to ensure that it can hold at least capacity distinct tags.
 Collection<E> get(T tag)
          Returns a collection of all elements with the given tag.
 int getCapacity()
          Returns the current capacity (in terms of the number of tags) of this tagged collection.
 Locator<E> getElements(T tag)
          Returns a locator positioned at FORE within the bucket associated with the given tag, or an iterator over an empty bucket if the tag is not in use.
 int getNumTags()
          Returns the number of distinct tags used in this collection.
 int getSize()
          Returns the number of elements, size, in this collection.
 boolean isEmpty()
          Returns true if this collection contains no elements, and otherwise returns false.
 Iterator<TaggedElement<T,Collection<E>>> iterator()
          Returns an iterator initialized at FORE that may be used to iterate over the tags and their associated buckets.
 void put(T tag, E element)
          This method creates a new tagged element with the given values and inserts this tagged element into this collection.
 E remove(T tag)
          Removes from this tagged collection an arbitrary element with the given tag.
 boolean remove(T tag, E element)
          Removes from this tagged collection an element equivalent to the given element with the given tag.
 Collection<E> removeBucket(T tag)
          Removes and returns the bucket associated with the given tag.
 String toString()
          Returns a string that describes each tagged element in the collection, as produced by the toString method for that element, in the iteration order.
 void trimToSize()
          Trims the capacity of this tagged bucket collection to be its current size.
 

Method Detail

accept

void accept(Visitor<TaggedElement<T,Collection<E>>> v)
Traverses each element of this collection, in the iteration order, on behalf of the visitor. The visitor sees a tagged element for each tag and its associated bucket.


clear

void clear()
Removes all tagged elements from this tagged bucket collection.


contains

boolean contains(T tag)
Returns true if an equivalent tag exists in this tagged bucket collection. Otherwise, false is returned.


ensureCapacity

void ensureCapacity(int capacity)
Increases the capacity of this tagged collection, if necessary, to ensure that it can hold at least capacity distinct tags.


get

Collection<E> get(T tag)
Returns a collection of all elements with the given tag. This method requires that tag be in use and will throw a NoSuchElementException otherwise.


getElements

Locator<E> getElements(T tag)
Returns a locator positioned at FORE within the bucket associated with the given tag, or an iterator over an empty bucket if the tag is not in use.


getCapacity

int getCapacity()
Returns the current capacity (in terms of the number of tags) of this tagged collection.


getSize

int getSize()
Returns the number of elements, size, in this collection.


getNumTags

int getNumTags()
Returns the number of distinct tags used in this collection.


bucketSize

int bucketSize(T tag)
Returns the number of elements with the given tag.


isEmpty

boolean isEmpty()
Returns true if this collection contains no elements, and otherwise returns false.


iterator

Iterator<TaggedElement<T,Collection<E>>> iterator()
Returns an iterator initialized at FORE that may be used to iterate over the tags and their associated buckets.

Specified by:
iterator in interface Iterable<TaggedElement<T,Collection<E>>>

put

void put(T tag,
         E element)
This method creates a new tagged element with the given values and inserts this tagged element into this collection. If there is already an element with an equivalent tag, then element is added to the bucket. Otherwise, a new bucket is created for tag, and element is placed in that bucket. An AtCapacityException, an unchecked exception, is thrown if the collection is already at capacity.


remove

E remove(T tag)
Removes from this tagged collection an arbitrary element with the given tag. It returns the element that was removed, and \tagthrows{NoSuchElementException}{there is no element with an equivalent tag.}


remove

boolean remove(T tag,
               E element)
Removes from this tagged collection an element equivalent to the given element with the given tag. It returns true if an equivalent element with the given tag was found, and otherwise returns false.


removeBucket

Collection<E> removeBucket(T tag)
Removes and returns the bucket associated with the given tag.


toString

String toString()
Returns a string that describes each tagged element in the collection, as produced by the toString method for that element, in the iteration order.

Overrides:
toString in class Object

trimToSize

void trimToSize()
Trims the capacity of this tagged bucket collection to be its current size. An application can use this operation to minimize the space usage. For elastic implementations, this method does nothing.