Side of Software
Dated Collections Library 2.0

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

Side of Software
Dated Collections Library 2.0

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