sos.dated.util
Class ValueByDate<E,D>

java.lang.Object
  sos.dated.util.AbstractDatedObject<D>
      sos.dated.util.AbstractDatedValue<E,D>
          sos.dated.util.ValueByDate<E,D>

Type Parameters:

E - the type of value maintained by this dated value

D - the type of dates used by this dated value

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, DatedObject<D>, DatedValue<E,D>

public class ValueByDate<E,D>
extends AbstractDatedValue<E,D>
implements DatedValue<E,D>, java.io.Serializable, java.lang.Cloneable

An implementation of DatedValue that can efficiently produce the value at a given date. The following illustration shows a conceptual view of a small ValueByDate where the "dates" are integers and the values are characters:

In the above picture, the dated value contains the following values for the following ranges:

   [1,2): K
   [2,3): M
   [3,5): A
   [5,6): B
   [7,9): M

This implementation is serializable and cloneable; however, it is not synchronized. To use it safely in a multi-threaded situation, wrap an instance of the dated object with a call to DatedCollections.synchronizedDatedValue.

Since:

1.0

See Also:

DatedValue, DatedCollections.synchronizedDatedValue(sos.dated.util.DatedValue)

Constructor Summary

ValueByDate()
Creates a ValueByDate with a null value over all dates.

ValueByDate(DatedValue<? extends E,D> datedValue)
Creates a ValueByDate with the same values as the specified dated value.

Method Summary

java.lang.Object	clone() Creates and returns a shallow copy of this object.
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.
E	get(D at) Returns the value at a specified date.
DatedValue<E,D>	set(E value, D from, D to) Sets the value for a specified date range.

Methods inherited from class sos.dated.util.AbstractDatedValue

equals, hashCode, is, isNotThroughout, isThroughout, toString

Methods inherited from class sos.dated.util.AbstractDatedObject

dateIterator, equals, hashCode, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface sos.dated.util.DatedValue

equals, hashCode, is, isNotThroughout, isThroughout

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, equals, hashCode, toString

Constructor Detail

ValueByDate

public ValueByDate()

Creates a ValueByDate with a null value over all dates.

ValueByDate

public ValueByDate(DatedValue<? extends E,D> datedValue)

Creates a ValueByDate with the same values as the specified dated value.

Parameters:

datedValue - values used to initialize this object

Throws:

java.lang.NullPointerException - if datedValue is null

Method Detail

clone

public java.lang.Object clone()

Creates and returns a shallow copy of this object.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this instance

dateIterator

public DateIterator<D> dateIterator(D at)

Description copied from interface: DatedObject

Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date. Throughout a range returned by the iterator, the state of the dated object must be the same. Also, the states of the dated object must be different in two consecutive ranges returned by the iterator. There are no gaps in the ranges returned by the iterator. That is, if a previous date range exists, then a call to nextFrom returns the same date as previousTo. Passing null as the argument will return an iterator positioned at the beginning of the sequence.

Specified by:

dateIterator in interface DatedObject<D>

Specified by:

dateIterator in class AbstractDatedObject<D>

Parameters:

at - date to position the iteration

Returns:

an iterator of the dates of when this dated object has changed, positioned immediately before the date range that contains the specified date

get

public E get(D at)

Returns the value at a specified date. It returns null if no value has been set for that date. Thus, it is impossible to distinguish an unset value and a set value of null. If such a distinction is necessary, the client can use a special marker value instead of null to signal a null value.

Specified by:

get in interface DatedValue<E,D>

Parameters:

at - date at which this dated value is to be queried

Returns:

the value at a specified date

Throws:

java.lang.NullPointerException - if at is null

set

public DatedValue<E,D> set(E value,
                           D from,
                           D to)

Sets the value for a specified date range.

Specified by:

set in interface DatedValue<E,D>

Overrides:

set in class AbstractDatedValue<E,D>

Parameters:

value - value to be set

from - starting date (inclusive) at which the value should hold

to - ending date (exclusive) at which the value should hold

Returns:

Returns a DatedValue indicating the values held in the date range of interest before the call to set.

Throws:

java.lang.IllegalArgumentException - to is not greater than from

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