org.chronicj
Class DateRange

java.lang.Object
  |
  +--org.chronicj.DateRange

All Implemented Interfaces:

java.lang.Comparable

public class DateRange

extends java.lang.Object

implements java.lang.Comparable

Defines basic requirements and utility methods for classes that model periods of time. Based directly on the Range pattern described by Martin Fowler. This is a value object.

Author:

Matthew Lipper

See Also:

TimePoint, Range

Field Summary

static org.chronicj.DateRange

EMTPY Specifies an empty range which can be used as a constant

Constructor Summary

DateRange(java.util.Date aStartDate, java.util.Date anEndDate)
Construct a DateRange using the given start and end dates.

DateRange(org.chronicj.TimePoint aStartDate, org.chronicj.TimePoint anEndDate)
Construct a DateRange using the supplied start and end TimePoints.

Method Summary

boolean	abuts(org.chronicj.DateRange anotherRange) Used to detect whether two date ranges abut each other.
static org.chronicj.DateRange	combination(org.chronicj.DateRange[] args)
int	compareTo(java.lang.Object arg) Compare the current DateRange instance to the one provided.
org.chronicj.TimePoint	end() Accessor method for the TimePoint denoting the upper end of this range.
boolean	equals(java.lang.Object arg)
org.chronicj.DateRange	gap(org.chronicj.DateRange arg) Used to determine the duration of time (expressed as another DateRange) between the current DateRange instance and another DateRange.
org.chronicj.DatePrecision	getDatePrecision() The DatePrecisionof this range.
int	hashCode()
boolean	includes(org.chronicj.DateRange arg) Used to check whether a given DateRange occurs within the current range.
boolean	includes(org.chronicj.TimePoint aDate) Used to check whether a given TimePoint occurs within the current range.
static boolean	isContiguous(org.chronicj.DateRange[] args)
boolean	isEmpty() Used mostly by other date range calculations to indicate an empty set.
boolean	overlaps(org.chronicj.DateRange anotherRange) Used mostly by other date range calculations to indicate an empty set.
boolean	partitionedBy(org.chronicj.DateRange[] otherRanges) Used to check whether a group of ranges completely partition the current DateRange.
org.chronicj.TimePoint	start() Accessor method for the TimePoint denoting the lower end of this range.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

EMTPY

public static final org.chronicj.DateRange EMTPY

Specifies an empty range which can be used as a constant

Constructor Detail

DateRange

public DateRange(java.util.Date aStartDate,
                 java.util.Date anEndDate)

Construct a DateRange using the given start and end dates. The Date arguments are wrapped using TimePoints, and as such, they are normalized using minute precision (this is the default precision for a TimePoint). If the start date is greater than the end date, the range is considered empty. Currently, this class does not support open ranges, i.e. since or until.

Parameters:

aStartDate - the Date that is the lower end of the range

anEndDate - the Date that is the upper end of the range

Throws:

java.lang.NullPointerException - is either argument is null

DateRange

public DateRange(org.chronicj.TimePoint aStartDate,
                 org.chronicj.TimePoint anEndDate)

Construct a DateRange using the supplied start and end TimePoints. If the start date is greater than the end date, the range is considered empty. Currently, this class does not support open ranges, i.e. since or until.

Parameters:

aStartDate - the TimePoint that is the lower end of the range

anEndDate - the TimePoint that is the upper end of the range

Throws:

java.lang.NullPointerException - is either argument is null

Method Detail

isContiguous

public static boolean isContiguous(org.chronicj.DateRange[] args)

getDatePrecision

public org.chronicj.DatePrecision getDatePrecision()

The DatePrecisionof this range. If the start and end of this range are of different precisions, the greater precision is returned.

Returns:

DatePrecision of this range

isEmpty

public boolean isEmpty()

Used mostly by other date range calculations to indicate an empty set.

Returns:

true or false, indicating whether the start date occurs after the end date

abuts

public boolean abuts(org.chronicj.DateRange anotherRange)

Used to detect whether two date ranges abut each other.

Parameters:

anotherRange - the range to check against

Returns:

true if the supplied DateRange argument abuts this range either occurring before or after

combination

public static org.chronicj.DateRange combination(org.chronicj.DateRange[] args)

compareTo

public int compareTo(java.lang.Object arg)

Compare the current DateRange instance to the one provided. The following algorithms are used if the start dates are not equal:

• whichever instance has a later start date (as determined by start() is the greater value

if the start dates are equal then:

• whichever instance has a later end date (as determined by end() is the greater value
• if the end dates are equal, then the instances are equal

NOTE: results are non-deterministic if either DateRange isEmpty()

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

arg - Object to compare

Returns:

• -1 if this TimePoint occurs after the one supplied
• 0 if this TimePoint occurs at the same time as the one provided
• 1 if this TimePoint occurs after the one provided

Throws:

java.lang.ClassCastException - if argument is not a DateRange

java.lang.NullPointerException - if argument is null

See Also:

end

public org.chronicj.TimePoint end()

Accessor method for the TimePoint denoting the upper end of this range.

Returns:

the TimePoint which holds the current value of the end field

equals

public boolean equals(java.lang.Object arg)

Overrides:

equals in class java.lang.Object

gap

public org.chronicj.DateRange gap(org.chronicj.DateRange arg)

Used to determine the duration of time (expressed as another DateRange) between the current DateRange instance and another DateRange. For now, the default precision, DatePrecision.MINUTE, is used.

Parameters:

arg - the other DateRange against which to determine an intervening gap

Returns:

anotherRange DateRange delimiting beginning and ending times of the gap

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

includes

public boolean includes(org.chronicj.TimePoint aDate)

Used to check whether a given TimePoint occurs within the current range.

Parameters:

aDate - the TimePoint that is to be checked for occurence within the current range

Returns:

true or false, indicating whether the supplied Date occurs within the current range

includes

public boolean includes(org.chronicj.DateRange arg)

Used to check whether a given DateRange occurs within the current range.

Parameters:

arg - the DateRange that is to be checked for occurence within the current range

Returns:

true or false, indicating whether the supplied DateRange occurs within the current range

overlaps

public boolean overlaps(org.chronicj.DateRange anotherRange)

Used mostly by other date range calculations to indicate an empty set.

Parameters:

anotherRange - the other DateRange against which to determine an intervening gap

Returns:

true or false, indicating whether the start date occurs after the end date

partitionedBy

public boolean partitionedBy(org.chronicj.DateRange[] otherRanges)

Used to check whether a group of ranges completely partition the current DateRange. For this to be true, the given set of DateRange arguments,must be contiguous with respect to each other and, when combined, equal the current range.

Parameters:

otherRanges - the set of DateRange objects to check against

Returns:

true if the supplied ranges completely partition this range, false otherwise

start

public org.chronicj.TimePoint start()

Accessor method for the TimePoint denoting the lower end of this range.

Returns:

the TimePoint which holds the current value of the start field

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object