goldman.collection.tagged.bucket
Class TaggedBucketCollectionWrapper<T,E>

java.lang.Object
  extended by goldman.collection.tagged.bucket.TaggedBucketCollectionWrapper<T,E>
All Implemented Interfaces:
TaggedBucketCollection<T,E>, Iterable<TaggedElement<T,Collection<E>>>

public class TaggedBucketCollectionWrapper<T,E>
extends Object
implements TaggedBucketCollection<T,E>

The tagged bucket wrapper is implemented as a wrapper for any tagged collection, where each tag is placed in the wrapped collection only once, and the associated element for each tag is a bucket object of any collection type. An important distinction is that the size of a wrapped tagged collection only depends upon the number of distinct tags. Thus, for the time complexity of all methods delegated to the wrapped tagged collection, n is the number of distinct tags. However, from the view of the application, the size of a tagged bucket collection is the number of elements, not the number of tags.


Field Summary
protected  BucketFactory<E> factory
           
protected  TaggedCollection<T,Collection<E>> tc
           
 
Constructor Summary
TaggedBucketCollectionWrapper(TaggedCollection<T,Collection<E>> tc, BucketFactory<E> factory)
           
TaggedBucketCollectionWrapper(TaggedCollection<T,Collection<E>> tc, Class bucketType)
           
 
Method Summary
 void accept(Visitor<TaggedElement<T,Collection<E>>> v)
          Traverses the entire collection on behalf of a visitor.
 int bucketSize(T tag)
          Returns the number of elements with the given tag.
 void clear()
          Removes all elements from this 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.
 TaggedCollection<T,Collection<E>> getTaggedCollection()
           
 boolean isEmpty()
          Returns true if this collection contains no elements, and otherwise returns false.
 Iterator<TaggedElement<T,Collection<E>>> iterator()
          Creates a new iterator that is at FORE.
 void put(T tag, E data)
          Adds data to the bucket for the given tag.
 void putAll(TaggedCollection<T,E> tc)
           
 Locator<E> putTracked(T tag, E data)
          Associates data with the given tag by adding it to the bucket (which is created if it does not exist) for tag.
 E remove(T tag)
          Removes the first element in the bucket for that tag, according to the iteration order
 boolean remove(T tag, E element)
          Removes the specified element from the bucket associated with the given tag (if it exists in that bucket).
 Collection<E> removeBucket(T tag)
          Removes all elements from this tagged bucket collection that are 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

tc

protected TaggedCollection<T,Collection<E>> tc

factory

protected BucketFactory<E> factory
Constructor Detail

TaggedBucketCollectionWrapper

public TaggedBucketCollectionWrapper(TaggedCollection<T,Collection<E>> tc,
                                     BucketFactory<E> factory)
Parameters:
tc - the (empty) tagged collection from T to buckets that is to be wrapped
factory - a bucket factory that is used to create a bucket for each new tag

TaggedBucketCollectionWrapper

public TaggedBucketCollectionWrapper(TaggedCollection<T,Collection<E>> tc,
                                     Class bucketType)
Parameters:
tc - the tagged collection from T to buckets that is to be wrapped
bucketType - a class of the appropriate collection type for the buckets
REQUIRES: the provided class bucketType implement the Collection interface
Method Detail

getTaggedCollection

public TaggedCollection<T,Collection<E>> getTaggedCollection()
Returns:
the underlying tagged collection used by this wrapper

getNumTags

public int getNumTags()
Description copied from interface: TaggedBucketCollection
Returns the number of distinct tags used in this collection.

Specified by:
getNumTags in interface TaggedBucketCollection<T,E>
Returns:
the number of tags held in the mapping

isEmpty

public boolean isEmpty()
Description copied from interface: TaggedBucketCollection
Returns true if this collection contains no elements, and otherwise returns false.

Specified by:
isEmpty in interface TaggedBucketCollection<T,E>
Returns:
true if and only if there are no elements in the collection

getSize

public int getSize()
Description copied from interface: TaggedBucketCollection
Returns the number of elements, size, in this collection.

Specified by:
getSize in interface TaggedBucketCollection<T,E>
Returns:
the number of elements, among all buckets, held in this collection.

getCapacity

