Side of Software
Dated Collections Library 2.0

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

java.lang.Object
  extended by sos.dated.util.AbstractDatedObject<D>
      extended by sos.dated.util.AbstractDatedValue<E,D>
          extended by 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

Side of Software
Dated Collections Library 2.0

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