|
Side of Software Dated Collections Library 2.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
E
- the type of elements maintained by this dated collectionD
- the type of dates used by this dated collectionpublic interface DatedCollection<E,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:
DatedCollectionTo iterate through the elements at the current time, one may then do the following:
IteratorThis 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)
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. |
|
|
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 |
---|
Dates<D> add(E value, D from, D to)
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.
value
- element to addfrom
- starting date (inclusive) at which the element should be addedto
- ending date (exclusive) at which the element should be added
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
Dates<D> addAll(DatedCollection<? extends E,D> datedCollection)
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.
datedCollection
- elements to add (and their date ranges)
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
add(E, D, D)
,
DatedCollections.addAll(sos.dated.util.DatedCollection super E, D>, D, D, E...)
void clear(D from, D to)
from
- starting date (inclusive) at which this dated collection should be clearedto
- ending date (exclusive) at which this dated collection should be cleared
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
boolean contains(java.lang.Object value, D at)
true
if this dated collection contains the specified element
on the specified date.
value
- element whose presence is to be testedat
- date at which this collection is to be queried
true
if this dated collection contains the specified element
on the specified date
java.lang.NullPointerException
- if at
is null
containsThroughout(java.lang.Object, D, D)
boolean containsAll(DatedCollection<?,D> datedCollection)
true
if this dated collection contains all elements of
the specified collection.
datedCollection
- elements and dates to test for containment
true
if this dated collection contains all elements of
the specified collection
java.lang.NullPointerException
- if datedCollection
is null
contains(java.lang.Object, D)
boolean containsThroughout(java.lang.Object value, D from, D to)
true
if this dated collection contains the specified element
throughout the specified date range.
value
- element whose presence is to be testedfrom
- starting date (inclusive) at which containment should be testedto
- ending date (exclusive) at which containment should be tested
true
if this dated collection contains the specified element
throughout the specified date range
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
contains(java.lang.Object, D)
,
excludesThroughout(java.lang.Object, D, D)
boolean excludesThroughout(java.lang.Object value, D from, D to)
true
if this dated collection does not contain the specified
element at any date within the specified date range.
value
- element whose presence is to be testedfrom
- starting date (inclusive) at which exclusion should be testedto
- ending date (exclusive) at which exclusion should be tested
true
if this dated collection does not contain value
at any date between from
and to
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
containsThroughout(java.lang.Object, D, D)
boolean hasSizeThroughout(int size, D from, D to)
true
if the number of elements in this dated collection is
greater than or equal to the specified size throughout the specified
date range.
size
- number of elements in questionfrom
- starting date (inclusive) at which the size is to be comparedto
- ending date (exclusive) at which the size is to be compared
true
if this dated collection has at least the specified size
throughout the specified date range.
java.lang.IllegalArgumentException
- if size < 0
or if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
size(D)
,
isEmptyThroughout(D, D)
boolean isEmpty(D at)
true
if this dated collection contains no elements on the
specified date.
at
- date at which this dated collection is to be queried
true
if this dated collection contains no elements on the
specified date
java.lang.NullPointerException
- if at
is null
boolean isEmptyThroughout(D from, D to)
true
if this dated collection contains no elements throughout the
specified date range.
from
- starting date (inclusive) at which this dated collection is to be queriedto
- ending date (exclusive) at which this dated collection is to be queried
true
if this dated collection contains no elements throughout the
specified date range.
java.lang.IllegalArgumentException
- if from
does not precede to
java.lang.NullPointerException
- if from
or to
is null
isEmpty(D)
Iterator<E,D> iterator(D at)
UnsupportedOperationException
in its remove
method because a date range is required to remove an element from
this dated collection.
at
- date at which to iterate through the elements
java.lang.NullPointerException
- if at
is null
Dates<D> remove(java.lang.Object value, D from, D to)
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.
value
- element to removefrom
- starting date (inclusive) at which the element should be removedto
- ending date (exclusive) at which the element should be removed
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
add(E, D, D)
Dates<D> removeAll(DatedCollection<?,D> datedCollection)
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.
datedCollection
- elements to remove (and their date ranges)
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
remove(java.lang.Object, D, D)
Dates<D> retainAll(DatedCollection<?,D> datedCollection)
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.
datedCollection
- elements to remove (and their date ranges)
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
int size(D at)
at
- date at which this dated collection is to be queried
java.lang.NullPointerException
- if at
is null
hasSizeThroughout(int, D, D)
java.lang.Object[] toArray(D at)
at
- date of elements in this dated collection
java.lang.NullPointerException
- if at
is null
<T> T[] toArray(T[] a, D at)
a
- array to hold the elements, if possibleat
- date of elements in this dated collection
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 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |