sos.dated.util
Class AbstractDates<D>

java.lang.Object
  sos.dated.util.AbstractDates<D>

Type Parameters:

D - the type of dates used in this series

All Implemented Interfaces:

Dates<D>

Direct Known Subclasses:

TreeDates

public abstract class AbstractDates<D>
extends java.lang.Object
implements Dates<D>

A partial implementation of a series of date ranges. The purpose of this class is to make it easier to implement the Dates interface. To create an unmodifiable date range series, the programmer should subclass this class and define dateIterator(D). To create a fully modifiable date range series, the programmer must also define addAll, addRange, clear, removeAll, removeRange, and retainAll.

Since:

1.0

See Also:

TreeDates, Dates

Constructor Summary

protected

AbstractDates() No-argument constructor available only to subclasses.

Method Summary

Dates<D>	addAll(Dates<D> dates) Adds all date ranges given by dates to this series of dates (optional operation).
Dates<D>	addRange(D from, D to) Adds a date range to this series of dates (optional operation).
void	clear() Removes all date ranges from this series of dates (optional operation).
void	complement(D from, D to) Modifies this Dates object so that it contains only the ranges not currently in this Dates object (optional operation).
DateIterator<D>	dateIterator() Returns a date iterator positioned at the first range in the series.
abstract DateIterator<D>	dateIterator(D at) Returns an iterator over the date ranges, starting at the range that contains the specified date.
boolean	equals(java.lang.Object obj) Indicates if this series of dates is equivalent to the specified object.
boolean	excludesAll(Dates<D> dates) Indicates if this series does not overlap another series of dates.
boolean	excludesRange(D from, D to) Indicates if no date range in this series overlaps the specified date range.
int	hashCode() Returns the hash code value of this series of dates.
boolean	includes(D date) Indicates if a date range in this series contains the specified date.
boolean	includesAll(Dates<D> dates) Indicates if this series of dates contains all the date ranges given by dates.
boolean	includesRange(D from, D to) Indicates if a date range in this series contains the specified date range.
boolean	isEmpty() Indicates if this series of dates is empty.
Dates<D>	removeAll(Dates<D> series) Removes all dates ranges given by dates from this series of dates (optional operation).
Dates<D>	removeRange(D from, D to) Removes the specified range from this series of dates (optional operation).
Dates<D>	retainAll(Dates<D> series) Removes all but the date ranges given by dates from this series of dates (optional operation).
int	size() Returns the number of date ranges included in this series.
java.lang.Object[]	toDateArray() Moves this series of dates to a newly created array of dates, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.
<T> T[]	toDateArray(T[] a) Moves this series of dates to either the specified array or to a new array with the same type as the specified array, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.
java.lang.String	toString() Returns a string representation of this series of dates.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractDates

protected AbstractDates()

No-argument constructor available only to subclasses.

Method Detail

addAll

public Dates<D> addAll(Dates<D> dates)

Adds all date ranges given by dates to this series of dates (optional operation).

The returned value indicates when this series of date ranges 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 Dates object.

This implementation throws an UnsupportedOperationException.

Specified by:

addAll in interface Dates<D>

Parameters:

dates - series of dates to be added

Returns:

a series of dates indicating the date ranges that were added as a result of the call

Throws:

java.lang.UnsupportedOperationException - always

addRange

public Dates<D> addRange(D from,
                         D to)

Adds a date range to this series of dates (optional operation).

The returned value indicates when this series of date ranges 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 Dates object.

This implementation throws an UnsupportedOperationException.

Specified by:

addRange in interface Dates<D>

Parameters:

from - start of the date range, inclusive

to - end of the date range, exclusive

Returns:

a series of dates indicating the date ranges that were added as a result of the call

Throws:

java.lang.UnsupportedOperationException - always

clear

public void clear()

Removes all date ranges from this series of dates (optional operation). This implementation throws an UnsupportedOperationException.

Specified by:

clear in interface Dates<D>

Throws:

java.lang.UnsupportedOperationException - always

complement

public void complement(D from,
                       D to)

Modifies this Dates object so that it contains only the ranges not currently in this Dates object (optional operation). This implementation throws an UnsupportedOperationException.

Specified by:

complement in interface Dates<D>

Throws:

java.lang.UnsupportedOperationException - always

dateIterator

public DateIterator<D> dateIterator()

Returns a date iterator positioned at the first range in the series. A call to this method is equivalent to dateIterator( null ).

This implementation invokes dateIterator( null ).

Specified by:

dateIterator in interface Dates<D>

Returns:

a date iterator positioned at the first range in the series.

dateIterator

public abstract DateIterator<D> dateIterator(D at)

Description copied from interface: Dates

Returns an iterator over the date ranges, starting at the range that contains the specified date. Passing null as the argument will return an iterator positioned at the beginning of the series.

Specified by:

dateIterator in interface Dates<D>

Parameters:

at - date to position the iteration

Returns:

an iterator over the date ranges, positioned immediately before the date range that contains the specified date

equals

public boolean equals(java.lang.Object obj)

Indicates if this series of dates is equivalent to the specified object.

This implementation first checks reference equality and then casts obj to another Dates object. Finally, it iterates through the ranges of each, checking for equal ranges.

Specified by:

equals in interface Dates<D>

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to be compared to this series of dates

Returns:

true if this series equals obj

excludesAll

public boolean excludesAll(Dates<D> dates)

Indicates if this series does not overlap another series of dates. This implementation iterates through the ranges of dates and checks excludesRange for each range.

Specified by:

excludesAll in interface Dates<D>

Parameters:

dates - date ranges to test for exclusion

Returns:

true if no date range of this series overlaps a date range of the specified series

Throws:

java.lang.NullPointerException - if dates is null

excludesRange

public boolean excludesRange(D from,
                             D to)

Indicates if no date range in this series overlaps the specified date range. This implementation checks if the date range (if one exists) of an iterator positioned at from does not contain from or to.

Specified by:

excludesRange in interface Dates<D>

Parameters:

from - start of date range (inclusive) to test for exclusion

to - end of date range (exclusive) to test for exclusion

Returns:

true if no date range of this series overlaps the specified date range

Throws:

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

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

hashCode

public int hashCode()

Description copied from interface: Dates

Returns the hash code value of this series of dates. The value of a Dates object is defined to be

   hashCode += 31 * ( from.hashCode() + to.hashCode() );
 

for each range [from,to) in this object.

Specified by:

hashCode in interface Dates<D>

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value of this series of dates.

includes

public boolean includes(D date)

Indicates if a date range in this series contains the specified date.

This implementation gets a date iterator at date and checks if nextFrom is less than or equal to date.

Specified by:

includes in interface Dates<D>

Parameters:

date - date to test for inclusion

Returns:

true if this series of dates contains the specified date

Throws:

java.lang.NullPointerException - if at is null

includesAll

public boolean includesAll(Dates<D> dates)

Indicates if this series of dates contains all the date ranges given by dates.

This implementation iterates through the date ranges of dates, invoking includesRange for each range.

Specified by:

includesAll in interface Dates<D>

Parameters:

dates - date ranges to test for inclusion

Returns:

true if this series of dates contains all of the specified date ranges

Throws:

java.lang.NullPointerException - if dates is null

includesRange

public boolean includesRange(D from,
                             D to)

Indicates if a date range in this series contains the specified date range.

This implementation checks if the first range of the iterator produced by dateIterator(from) contains from and to.

Specified by:

includesRange in interface Dates<D>

Parameters:

from - start of date range (inclusive) to test for inclusion

to - end of date range (exclusive) to test for inclusion

Returns:

true if this series of dates contains the specified date range

Throws:

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

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

isEmpty

public boolean isEmpty()

Indicates if this series of dates is empty.

This implementation executes

   return !dateIterator().hasNext();
 

Specified by:

isEmpty in interface Dates<D>

Returns:

true if no date ranges exist in this series

removeAll

public Dates<D> removeAll(Dates<D> series)

Removes all dates ranges given by dates from this series of dates (optional operation).

The returned value indicates when this series of date ranges 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 Dates object.

This implementation throws an UnsupportedOperationException.

Specified by:

removeAll in interface Dates<D>

Parameters:

series - date ranges to be removed

Returns:

a series of dates indicating the date ranges that were removed as a result of the call

Throws:

java.lang.UnsupportedOperationException - always

removeRange

public Dates<D> removeRange(D from,
                            D to)

Removes the specified range from this series of dates (optional operation).

The returned value indicates when this series of date ranges 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 Dates object.

This implementation throws an UnsupportedOperationException.

Specified by:

removeRange in interface Dates<D>

Parameters:

from - start of date range to remove (inclusive)

to - end of date range to remove (exclusive)

Returns:

a series of dates indicating the date ranges that were removed as a result of the call

Throws:

java.lang.UnsupportedOperationException - always

retainAll

public Dates<D> retainAll(Dates<D> series)

Removes all but the date ranges given by dates from this series of dates (optional operation).

The returned value indicates when this series of date ranges 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 Dates object.

This implementation throws an UnsupportedOperationException.

Specified by:

retainAll in interface Dates<D>

Parameters:

series - date ranges to retain

Returns:

a series of dates indicating the date ranges that were removed as a result of the call

Throws:

java.lang.UnsupportedOperationException - always

size

public int size()

Returns the number of date ranges included in this series.

This implementation counts the number of ranges returned by an iterator positioned at the beginning.

Specified by:

size in interface Dates<D>

Returns:

the number of date ranges included in this series.

toDateArray

public java.lang.Object[] toDateArray()

Description copied from interface: Dates

Moves this series of dates to a newly created array of dates, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.

Specified by:

toDateArray in interface Dates<D>

Returns:

an array of dates representing this series of dates

toDateArray

public <T> T[] toDateArray(T[] a)

Description copied from interface: Dates

Moves this series of dates to either the specified array or to a new array with the same type as the specified array, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.

Specified by:

toDateArray in interface Dates<D>

Returns:

an array of dates representing this series of dates

toString

public java.lang.String toString()

Returns a string representation of this series of dates. The string representation begins with "{". Then, for each range returned by an iterator positioned at the beginning, it contains "[from,to)" where from and to denote the start and end of the range, respectively. Each range is separated with ", " and "}" ends the string.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this series of dates.