sos.dated.util
Interface DatedObject

All Known Subinterfaces:

DatedCollection, DatedList, DatedMap, DatedSet, DatedSortedMap, DatedSortedSet, DatedValue

All Known Implementing Classes:

AbstractDatedCollection, AbstractDatedList, AbstractDatedMap, AbstractDatedObject, AbstractDatedSet, AbstractDatedValue, sos.dated.util.AbstractListByDate, sos.dated.util.AbstractMapBackedSet, AbstractMapByDate, sos.dated.util.AbstractMapByKey, ArrayListByDate, ArrayListByElement, HashMapByDate, HashMapByKey, HashSetByDate, HashSetByElement, IdentityHashMapByDate, IdentityHashMapByKey, TreeMapByDate, TreeMapByKey, TreeSetByDate, TreeSetByElement, ValueByDate

public interface DatedObject

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.

All dated objects use the standard java.util.Date to represent time. The earliest time possible is given by MIN_DATE, and the latest time possible by MAX_DATE. The state of the object is undefined at the instant of MAX_DATE.

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

Field Summary

static java.util.Date	MAX_DATE A date representing the latest possible date.
static java.util.Date	MIN_DATE A date representing the earliest possible date.

Method Summary

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

Field Detail

MIN_DATE

public static final java.util.Date MIN_DATE

A date representing the earliest possible date. It is equal to a Date object that is passed Long.MIN_VALUE to its constructor.

MAX_DATE

public static final java.util.Date MAX_DATE

A date representing the latest possible date. It is equal to a Date object that is passed Long.MAX_VALUE to its constructor.

Method Detail

dateIterator

public DateIterator dateIterator()

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

Returns:

a date iterator positioned before the first date range

See Also:

dateIterator(Date)

dateIterator

public DateIterator dateIterator(java.util.Date date)

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 MAX_DATE as the argument will return an iterator positioned at the end of the sequence.

Parameters:

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

Throws:

java.lang.NullPointerException - if date is null

equals

public 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(Date,DatedObject,Date).

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(Date,DatedObject,Date)

equals

public boolean equals(java.util.Date date,
                      DatedObject obj,
                      java.util.Date objDate)

Indicates if this dated object at date is equal to obj at objDate.

Parameters:

date - date at which this object should be tested

obj - the other dated object to be compared to

objDate - the date of the other dated object

Returns:

true if this dated object at date equals another dated object at objDate

Throws:

java.lang.NullPointerException - if any argument is null

hashCode

public 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

public int hashCode(java.util.Date date)

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:

date - date to which the value should correspond

Returns:

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

Throws:

java.lang.NullPointerException - if date is null

toString

public java.lang.String toString(java.util.Date date)

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

Parameters:

date - to which the string should correspond

Returns:

a string representation of this dated object

Throws:

java.lang.NullPointerException - if date is null