Side of Software
Dated Collections Library 2.0

sos.dated.util
Class TreeSetByDate<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.TreeSetByDate<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>, DatedSortedSet<E,D>

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

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

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:
TreeSetByElement, HashSetByDate, DatedSet, TreeMapByDate, DatedCollections.synchronizedDatedSet(DatedSet)

Constructor Summary
TreeSetByDate()
          Creates an empty TreeSetByDate that sorts its elements according to their natural ordering.
TreeSetByDate(java.util.Comparator<? super E> comparator)
          Creates an empty TreeSetByDate that uses the specified comparator to sort its elements.
TreeSetByDate(DatedCollection<? extends E,D> datedCollection)
          Creates a TreeSetByDate containing the elements and date ranges of the specified dated collection, sorted by the elements' natural ordering.
TreeSetByDate(DatedSortedSet<E,D> datedSortedSet)
          Creates a TreeSetByDate containing the elements and date ranges of the specified dated sorted set, ordered by the parameter's comparator object.
 
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.
 java.util.Comparator<? super E> comparator()
          Returns the comparator used to sorted the elements of this dated set.
 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.
 E first(D at)
          Returns the smallest element in this dated set at the specified date.
 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.
 DatedSortedSet<E,D> headSet(E toElement)
          Returns a view of this dated set of all elements that precede toElement.
 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.
 E last(D at)
          Returns the largest element in this dated set 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.
 DatedSortedSet<E,D> subSet(E fromElement, E toElement)
          Returns a view of this dated set of all elements that fall between fromElement (inclusive) and toElement (exclusive).
 DatedSortedSet<E,D> tailSet(E fromElement)
          Returns a view of this dated set of all elements greater than or equal to fromElement.
 
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

TreeSetByDate

public TreeSetByDate()
Creates an empty TreeSetByDate that sorts its elements according to their natural ordering.


TreeSetByDate

public TreeSetByDate(java.util.Comparator<? super E> comparator)
Creates an empty TreeSetByDate that uses the specified comparator to sort its elements. If the comparator is null, then the elements' natural ordering is used.

Parameters:
comparator - object to use to sort the elements (may be null)

TreeSetByDate

public TreeSetByDate(DatedCollection<? extends E,D> datedCollection)
Creates a TreeSetByDate containing the elements and date ranges of the specified dated collection, sorted by the elements' natural ordering.

Parameters:
datedCollection - elements and corresponding date ranges to store in the new TreeSetByDate
Throws:
java.lang.NullPointerException - if the parameter is null

TreeSetByDate

public TreeSetByDate(DatedSortedSet<E,D> datedSortedSet)
Creates a TreeSetByDate containing the elements and date ranges of the specified dated sorted set, ordered by the parameter's comparator object.

Parameters:
datedSortedSet - elements and corresponding date ranges to store in the new TreeSetByDate
Throws:
java.lang.NullPointerException - if the parameter is null
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

comparator

public java.util.Comparator<? super E> comparator()
Description copied from interface: DatedSortedSet
Returns the comparator used to sorted the elements of this dated set. A returned null value indicates that this dated set uses the elements' natural ordering.

Specified by:
comparator in interface DatedSortedSet<E,D>
Returns:
the comparator that orders the elements (may be null)

first

public E first(D at)
Description copied from interface: DatedSortedSet
Returns the smallest element in this dated set at the specified date.

Specified by:
first in interface DatedSortedSet<E,D>
Parameters:
at - date for which to find the smallest element
Returns:
the smallest element at at

headSet

public DatedSortedSet<E,D> headSet(E toElement)
Description copied from interface: DatedSortedSet
Returns a view of this dated set of all elements that precede toElement. The element toElement does not have to appear in this dated set nor will it ever appear in the returned set. The returned set is a fully functional dated sorted set that is tied to this set. Changes to either will be reflected in the other. Any attempt to add an element greater than or equal to toElement will throw an IllegalArgumentException.

Specified by:
headSet in interface DatedSortedSet<E,D>
Parameters:
toElement - upper bound of the elements of the returned set (exclusive)
Returns:
the front portion of this ordered dated set up to, but not including, the specified element

last

public E last(D at)
Description copied from interface: DatedSortedSet
Returns the largest element in this dated set at the specified date.

Specified by:
last in interface DatedSortedSet<E,D>
Parameters:
at - date for which to find the largest element
Returns:
the largest element at at

subSet

public DatedSortedSet<E,D> subSet(E fromElement,
                                  E toElement)
Description copied from interface: DatedSortedSet
Returns a view of this dated set of all elements that fall between fromElement (inclusive) and toElement (exclusive). Neither element has to appear in this dated set. The returned set is a fully functional dated sorted set that is closely tied to this set. Changes to either will be reflected in the other. Any attempt to add an element outside the specified range will throw an IllegalArgumentException.

Specified by:
subSet in interface DatedSortedSet<E,D>
Parameters:
fromElement - lower bound of the elements of the returned set (inclusive)
toElement - upper bound of the elements of the returned set (exclusive)
Returns:
the middle portion of this ordered dated set from fromElement (inclusive) to toElement (exclusive)

tailSet

public DatedSortedSet<E,D> tailSet(E fromElement)
Description copied from interface: DatedSortedSet
Returns a view of this dated set of all elements greater than or equal to fromElement. The element fromElement does not have to appear in this dated set. The returned set is a fully functional dated sorted set that is closely tied to this set. Changes to either will be reflected in the other. Any attempt to add an element less than fromElement will throw an IllegalArgumentException.

Specified by:
tailSet in interface DatedSortedSet<E,D>
Parameters:
fromElement - lower bound of the elements of the returned set (inclusive)
Returns:
the back portion of this ordered dated set starting from the specified element

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.