sos.dated.util
Interface DatedObject<D>

Type Parameters:

D - the type of dates used by this dated object

All Known Subinterfaces:

DatedCollection<E,D>, DatedList<E,D>, DatedMap<K,V,D>, DatedSet<E,D>, DatedSortedMap<K,V,D>, DatedSortedSet<E,D>, DatedValue<E,D>

All Known Implementing Classes:

AbstractDatedCollection, AbstractDatedList, AbstractDatedMap, AbstractDatedObject, AbstractDatedSet, AbstractDatedValue, AbstractMapByDate, AbstractSequentialDatedList, ArrayListByDate, ArrayListByElement, HashMapByDate, HashMapByKey, HashSetByDate, HashSetByElement, IdentityHashMapByDate, IdentityHashMapByKey, LinkedHashMapByDate, LinkedHashSetByDate, TreeMapByDate, TreeMapByKey, TreeSetByDate, TreeSetByElement, ValueByDate

public interface DatedObject<D>

An object that maintains its state explicitly over time. This interface serves as the root of all dated objects, just as java.lang.Object tops the hierarchy of non-dated objects. Unlike java.lang.Object, however, this class provides no implementation but an API that all dated objects should adhere to.

The time axis may be of any type D. It may use standard java.util.Date objects to represent time, objects of a custom date class, or any other naturally ordered objects (such as java.lang.Integer). If the client uses java.util.Date to represent time, then the earliest time possible is new Date( Long.MIN_VALUE ) and the latest time possible is new Date( Long.MAX_VALUE ). Since the end of all date ranges is exclusive, the state of the object is undefined at its latest date (if one exists).

All dated objects have "change dates" that specify when the object's state has changed. The method dateIterator allows the client to iterate through these dates. The state from one date up to (but not including) the next date is guaranteed to be static. Some implementations may maintain these dates explicitly, while others may calculate them on-the-fly. The following sample while-loop iterates through the dates of a dated object:

   DatedObject obj = ...
   DateIterator dateIter = obj.dateIterator();
   while( dateIter.hasNext() ) {
     Date from = dateIter.nextFrom();
     Date to = dateIter.nextTo();
     dateIter.next();              // don't forget to advance the iterator
     ...
   }
 

Similarly, one can use a for-loop to iterate through the dates:

   DatedObject obj = ...
   for( DateIterator i = obj.dateIterator(); i.hasNext(); i.next() ) {
     Date from = dateIter.nextFrom();
     Date to = dateIter.nextTo();
     ...
   }
 

Also, this interface defines equals, hashCode, and toString at a specified date.

Since:

1.0

See Also:

DatedCollection, AbstractDatedObject

Method Summary

DateIterator<D>	dateIterator() Returns an iterator of the date ranges of when this dated object has changed.
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	equals(D at, DatedObject<D> obj, D objAt) Indicates if this dated object at at is equal to obj at objAt.
boolean	equals(java.lang.Object obj) Indicates if this dated object equals the specified object.
int	hashCode() Returns the hash code value of this dated object.
int	hashCode(D at) Returns a hash code value of this dated object at the specified date.
java.lang.String	toString(D at) Returns a string representation of this dated object at the specified date.

Method Detail

dateIterator

DateIterator<D> dateIterator()

Returns an iterator of the date ranges of when this dated object has changed. This method is equivalent to dateIterator( null ).

Returns:

a date iterator positioned before the first date range

See Also:

dateIterator(Object)

dateIterator

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. 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.

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

equals

boolean equals(java.lang.Object obj)

Indicates if this dated object equals the specified object. Two DatedObjects are equal if they have the same dates and if they are equal at each of these dates, as seen by equals(D,DatedObject,D).

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to compare this dated object to

Returns:

true if this dated object equals the specified object

See Also:

equals(Object,DatedObject,Object)

equals

boolean equals(D at,
               DatedObject<D> obj,
               D objAt)

Indicates if this dated object at at is equal to obj at objAt.

Parameters:

at - date at which this object should be tested

obj - the other dated object to be compared to

objAt - the date of the other dated object

Returns:

true if this dated object at at equals another dated object at objAt

Throws:

java.lang.NullPointerException - if any argument is null

hashCode

int hashCode()

Returns the hash code value of this dated object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value of this dated object

hashCode

int hashCode(D at)

Returns a hash code value of this dated object at the specified date. For two dated objects o1 and o2 and two dates d1 and d2, if o1.equals( d1, o2, d2 ) returns true, then o1.hashCode( d1 ) must equal o2.hashCode( d2 ).

Parameters:

at - date to which the hash code value should correspond

Returns:

the hash code value of this dated object at the specified date

Throws:

java.lang.NullPointerException - if at is null

toString

java.lang.String toString(D at)

Returns a string representation of this dated object at the specified date.

Parameters:

at - date to which the string should correspond

Returns:

a string representation of this dated object

Throws:

java.lang.NullPointerException - if at is null