Side of Software
Dated Collections Library 2.0

sos.dated.util
Class HashSetByElement<E,D>

java.lang.Object
  extended by sos.dated.util.AbstractDatedObject<D>
      extended by sos.dated.util.AbstractDatedCollection<E,D>
          extended by sos.dated.util.AbstractDatedSet<E,D>
              extended by sos.dated.util.HashSetByElement<E,D>
Type Parameters:
E - the type of elements maintained by this dated set
D - the type of dates used by this dated set
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, DatedCollection<E,D>, DatedObject<D>, DatedSet<E,D>

public class HashSetByElement<E,D>
extends AbstractDatedSet<E,D>
implements DatedSet<E,D>, java.io.Serializable, java.lang.Cloneable

An implementation of DatedSet that uses a HashMapByKey as its underlying data structure. The following illustration shows a conceptual view of a small HashSetByElement where the "dates" are integers and the elements are characters:

In the above picture, the dated set contains the following elements for the following ranges:
   [1,2): {K,B,M}
   [3,5): {K,A,B,M}
   [5,6): {M}
   [6,9): {K,A,B}
This implementation is serializable and cloneable; however, it is not synchronized. To use it safely in a multi-threaded situation, wrap an instance of the dated set with a call to DatedCollections.synchronizedDatedSet.

Since:
1.0
See Also:
HashSetByDate, TreeSetByElement, DatedSet, HashMapByKey, DatedCollections.synchronizedDatedSet(DatedSet)

Constructor Summary
HashSetByElement()
          Creates a new instance of HashSetByElement.
HashSetByElement(DatedCollection<? extends E,D> datedCollection)
          Creates a new instance of HashSetByElement initialized with the elements and dates of the specified dated collection.
HashSetByElement(int initialCapacity)
          Creates a new instance of HashSetByElement with the specified initial capacity and default load factor (0.75).
HashSetByElement(int initialCapacity, float loadFactor)
          Creates a new instance of HashSetByElement with the specified initial capacity and load factor.
 
Method Summary
 Dates<D> add(E value, D from, D to)
          Adds the specified element to this dated collection for the specified date range.
 void clear(D from, D to)
          Removes all elements from this dated collection for the specified dates.
 java.lang.Object clone()
          Creates and returns a shallow copy of this object.
 boolean contains(java.lang.Object value, D date)
          Returns true if this dated collection contains the specified element on the specified date.
 boolean containsThroughout(java.lang.Object value, D from, D to)
          Returns true if this dated collection contains the specified element throughout the specified date range.
 DateIterator<D> dateIterator(D at)
          Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date.
 boolean excludesThroughout(java.lang.Object value, D from, D to)
          Returns true if this dated collection does not contain the specified element at any date within the specified date range.
 boolean hasSizeThroughout(int size, D from, D to)
          Returns true if the number of elements in this dated collection is greater than or equal to the specified size throughout the specified date range.
 boolean isEmpty(D at)
          Returns true if this dated collection contains no elements on the specified date.
 boolean isEmptyThroughout(D from, D to)
          Returns true if this dated collection contains no elements throughout the specified date range.
 Iterator<E,D> iterator(D at)
          Returns an iterator over the elements of this dated collection at the specified date.
 Dates<D> remove(java.lang.Object value, D from, D to)
          Removes an instance of the specified element from this dated collection for the specified date range.
 int size(D at)
          Returns the number of elements in this dated collection at the specified date.
 
Methods inherited from class sos.dated.util.AbstractDatedSet
equals, hashCode
 
Methods inherited from class sos.dated.util.AbstractDatedCollection
addAll, containsAll, removeAll, retainAll, toArray, toArray, toString
 
Methods inherited from class sos.dated.util.AbstractDatedObject
dateIterator, equals, hashCode, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface sos.dated.util.DatedSet
equals, hashCode
 
Methods inherited from interface sos.dated.util.DatedCollection
add, addAll, clear, contains, containsAll, containsThroughout, excludesThroughout, hasSizeThroughout, isEmpty, isEmptyThroughout, iterator, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface sos.dated.util.DatedObject
dateIterator, dateIterator, equals, hashCode, toString
 

