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

java.lang.Object
  sos.dated.util.AbstractDatedObject<D>
      sos.dated.util.AbstractDatedCollection<E,D>

Type Parameters:

E - the type of elements maintained by this dated collection

D - the type of dates used by this dated collection

All Implemented Interfaces:

DatedCollection<E,D>, DatedObject<D>

Direct Known Subclasses:

AbstractDatedList, AbstractDatedSet

public abstract class AbstractDatedCollection<E,D>
extends AbstractDatedObject<D>
implements DatedCollection<E,D>

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

Constructor Summary

protected

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

Method Summary

Dates<D>	add(E value, D from, D to) Adds the specified element to this dated collection for the specified date range (optional operation).
Dates<D>	addAll(DatedCollection<? extends E,D> datedCollection) Adds a dated collection of elements to this dated collection (optional operation).
void	clear(D from, D to) Removes all elements from this dated collection for the specified dates (optional operation).
boolean	contains(java.lang.Object value, D at) Returns true if this dated collection contains the specified element on the specified date.
boolean	containsAll(DatedCollection<?,D> datedCollection) Returns true if this dated collection contains all elements of the specified collection.
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.
abstract 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.
abstract 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 (optional operation).
Dates<D>	removeAll(DatedCollection<?,D> datedCollection) Removes the elements in this dated collection that are contained in the specified dated collection (optional operation).
Dates<D>	retainAll(DatedCollection<?,D> datedCollection) Retains in this dated collection only the elements in the specified dated collection (optional operation).
int	size(D at) Returns the number of elements in this dated collection at the specified date.
java.lang.Object[]	toArray(D at) Moves the elements of this dated collection at the specified date to a newly created array.
<T> T[]	toArray(T[] a, D at) 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(D at) 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<D> add(E value,
                    D from,
                    D to)

Adds the specified element to this dated 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 throws an UnsupportedOperationException.

Specified by:

add in interface DatedCollection<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.UnsupportedOperationException - always

addAll

public Dates<D> addAll(DatedCollection<? extends E,D> datedCollection)

Adds a dated collection of elements to this dated collection (optional operation). If this dated collection and the collection passed in are connected in such a way that the collection changes during any additions, this method is undefined. This means that this method cannot handle this as the parameter.

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<E,D>

Parameters:

datedCollection - elements to add (and their date ranges)

Returns:

a series of dates for which a change occurs

Throws:

java.lang.ClassCastException - if the type of an element of datedCollection prevents it from being added to this dated collection

java.lang.IllegalArgumentException - if some property of an element of datedCollection prevents it from being added to this dated collection

java.lang.NullPointerException - if datedCollection is null or if an element of datedCollection is null and this dated collection cannot hold null elements

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

See Also:

DatedCollection.add(E, D, D), DatedCollections.addAll(sos.dated.util.DatedCollection, D, D, E...)

clear

public void clear(D from,
                  D to)

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

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

java.lang.UnsupportedOperationException - if the iterator throws this exception on removal

contains

public boolean contains(java.lang.Object value,
                        D at)

Returns true if this dated 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<E,D>

Parameters:

value - element whose presence is to be tested

at - 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)

containsAll

public boolean containsAll(DatedCollection<?,D> 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<E,D>

Parameters:

datedCollection - elements and dates 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

See Also:

DatedCollection.contains(java.lang.Object, 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.

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

Specified by:

containsThroughout in interface DatedCollection<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 abstract 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 AbstractDatedObject<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.

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

Specified by:

excludesThroughout in interface DatedCollection<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.

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

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

Specified by:

isEmpty in interface DatedCollection<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.

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

Specified by:

isEmptyThroughout in interface DatedCollection<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 abstract Iterator<E,D> iterator(D at)

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

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 (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<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.ClassCastException - if the underlying type of value prevents it from being removed from this dated collection

java.lang.IllegalArgumentException - if from does not precede to or if some property of value prevents it from being removed from this dated collection

java.lang.NullPointerException - if from or to is null or if value is null and this dated collection cannot hold null elements

java.lang.UnsupportedOperationException - if the iterator throws this exception on removal

See Also:

DatedCollection.add(E, D, D)

removeAll

public Dates<D> removeAll(DatedCollection<?,D> datedCollection)

Removes the elements in this dated collection that are contained in the specified dated collection (optional operation). After the method, this dated collection will contain no element in common with the specified dated 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<E,D>

Parameters:

datedCollection - elements to remove (and their date ranges)

Returns:

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

Throws:

java.lang.ClassCastException - if the type of an element of datedCollection prevents it from being removed from this dated collection

java.lang.IllegalArgumentException - if some property of an element of datedCollection prevents it from being removed from this dated collection

java.lang.NullPointerException - if datedCollection is null or if an element of datedCollection is null and this dated collection cannot hold null elements

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

See Also:

DatedCollection.remove(java.lang.Object, D, D)

retainAll

public Dates<D> retainAll(DatedCollection<?,D> datedCollection)

Retains in this dated collection only the elements in the specified dated collection (optional operation).

The returned value indicates when this dated collection changed as a result of the call. 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<E,D>

Parameters:

datedCollection - elements to remove (and their date ranges)

Returns:

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

Throws:

java.lang.ClassCastException - if the type of an element of datedCollection is incompatible with the elements of this dated collection

java.lang.IllegalArgumentException - if some property of an element of datedCollection is incompatible with the elements of this dated collection

java.lang.NullPointerException - if datedCollection is null or if an element of datedCollection is null and this dated collection cannot hold null elements

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

size

public int size(D at)

Returns the number of elements in this dated 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<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)

toArray

public java.lang.Object[] toArray(D at)

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<E,D>

Parameters:

at - date of elements in this dated collection

Returns:

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

Throws:

java.lang.NullPointerException - if at is null

toArray

public <T> T[] toArray(T[] a,
                       D at)

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. The order of the elements in the returned array matches that returned by an iterator at this date.

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<E,D>

Parameters:

a - array to hold the elements, if possible

at - date of elements in this dated collection

Returns:

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

Throws:

java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this dated collection at the specified date

java.lang.NullPointerException - if a or at is null

toString

public java.lang.String toString(D at)

Returns a string representation of this dated object at the specified date. The string representation is the open square bracket "[", followed by the elements of the dated collection at the specified date, followed by the closing square bracket "]". The elements are listed in the order returned by the iterator and are separated by ", ". Each element is converted to a string via a call to String.valueOf.

Specified by:

toString in interface DatedObject<D>

Specified by:

toString in class AbstractDatedObject<D>

Parameters:

at - date to which the string should correspond

Returns:

a string representation of this dated object

Throws:

java.lang.NullPointerException - if at is null