sos.dated.util
Interface DatedCollection

All Superinterfaces:

DatedObject

All Known Subinterfaces:

DatedList, DatedSet, DatedSortedSet

All Known Implementing Classes:

AbstractDatedCollection, AbstractDatedList, AbstractDatedSet, sos.dated.util.AbstractListByDate, sos.dated.util.AbstractMapBackedSet, ArrayListByDate, ArrayListByElement, HashSetByDate, HashSetByElement, TreeSetByDate, TreeSetByElement

public interface DatedCollection

extends DatedObject

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,Date). Similarly, to treat a non-dated collection as dated, use Adapters.asDatedCollection(Collection,Date,Date).

At the instant of MAX_DATE, the collection is always empty.

For example, to add an element from the current time to the end of time, one may use the following code:

   DatedCollection datedCollection = ...
   Date currentDate = new Date();
   datedCollection.add( value, currentDate, DatedObject.MAX_DATE );
 

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,Date,Date)
• excludesThroughout(Object,Date,Date)
• get(Object)
• hasSizeThroughout(int,Date,Date)
• isEmptyThroughout(Date,Date)

Since:

1.0

See Also:

DatedList, DatedSet, DatedMap, DatedSortedSet, DatedSortedMap, DatedCollections, Adapters.asCollection(DatedCollection,Date), Adapters.asDatedCollection(Collection,Date,Date)

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

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

Methods inherited from interface sos.dated.util.DatedObject

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

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

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

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

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.

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.

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.

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

Throws:

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

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

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.

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.

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.

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.

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.

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 Iterator iterator(java.util.Date date)

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:

date - 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 date is null

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.

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.

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.

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.

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.

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.

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