Side of Software
Dated Collections Library 2.0

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:

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

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.