Constructor Detail

HashSetByElement

public HashSetByElement()
Creates a new instance of HashSetByElement.


HashSetByElement

public HashSetByElement(int initialCapacity)
Creates a new instance of HashSetByElement with the specified initial capacity and default load factor (0.75). The initial capacity is used to initialize the underlying HashMapByKey, which holds all elements across all time.

Parameters:
initialCapacity - initial capacity of the underlying hash map
Throws:
java.lang.IllegalArgumentException - if initialCapacity < 0

HashSetByElement

public HashSetByElement(int initialCapacity,
                        float loadFactor)
Creates a new instance of HashSetByElement with the specified initial capacity and load factor.

Parameters:
initialCapacity - load capacity of the underlying hash map
loadFactor - load factor of the underlying hash map
Throws:
java.lang.IllegalArgumentException - if initialCapacity < 0 or if loadFactor <= 0.0

HashSetByElement

public HashSetByElement(DatedCollection<? extends E,D> datedCollection)
Creates a new instance of HashSetByElement initialized with the elements and dates of the specified dated collection.

Parameters:
datedCollection - collection with which to initialize the new HashSetByElement
Method Detail

clone

public java.lang.Object clone()
Creates and returns a shallow copy of this object.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this instance

add

public Dates<D> add(E value,
                    D from,
                    D to)
Adds the specified element to this dated collection for the specified date range.

Specified by:
add in interface DatedCollection<E,D>
Overrides:
add in class AbstractDatedCollection<E,D>
Parameters:
value - element to add
from - starting date (inclusive) at which the element should be added
to - ending date (exclusive) at which the element should be added
Returns:
a series of date ranges indicating when the addition changed this dated collection
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

clear

public void clear(D from,
                  D to)
Removes all elements from this dated collection for the specified dates.

Specified by:
clear in interface DatedCollection<E,D>
Overrides:
clear in class AbstractDatedCollection<E,D>
Parameters:
from - starting date (inclusive) at which this dated collection should be cleared
to - ending date (exclusive) at which this dated collection should be cleared
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if if from or to is null

contains

public boolean contains(java.lang.Object value,
                        D date)
Returns true if this dated collection contains the specified element on the specified date.

Specified by:
contains in interface DatedCollection<E,D>
Overrides:
contains in class AbstractDatedCollection<E,D>
Parameters:
value - element whose presence is to be tested
date - date at which this collection is to be queried
Returns:
true if this dated collection contains the specified element on the specified date
Throws:
java.lang.NullPointerException - if at is null
See Also:
DatedCollection.containsThroughout(java.lang.Object, D, D)

containsThroughout

public boolean containsThroughout(java.lang.Object value,
                                  D from,
                                  D to)
Returns true if this dated collection contains the specified element throughout the specified date range.

Specified by:
containsThroughout in interface DatedCollection<E,D>
Overrides:
containsThroughout in class AbstractDatedCollection<E,D>
Parameters:
value - element whose presence is to be tested
from - starting date (inclusive) at which containment should be tested
to - ending date (exclusive) at which containment should be tested
Returns:
true if this dated collection contains the specified element throughout the specified date range
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
See Also:
DatedCollection.contains(java.lang.Object, D), DatedCollection.excludesThroughout(java.lang.Object, D, D)

dateIterator

public DateIterator<D> dateIterator(D at)
Description copied from interface: DatedObject
Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date. Throughout a range returned by the iterator, the state of the dated object must be the same. Also, the states of the dated object must be different in two consecutive ranges returned by the iterator. There are no gaps in the ranges returned by the iterator. That is, if a previous date range exists, then a call to nextFrom returns the same date as previousTo. Passing null as the argument will return an iterator positioned at the beginning of the sequence.

Specified by:
dateIterator in interface DatedObject<D>
Specified by:
dateIterator in class AbstractDatedCollection<E,D>
Parameters:
at - date to position the iteration
Returns:
an iterator of the dates of when this dated object has changed, positioned immediately before the date range that contains the specified date

