sos.dated.util
Class AbstractDatedCollection

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

All Implemented Interfaces:

DatedCollection, DatedObject

Direct Known Subclasses:

AbstractDatedList, AbstractDatedSet

public abstract class AbstractDatedCollection

extends AbstractDatedObject

implements DatedCollection

A partial implementation of a dated collection. To write a complete implementation of a dated collection, the programmer only has to subclass this class and define iterator and dateIterator.

The methods that update the collection, such as add and clear, will throw an UnsupportedOperationException. To write a modifiable implementation, the programmer should also implement add and the returned element iterator should implement remove.

Depending on the implementation, the programmer may wish to override certain methods to make use of implementation-specific information and to increase the methods' efficiency.

Since:

1.0

See Also:

DatedCollection

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

Constructor Summary

protected

AbstractDatedCollection() No-argument constructor available only to subclasses.

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).
Dates	addAll(DatedCollection datedCollection) Adds a dated collection of elements to this dated collection (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).
boolean	contains(java.lang.Object value, java.util.Date date) Returns true if this collection contains the specified element on the specified date.
boolean	containsAll(DatedCollection datedCollection) Returns true if this dated collection contains all elements of the specified collection.
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.
abstract 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.
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.
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.
abstract Iterator	iterator(java.util.Date date) Returns an iterator over the elements of this dated collection 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).
Dates	removeAll(DatedCollection datedCollection) Removes the elements in this collection that are contained in the specified collection (optional operation).
Dates	retainAll(DatedCollection datedCollection) Retains in this dated collection only the the elements in the specified collection (optional operation).
int	size(java.util.Date date) Returns the number of elements in this collection at the specified date.
java.lang.Object[]	toArray(java.util.Date date) Moves the elements of this dated collection at the specified date to a newly created array.
java.lang.Object[]	toArray(java.lang.Object[] a, java.util.Date date) Moves the elements of this dated collection at the specified date either to the specified array or to a new array with the same type as the specified array.
java.lang.String	toString(java.util.Date date) Returns a string representation of this dated object at the specified date.

Methods inherited from class sos.dated.util.AbstractDatedObject

dateIterator, equals, equals, hashCode, hashCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, equals, equals, hashCode, hashCode

Constructor Detail

AbstractDatedCollection

protected AbstractDatedCollection()

No-argument constructor available only to subclasses.

Method Detail

add

public 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).

This implementation throws an UnsupportedOperationException.

Specified by:

add in interface DatedCollection

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

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.UnsupportedOperationException - if this collection does not support add

addAll

public Dates addAll(DatedCollection datedCollection)

Adds a dated collection of elements to this dated collection (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.

This implementation provides a generic implementation. It iterates through the dates of the specified collection, invoking add for each element in the collection at a date.

A subclass that can implement this method more efficiently should override this method.

Specified by:

addAll in interface DatedCollection

Parameters:

datedCollection - elements to add

Returns:

a series of dates for which a change occurs

Throws:

java.lang.NullPointerException - if datedCollection is null

clear

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

Removes all elements from this dated collection for the specified dates (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.

This implementation repeatedly invokes remove on the iterator, while iterating through the elements at each date within the specified range.

Specified by:

clear in interface DatedCollection

Parameters:

from - date to start clearing the collection, inclusive

to - date to finish clearing the collection, exclusive

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

contains

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

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

This implementation iterates through the elements at the specified date and returns true if it finds the specified value.

Specified by:

contains in interface DatedCollection

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

Throws:

java.lang.NullPointerException - if date is null

containsAll

public boolean containsAll(DatedCollection datedCollection)

Returns true if this dated collection contains all elements of the specified collection.

This implementation invokes containsThroughout on each element and date range in the specified dated collection.

Specified by:

containsAll in interface DatedCollection

Parameters:

datedCollection - elements and date to test for containment

Returns:

true if this dated collection contains all elements of the specified collection

Throws:

java.lang.NullPointerException - if datedCollection is null

containsThroughout

public 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.

This implementation iterates through each element at the dates within the specified range, invoking contains.

Specified by:

containsThroughout in interface DatedCollection

Parameters:

value - element whose presence is to be tested

from - starting date at which containment should be tested

to - ending date at which containment should be tested

Returns:

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

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

dateIterator

public abstract 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 AbstractDatedObject

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)

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

This implementation iterates through each element at the dates within the specified range, invoking contains.

Specified by:

excludesThroughout in interface DatedCollection

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

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

hasSizeThroughout

public 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.

This implementation iterates through the dates between from and to, invoking size at each date. If a returned size is less than the parameter size, it returns false.

Specified by:

hasSizeThroughout in interface DatedCollection

Parameters:

size - number of elements in question

from - starting date at which the size is to be compared

to - ending date at which the size is to be compared

Returns:

true if this collection has at least the specified size throughout the specified date range.

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if size < 0 or if from does not precede to

isEmpty

public boolean isEmpty(java.util.Date date)

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

This implementation returns true if size( t ) returns 0.

Specified by:

isEmpty in interface DatedCollection

Parameters:

date - date at which this collection is to be queried

Returns:

true if this collection contains no elements on the specified date

Throws:

java.lang.NullPointerException - if date is null

isEmptyThroughout

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

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

This implementation invokes isEmpty at each date within the specified range.

Specified by:

isEmptyThroughout in interface DatedCollection

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.

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

iterator

public abstract 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

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)

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.

