sos.dated.util
Class TreeSetByDate

java.lang.Object
  |
  +--sos.dated.util.AbstractDatedObject
        |
        +--sos.dated.util.AbstractDatedCollection
              |
              +--sos.dated.util.AbstractDatedSet
                    |
                    +--sos.dated.util.AbstractMapBackedSet
                          |
                          +--sos.dated.util.TreeSetByDate

All Implemented Interfaces:

java.lang.Cloneable, DatedCollection, DatedObject, DatedSet, DatedSortedSet, java.io.Serializable

public class TreeSetByDate

extends sos.dated.util.AbstractMapBackedSet

implements DatedSortedSet, java.io.Serializable, java.lang.Cloneable

An implementation of DatedSet that uses a TreeMapByDate as its underlying data structure.

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)

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

Constructor Summary

TreeSetByDate()
Creates a new instance of TreeSetByDate.

TreeSetByDate(java.util.Comparator comparator)
Creates a new instance of TreeSetByDate that uses the specified comparator to sort the keys.

TreeSetByDate(DatedCollection datedCollection)
Creates a new instance of TreeSetByDate from the specified dated collection.

TreeSetByDate(DatedSortedSet datedSortedSet)
Creates a new instance of TreeSetByDate from the specified dated sorted set.

Method Summary

Dates	add(java.lang.Object value, java.util.Date from, java.util.Date to) Adds the specified element to this collection for the specified date range (optional operation).
void	clear(java.util.Date from, java.util.Date to) Removes all elements from this dated collection for the specified dates (optional operation).
java.lang.Object	clone() Creates and returns a copy of this object.
java.util.Comparator	comparator() Returns the comparator used to sorted the elements of this dated set.
boolean	contains(java.lang.Object value, java.util.Date date) Returns true if this collection contains the specified element on the specified date.
boolean	containsThroughout(java.lang.Object value, java.util.Date from, java.util.Date to) Returns true if this collection contains the specified element throughout the specified date range.
DateIterator	dateIterator(java.util.Date date) 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, java.util.Date from, java.util.Date to) Returns true if this collection does not contain the specified element at any date within the specified date range.
java.lang.Object	first(java.util.Date date) Returns the smallest element in this dated set at the specified date.
boolean	hasSizeThroughout(int size, java.util.Date from, java.util.Date to) Returns true if the number of elements in this collection is greater than or equal to the specified size throughout the specified date range.
DatedSortedSet	headSet(java.lang.Object toElement) Returns a view of this dated set of all elements that precede toElement.
boolean	isEmpty(java.util.Date date) Returns true if this collection contains no elements on the specified date.
boolean	isEmptyThroughout(java.util.Date from, java.util.Date to) Returns true if this collection contains no elements throughout the specified date range.
Iterator	iterator(java.util.Date date) Returns an iterator over the elements of this dated collection at the specified date.
java.lang.Object	last(java.util.Date date) Returns the largest element in this dated set at the specified date.
Dates	remove(java.lang.Object value, java.util.Date from, java.util.Date to) Removes an instance of the specified element from this collection for the specified date range (optional operation).
int	size(java.util.Date date) Returns the number of elements in this collection at the specified date.
DatedSortedSet	subSet(java.lang.Object fromElement, java.lang.Object toElement) Returns a view of this dated set of all elements that fall between fromElement (inclusive) and toElement (exclusive).
DatedSortedSet	tailSet(java.lang.Object fromElement) Returns a view of this dated set of all elements greater than or equal to toElement.

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 a new instance of TreeSetByDate.

TreeSetByDate

public TreeSetByDate(java.util.Comparator comparator)

Creates a new instance of TreeSetByDate that uses the specified comparator to sort the keys.

TreeSetByDate

public TreeSetByDate(DatedCollection datedCollection)

Creates a new instance of TreeSetByDate from the specified dated collection.

TreeSetByDate

public TreeSetByDate(DatedSortedSet datedSortedSet)

Creates a new instance of TreeSetByDate from the specified dated sorted set.

Method Detail

clone

public java.lang.Object clone()

Creates and returns a copy of this object.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this instance

comparator

public java.util.Comparator 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

Returns:

the comparator that orders the elements (may be null)

first

public java.lang.Object first(java.util.Date date)

Description copied from interface: DatedSortedSet

Returns the smallest element in this dated set at the specified date.

Specified by:

first in interface DatedSortedSet

Parameters:

date - date for which to find the smallest element

Returns:

the smallest element at date

headSet