excludesThroughout

public boolean excludesThroughout(java.lang.Object value,
                                  D from,
                                  D to)
Returns true if this dated collection does not contain the specified element at any date within the specified date range.

Specified by:
excludesThroughout in interface DatedCollection<E,D>
Overrides:
excludesThroughout in class AbstractDatedCollection<E,D>
Parameters:
value - element whose presence is to be tested
from - starting date (inclusive) at which exclusion should be tested
to - ending date (exclusive) at which exclusion should be tested
Returns:
true if this dated collection does not contain value at any date between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
See Also:
DatedCollection.containsThroughout(java.lang.Object, D, D)

hasSizeThroughout

public boolean hasSizeThroughout(int size,
                                 D from,
                                 D to)
Returns true if the number of elements in this dated collection is greater than or equal to the specified size throughout the specified date range.

Specified by:
hasSizeThroughout in interface DatedCollection<E,D>
Overrides:
hasSizeThroughout in class AbstractDatedCollection<E,D>
Parameters:
size - number of elements in question
from - starting date (inclusive) at which the size is to be compared
to - ending date (exclusive) at which the size is to be compared
Returns:
true if this dated collection has at least the specified size throughout the specified date range.
Throws:
java.lang.IllegalArgumentException - if size < 0 or if from does not precede to
java.lang.NullPointerException - if from or to is null
See Also:
DatedCollection.size(D), DatedCollection.isEmptyThroughout(D, D)

isEmpty

public boolean isEmpty(D at)
Returns true if this dated collection contains no elements on the specified date.

Specified by:
isEmpty in interface DatedCollection<E,D>
Overrides:
isEmpty in class AbstractDatedCollection<E,D>
Parameters:
at - date at which this dated collection is to be queried
Returns:
true if this dated collection contains no elements on the specified date
Throws:
java.lang.NullPointerException - if at is null

isEmptyThroughout

public boolean isEmptyThroughout(D from,
                                 D to)
Returns true if this dated collection contains no elements throughout the specified date range.

Specified by:
isEmptyThroughout in interface DatedCollection<E,D>
Overrides:
isEmptyThroughout in class AbstractDatedCollection<E,D>
Parameters:
from - starting date (inclusive) at which this dated collection is to be queried
to - ending date (exclusive) at which this dated collection is to be queried
Returns:
true if this dated collection contains no elements throughout the specified date range.
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
See Also:
DatedCollection.isEmpty(D)

iterator

public Iterator<E,D> iterator(D at)
Returns an iterator over the elements of this dated collection at the specified date. The returned iterator will always throw an UnsupportedOperationException in its remove method because a date range is required to remove an element from this dated collection.

Specified by:
iterator in interface DatedCollection<E,D>
Specified by:
iterator in class AbstractDatedCollection<E,D>
Parameters:
at - date at which to iterate through the elements
Returns:
an iterator over the elements of this dated collection at the specified date.
Throws:
java.lang.NullPointerException - if at is null

remove

public Dates<D> remove(java.lang.Object value,
                       D from,
                       D to)
Removes an instance of the specified element from this dated collection for the specified date range.

Specified by:
remove in interface DatedCollection<E,D>
Overrides:
remove in class AbstractDatedCollection<E,D>
Parameters:
value - element to remove
from - starting date (inclusive) at which the element should be removed
to - ending date (exclusive) at which the element should be removed
Returns:
a series of date ranges indicating when the removal changed this dated collection
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
See Also:
DatedCollection.add(E, D, D)

size

public int size(D at)
Returns the number of elements in this dated collection at the specified date.

Specified by:
size in interface DatedCollection<E,D>
Overrides:
size in class AbstractDatedCollection<E,D>
Parameters:
at - date at which this dated collection is to be queried
Returns:
the number of elements on the specified date
Throws:
java.lang.NullPointerException - if at is null
See Also:
DatedCollection.hasSizeThroughout(int, D, D)

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.