sos.dated.util
Interface DatedCollection<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 Superinterfaces:

DatedObject<D>

All Known Subinterfaces:

DatedList<E,D>, DatedSet<E,D>, DatedSortedSet<E,D>

All Known Implementing Classes:

AbstractDatedCollection, AbstractDatedList, AbstractDatedSet, AbstractSequentialDatedList, ArrayListByDate, ArrayListByElement, HashSetByDate, HashSetByElement, LinkedHashSetByDate, TreeSetByDate, TreeSetByElement

public interface DatedCollection<E,D>
extends DatedObject<D>

A collection of elements over time. A dated collection represents a group of elements during various date ranges. It provides an interface similar to java.util.Collection with the requirement that either a date or a date range be specified, depending on the type of method. A method that changes the collection requires a date range, while a method that queries the collection requires either a date or a date range. A non-dated collection is equivalent to a dated collection in which all elements appear from the beginning of time to the end of time.

The Dated Collections library does not provide any direct implementations of this class. Instead, it provides implementations of subinterfaces.

This interface does not extend java.util.Collection directly because at least one date is needed. To make a dated collection appear like a non-dated collection, use Adapters.asCollection(DatedCollection,D). Similarly, to treat a non-dated collection as dated, use Adapters.asDatedCollection(Collection,D,D).

For example, to add an element to a dated collection from one time to another time, one may use the following code:

   DatedCollection datedCollection = ...
   Date d1 = ...
   Date d2 = ...
   datedCollection.add( value, d1, d2 );
 

To iterate through the elements at the current time, one may then do the following:

   Iterator iter = datedCollection.iterator( currentDate );
   while( iter.hasNext() ) {
     Object element = iter.next();
     ...
   }
 

This interface contains additional methods that do not correspond to a method in java.util.Collection:

• containsThroughout(Object,D,D)
• excludesThroughout(Object,D,D)
• hasSizeThroughout(int,D,D)
• isEmptyThroughout(D,D)

Since:

1.0

See Also:

DatedList, DatedSet, DatedMap, DatedSortedSet, DatedSortedMap, DatedCollections, Adapters.asCollection(DatedCollection,Object), Adapters.asDatedCollection(Collection,Object,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 (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.
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 (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.

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, dateIterator, equals, equals, hashCode, hashCode, toString

Method Detail

add

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.

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

java.lang.IllegalArgumentException - if from does not precede to or if some property of value prevents it from being added to 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 this dated collection does not support add

addAll

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.

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 addAll

See Also:

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

clear

void clear(D from,
           D to)

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

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 from or to is null

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

contains

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

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

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:

containsThroughout(java.lang.Object, D, D)

containsAll

boolean containsAll(DatedCollection<?,D> datedCollection)

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

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:

contains(java.lang.Object, D)

containsThroughout

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.

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:

contains(java.lang.Object, D), excludesThroughout(java.lang.Object, D, D)

excludesThroughout

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.

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:

containsThroughout(java.lang.Object, D, D)

hasSizeThroughout

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.

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:

size(D), isEmptyThroughout(D, D)

isEmpty

boolean isEmpty(D at)

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

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

boolean isEmptyThroughout(D from,
                          D to)

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

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:

isEmpty(D)

iterator

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.

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

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.

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 this dated collection does not support remove

See Also:

add(E, D, D)

removeAll

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.

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 removeAll

See Also:

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

retainAll

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.

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 retainAll

size

int size(D at)

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

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:

hasSizeThroughout(int, D, D)

toArray

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.

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

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

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