public DatedSortedSet headSet(java.lang.Object 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

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 java.lang.Object last(java.util.Date date)

Description copied from interface: DatedSortedSet

Returns the largest element in this dated set at the specified date.

Specified by:

last in interface DatedSortedSet

Parameters:

date - date for which to find the largest element

Returns:

the largest element at date

subSet

public DatedSortedSet subSet(java.lang.Object fromElement,
                             java.lang.Object 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

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 tailSet(java.lang.Object fromElement)

Description copied from interface: DatedSortedSet

Returns a view of this dated set of all elements greater than or equal to toElement. The element toElement 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

Parameters:

fromElement - lower bound of the elements of the returned set (inclusive)

Returns:

the front portion of this ordered dated map up to, but not including, the specified key

add

public Dates add(java.lang.Object value,
                 java.util.Date from,
                 java.util.Date to)

Description copied from interface: DatedCollection

Adds the specified element to this collection for the specified date range (optional operation).

The returned value indicates when this dated collection changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this dated collection.

Specified by:

add in interface DatedCollection

Overrides:

add in class AbstractDatedCollection

Parameters:

value - element to add

from - starting date at which the element should be added

to - ending date at which the element should be added

Returns:

a series of date ranges indicating when the addition changed this collection

clear

public void clear(java.util.Date from,
                  java.util.Date to)

Description copied from interface: DatedCollection

Removes all elements from this dated collection for the specified dates (optional operation).

Specified by:

clear in interface DatedCollection

Overrides:

clear in class AbstractDatedCollection

Parameters:

from - date to start clearing the collection, inclusive

to - date to finish clearing the collection, exclusive

contains

public boolean contains(java.lang.Object value,
                        java.util.Date date)

Description copied from interface: DatedCollection

Returns true if this collection contains the specified element on the specified date.

Specified by:

contains in interface DatedCollection

Overrides:

contains in class AbstractDatedCollection

Parameters:

value - element whose presence is to be tested

date - date at which this collection is to be queried

Returns:

true if this collection contains the specified element on the specified date

containsThroughout

public boolean containsThroughout(java.lang.Object value,
                                  java.util.Date from,
                                  java.util.Date to)

Description copied from interface: DatedCollection

Returns true if this collection contains the specified element throughout the specified date range.

Specified by:

containsThroughout in interface DatedCollection

Overrides:

containsThroughout in class AbstractDatedCollection

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 collection contains the specified element throughout the specified date range

dateIterator

public DateIterator dateIterator(java.util.Date date)

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 MAX_DATE as the argument will return an iterator positioned at the end of the sequence.

Specified by:

dateIterator in interface DatedObject

Specified by:

dateIterator in class AbstractDatedCollection

Parameters:

date - 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,
                                  java.util.Date from,
                                  java.util.Date to)

Description copied from interface: DatedCollection

Returns true if this collection does not contain the specified element at any date within the specified date range.

Specified by:

excludesThroughout in interface DatedCollection

Overrides:

excludesThroughout in class AbstractDatedCollection

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 collection does not contain value at any date between from and to

hasSizeThroughout

public boolean hasSizeThroughout(int size,
                                 java.util.Date from,
                                 java.util.Date to)

Description copied from interface: DatedCollection

Returns true if the number of elements in this collection is greater than or equal to the specified size throughout the specified date range.

Specified by:

hasSizeThroughout in interface DatedCollection

Overrides:

hasSizeThroughout in class AbstractDatedCollection

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 collection has at least the specified size throughout the specified date range.

isEmpty

public boolean isEmpty(java.util.Date date)

Description copied from interface: DatedCollection

Returns true if this collection contains no elements on the specified date.

Specified by:

isEmpty in interface DatedCollection

Overrides:

isEmpty in class AbstractDatedCollection

Parameters:

date - date at which this collection is to be queried

Returns:

true if this collection contains no elements on the specified date

isEmptyThroughout

public boolean isEmptyThroughout(java.util.Date from,
                                 java.util.Date to)

Description copied from interface: DatedCollection

Returns true if this collection contains no elements throughout the specified date range.

Specified by:

isEmptyThroughout in interface DatedCollection

Overrides:

isEmptyThroughout in class AbstractDatedCollection

Parameters:

from - starting date at which this collection is to be queried

to - ending date at which this collection is to be queried

Returns:

true if this collection contains no elements throughout the specified date range.

iterator

public Iterator iterator(java.util.Date date)

Description copied from interface: DatedCollection

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

Specified by:

iterator in class AbstractDatedCollection

Parameters:

date - date at which to iterate through the elements

Returns:

an iterator over the elements of this dated collection at the specified date.

remove

public Dates remove(java.lang.Object value,
                    java.util.Date from,
                    java.util.Date to)

Description copied from interface: DatedCollection

Removes an instance of the specified element from this collection for the specified date range (optional operation).

The returned value indicates when this dated collection changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this dated collection.

Specified by:

remove in interface DatedCollection

Overrides:

remove in class AbstractDatedCollection

Parameters:

value - element to remove

from - starting date at which the element should be removed

to - ending date at which the element should be removed

Returns:

a series of date ranges indicating when the removal changed this collection

size

public int size(java.util.Date date)

Description copied from interface: DatedCollection

Returns the number of elements in this collection at the specified date.

Specified by:

size in interface DatedCollection

Overrides:

size in class AbstractDatedCollection

Parameters:

date - date at which this collection is to be queried

Returns:

the number of elements on the specified date