|
Side of Software Dated Collections Library 2.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object sos.dated.util.AbstractDatedObject<D> sos.dated.util.AbstractDatedCollection<E,D>
E
- the type of elements maintained by this dated collectionD
- the type of dates used by this dated collectionpublic abstract class AbstractDatedCollection<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.
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. |
|
|
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 |
---|
protected AbstractDatedCollection()
Method Detail |
---|
public 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.
This implementation throws an UnsupportedOperationException
.
add
in interface DatedCollection<E,D>
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.UnsupportedOperationException
- alwayspublic 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.
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.
addAll
in interface DatedCollection<E,D>
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 add
DatedCollection.add(E, D, D)
,
DatedCollections.addAll(sos.dated.util.DatedCollection super E, D>, D, D, E...)
public void clear(D from, D to)
This implementation repeatedly invokes remove
on the iterator, while iterating
through the elements at each date within the specified range.
clear
in interface DatedCollection<E,D>
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 if from
or to
is null
java.lang.UnsupportedOperationException
- if the iterator throws this exception on removalpublic boolean contains(java.lang.Object value, D at)
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.
contains
in interface DatedCollection<E,D>
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
DatedCollection.containsThroughout(java.lang.Object, D, D)
public boolean containsAll(DatedCollection<?,D> datedCollection)
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.
containsAll
in interface DatedCollection<E,D>
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
DatedCollection.contains(java.lang.Object, D)
public boolean containsThroughout(java.lang.Object value, D from, D to)
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
.
containsThroughout
in interface DatedCollection<E,D>
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
DatedCollection.contains(java.lang.Object, D)
,
DatedCollection.excludesThroughout(java.lang.Object, D, D)
public abstract DateIterator<D> dateIterator(D at)
DatedObject
nextFrom
returns the
same date as previousTo
.
Passing null
as the argument will return an iterator positioned
at the beginning of the sequence.
dateIterator
in interface DatedObject<D>
dateIterator
in class AbstractDatedObject<D>
at
- date to position the iteration
public 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.
This implementation iterates through each element at the dates within
the specified range, invoking contains
.
excludesThroughout
in interface DatedCollection<E,D>
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
DatedCollection.containsThroughout(java.lang.Object, D, D)
public 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.
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
.
hasSizeThroughout
in interface DatedCollection<E,D>
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
DatedCollection.size(D)
,
DatedCollection.isEmptyThroughout(D, D)
public boolean isEmpty(D at)
true
if this dated collection contains no elements on the
specified date.
This implementation returns true if size( at )
returns 0.
isEmpty
in interface DatedCollection<E,D>
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
public boolean isEmptyThroughout(D from, D to)
true
if this dated collection contains no elements throughout the
specified date range.
This implementation invokes isEmpty
at each date within
the specified range.
isEmptyThroughout
in interface DatedCollection<E,D>
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
DatedCollection.isEmpty(D)
public abstract Iterator<E,D> iterator(D at)
DatedCollection
UnsupportedOperationException
in its remove
method because a date range is required to remove an element from
this dated collection.
iterator
in interface DatedCollection<E,D>
at
- date at which to iterate through the elements
public 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.
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
.
remove
in interface DatedCollection<E,D>
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 the iterator throws this exception on removalDatedCollection.add(E, D, D)
public 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.
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.
removeAll
in interface DatedCollection<E,D>
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 remove
DatedCollection.remove(java.lang.Object, D, D)
public 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.
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.
retainAll
in interface DatedCollection<E,D>
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 remove
public int size(D at)
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.
size
in interface DatedCollection<E,D>
at
- date at which this dated collection is to be queried
java.lang.NullPointerException
- if at
is null
DatedCollection.hasSizeThroughout(int, D, D)
public java.lang.Object[] toArray(D at)
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.
toArray
in interface DatedCollection<E,D>
at
- date of elements in this dated collection
java.lang.NullPointerException
- if at
is null
public <T> T[] toArray(T[] a, D at)
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.
toArray
in interface DatedCollection<E,D>
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
public java.lang.String toString(D at)
String.valueOf
.
toString
in interface DatedObject<D>
toString
in class AbstractDatedObject<D>
at
- date to which the string should correspond
java.lang.NullPointerException
- if 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 |