This implementation iterates through the elements at each date between from and to and invokes remove on the iterator at the first occurrence of value.

Specified by:

remove in interface DatedCollection

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

Throws:

java.lang.IllegalArgumentException - if from does not precede to

java.lang.NullPointerException - if from or to is null

java.lang.UnsupportedOperationException - if this collection does not support remove

removeAll

public Dates removeAll(DatedCollection datedCollection)

Removes the elements in this collection that are contained in the specified collection (optional operation). After the method, this collection will contain no element in common with the specified collection at the same date.

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.

This implementation iterates over the dates of both this collection and the specified collection. gathering dates in a sorted set. Then, for each date in the set, it determines which elements to remove from this collection, by iterating through this collection's elements and seeing if the element is contained in the specified collection. Last, it removes the elements found in the previous step.

A subclass that can implement this method more efficiently should override this method.

Specified by:

removeAll in interface DatedCollection

Parameters:

datedCollection - elements and date ranges to remove

Returns:

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

Throws:

java.lang.NullPointerException - if datedCollection is null

retainAll

public Dates retainAll(DatedCollection datedCollection)

Retains in this dated collection only the the elements in the specified collection (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.

This implemenation iterates over the dates of both this collection and the specified collection. gathering dates in a sorted set. Then, for each date in the set, it determines which elements to remove from this collection, by iterating through this collection's elements and seeing if the element is not contained in the specified collection. Last, it removes the elements found in the previous step.

A subclass that can implement this method more efficiently should override this method.

Specified by:

retainAll in interface DatedCollection

Parameters:

datedCollection - elements and date ranges to remove

Returns:

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

Throws:

java.lang.NullPointerException - if datedCollection is null

size

public int size(java.util.Date date)

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

This implementation iterates through the elements at the specified date, counting the elements as it goes.

A subclass that can determine the size of its collection more efficiently should override this method.

Specified by:

size in interface DatedCollection

Parameters:

date - date at which this collection is to be queried

Returns:

the number of elements on the specified date

Throws:

java.lang.NullPointerException - if date is null

toArray

public java.lang.Object[] toArray(java.util.Date date)

Moves the elements of this dated collection at the specified date to a newly created array. The order of the elements in this array matches that returned by an iterator at this date.

This implementation first constructs a new Object array with the size of the collection at the specified date. Then it iterates through the elements at the date, appending them to the array as it goes.

Specified by:

toArray in interface DatedCollection

Parameters:

date - date of elements in this collection

Returns:

a newly constructed array containing the elements, as returned by an iterator at this date.

Throws:

java.lang.NullPointerException - if date is null

toArray

public java.lang.Object[] toArray(java.lang.Object[] a,
                                  java.util.Date date)

Moves the elements of this dated collection at the specified date either to the specified array or to a new array with the same type as the specified array.

This implementation constructs an array of the same type of a if a is not large enough to hold all of the elements. It then fills the array as it iterates through the elements.

Specified by:

toArray in interface DatedCollection

Parameters:

a - array to hold the elements, if possible

date - date of elements in this collection

Returns:

an array (possibly the parameter array) containing the elements, as returned by an iterator at this date

Throws:

java.lang.NullPointerException - if date is null

toString

public java.lang.String toString(java.util.Date date)

Returns a string representation of this dated object at the specified date.

This implementation uses a StringBuffer to generate the string. It first appends a "[". Then, for each element e in this collection at the specified date, it appends String.valueOf( e ), separating each element with ", ". Last, it appends a "]".

Specified by:

toString in interface DatedObject

Specified by:

toString in class AbstractDatedObject

Parameters:

date - to which the string should correspond

Returns:

a string representation of this dated object

Throws:

java.lang.NullPointerException - if date is null