public int getCapacity()
Description copied from interface: TaggedBucketCollection
Returns the current capacity (in terms of the number of tags) of this tagged collection.

Specified by:
getCapacity in interface TaggedBucketCollection<T,E>
Returns:
the capacity (in terms of the number of tags).

contains

public boolean contains(T tag)
Description copied from interface: TaggedBucketCollection
Returns true if an equivalent tag exists in this tagged bucket collection. Otherwise, false is returned.

Specified by:
contains in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
Returns:
true if and only if there is a bucket associated with the given tag.

get

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

Specified by:
get in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
Returns:
the bucket holding the elements associated with the given tag.
Throws:
NoSuchElementException - tag is not in use

getElements

public Locator<E> getElements(T tag)
Description copied from interface: TaggedBucketCollection
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.

Specified by:
getElements in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
Returns:
a locator positioned to just before the first element in the bucket associated with the given tag. For convenience when the tag is not in use, an iterator for an empty bucket is returned.

toString

public String toString()
Description copied from interface: TaggedBucketCollection
Returns a string that describes each tagged element in the collection, as produced by the toString method for that element, in the iteration order.

Specified by:
toString in interface TaggedBucketCollection<T,E>
Overrides:
toString in class Object
Returns:
a string representation for the bucket mapping, in keeping with the toString methods of the wrapped tagged collection and the bucket type

accept

public void accept(Visitor<TaggedElement<T,Collection<E>>> v)
Traverses the entire collection on behalf of a visitor.

Specified by:
accept in interface TaggedBucketCollection<T,E>
Parameters:
v - a visitor
Throws:
VisitAbortedException - the traversal is aborted due to an exception raised by the visitor, in which case the cause held by the VisitAbortedException is the exception thrown by the visitor.

bucketSize

public int bucketSize(T tag)
Description copied from interface: TaggedBucketCollection
Returns the number of elements with the given tag.

Specified by:
bucketSize in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
Returns:
the number of elements associated with tag (which by definition is 0 when the tag is not in use)

ensureCapacity

public void ensureCapacity(int capacity)
Description copied from interface: TaggedBucketCollection
Increases the capacity of this tagged collection, if necessary, to ensure that it can hold at least capacity distinct tags.

Specified by:
ensureCapacity in interface TaggedBucketCollection<T,E>

trimToSize

public void trimToSize()
Description copied from interface: TaggedBucketCollection
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.

Specified by:
trimToSize in interface TaggedBucketCollection<T,E>

put

public void put(T tag,
                E data)
Adds data to the bucket for the given tag. If no bucket exists for the given tag, a bucket is created using the provided factory.

Specified by:
put in interface TaggedBucketCollection<T,E>
Parameters:
tag - the tag for the new element
data - the associated data

putTracked

public Locator<E> putTracked(T tag,
                             E data)
Associates data with the given tag by adding it to the bucket (which is created if it does not exist) for tag.

Parameters:
tag - the tag for the new element
data - the associated data
Returns:
a tracker in the bucket for the newly added element
Throws:
UnsupportedOperationException - the bucket type does not implement the Tracked interface

putAll

public void putAll(TaggedCollection<T,E> tc)
Parameters:
tc - the tagged collection to be added to this collection

remove

public E remove(T tag)
Removes the first element in the bucket for that tag, according to the iteration order

Specified by:
remove in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
Returns:
the element removed.
Throws:
NoSuchElementException - there are no elements associated with the given tag

remove

public boolean remove(T tag,
                      E element)
Removes the specified element from the bucket associated with the given tag (if it exists in that bucket).

Specified by:
remove in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
element - the associated element to remove
Returns:
true if and only if the element was found in the specified bucket and removed

removeBucket

public Collection<E> removeBucket(T tag)
Removes all elements from this tagged bucket collection that are associated with the given tag.

Specified by:
removeBucket in interface TaggedBucketCollection<T,E>
Parameters:
tag - the target tag
Returns:
the bucket that had been associated with the tag
Throws:
NoSuchElementException - there is no bucket for the given tag.

clear

public void clear()
Removes all elements from this collection.

Specified by:
clear in interface TaggedBucketCollection<T,E>

iterator

public Iterator<TaggedElement<T,Collection<E>>> iterator()
Creates a new iterator that is at FORE.

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