com.programix.time
Class DateTimeRange

java.lang.Object
  com.programix.time.DateTimeRange

All Implemented Interfaces:

Serializable, Cloneable, Comparable<DateTimeRange>

public final class DateTimeRange
extends Object
implements Serializable, Comparable<DateTimeRange>, Cloneable

Immutable encapsulation of a period of time as expressed by a starting DateTime and an ending DateTime. Either the starting date or the ending date or both can be null. If you need a date span that does not include any time-of-day and/or time zone information, see PlainDateRange.

DateTools has handy utilities for formatting and parsing DateTime instances to and from more human-readable Strings.

Author:

Paul Hyde

See Also:

DateTime, PlainDate, PlainDateRange, Serialized Form

Field Summary

static DateTimeRange	BOTH_OPEN This DateTimeRange has both an undefined start and an undefined end.
static Comparator<DateTimeRange>	NEWEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "newest" or "most recent" first.
static Comparator<DateTimeRange>	OLDEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "oldest" first.
static DateTime	OPEN This constant can be used to specify that either the start or end of of the range is "open" (that is, it is not defined and can be considered to stretch out to infinity).

Constructor Summary

DateTimeRange(DateTime start, DateTime end)
Creates a new instance with the specified start and end times.

Method Summary

Object	clone() Simply returns a reference to this instance.
int	compareTo(DateTimeRange otherRange) Compares this instance to otherRange as defined by OLDEST_FIRST_COMPARATOR.
boolean	contains(DateTime dateTime) Returns true if the specified DateTime falls within this range (inclusive of both endpoints).
static DateTimeRange	createLocal(String start, String end) Creates a new instance with the specified start and end times parsed using the local timezone.
static DateTimeRange	createUTC(String start, String end) Creates a new instance with the specified start and end times parsed using the UTC timezone.
static DateTimeRange	createWithOpenEnd(DateTime start) Creates a new instance with an open end time and the specified start time.
static DateTimeRange	createWithOpenStart(DateTime end) Creates a new instance with an open start and the specified end date.
boolean	equals(DateTimeRange otherDateTime) Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance.
boolean	equals(Object obj) Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance.
DateTime	forceIntoRange(DateTime value) Forces the specified DateTime into this range.
DateTime	getEnd() Returns the end of this range.
Value	getEndValue() Returns the end of this range as a Value.
DateTime	getStart() Returns the start of this range.
Value	getStartValue() Returns the start of this range as a Value.
boolean	hasDefinedEnd() Returns true if this range has a defined end date.
boolean	hasDefinedStart() Returns true if this range has a defined start date.
int	hashCode()
DateTimeRange	setEnd(DateTime newEnd) Returns a new instance with the specified newEnd date and this instance's start date.
DateTimeRange	setStart(DateTime newStart) Returns a new instance with the specified start date and this instance's end time.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

OPEN

public static final DateTime OPEN

This constant can be used to specify that either the start or end of of the range is "open" (that is, it is not defined and can be considered to stretch out to infinity). A range with an open starting time would be considered to "have always been" or considered to have an "unknown beginning time". A range with an open end time would be considered to "be for all future time" or considered to have an "unknown ending time".

BOTH_OPEN

public static final DateTimeRange BOTH_OPEN

This DateTimeRange has both an undefined start and an undefined end. This is a shareable instance as all instances of DateTimeRange are immutable. In addition, there is no need to create any other instances that have both ends open (although is it permissible to create those instances).

OLDEST_FIRST_COMPARATOR

public static final Comparator<DateTimeRange> OLDEST_FIRST_COMPARATOR

Compares two ranges placing ranges that are considered "oldest" first. Open start times are considered to come before defined start times. Open end times are considered to come after defined end times. The following are listed in the order that would result by using this Comparator (time-of-date is not shown for simplicity):

    open    to 1997-02-02
    open    to 1997-09-09
    open    to 2000-02-02
    open    to 2000-03-03
    open    to    open
 1997-02-02 to 1997-02-02
 1997-02-03 to 1997-02-03
 1997-06-06 to 1997-09-09
 1997-06-06 to 1997-10-10
 1997-06-06 to    open
 1997-07-07 to 1997-08-08
 1997-08-08 to 1997-09-09
 1997-08-08 to    open
 1997-09-09 to    open
 

Also see NEWEST_FIRST_COMPARATOR is it is not simply the reverse of this comparator.

For additional permutations, see NullFirstComparator, NullLastComparator, and ReverseComparator.

NEWEST_FIRST_COMPARATOR

public static final Comparator<DateTimeRange> NEWEST_FIRST_COMPARATOR

Compares two ranges placing ranges that are considered "newest" or "most recent" first. Open end times are considered to come before defined end times. Open start times are considered to come after defined start times. The following are listed in the order that would result by using this Comparator (time-of-date is not shown for simplicity):

 1997-09-09 to    open
 1997-08-08 to    open
 1997-06-06 to    open
    open    to    open
    open    to 2000-03-03
    open    to 2000-02-02
 1997-06-06 to 1997-10-10
 1997-08-08 to 1997-09-09
 1997-06-06 to 1997-09-09
    open    to 1997-09-09
 1997-07-07 to 1997-08-08
 1997-02-03 to 1997-02-03
 1997-02-02 to 1997-02-02
    open    to 1997-02-02
 

Also see OLDEST_FIRST_COMPARATOR is it is not simply the reverse of this comparator.

For additional permutations, see NullFirstComparator, NullLastComparator, and ReverseComparator.

Constructor Detail

DateTimeRange

public DateTimeRange(DateTime start,
                     DateTime end)
              throws IllegalArgumentException

Creates a new instance with the specified start and end times. The constant OPEN (or null) can be used to indicate that one end or the other is open-ended. Both the start and the end can be open, and if you prefer, there is a shared, immutable instance that can be used instead: BOTH_OPEN.

Parameters:

start - the beginning of the range. Use OPEN or null to indicate that the range is open-ended and has no starting time.

end - the ending of the range. Use OPEN or null to indicate that the range is open-ended and has no end time.

Throws:

IllegalArgumentException - if the start time comes after the end time.

See Also:

createLocal(String, String), createUTC(String, String)

Method Detail

createLocal

public static DateTimeRange createLocal(String start,
                                        String end)
                                 throws IllegalArgumentException,
                                        DateTimeException

Creates a new instance with the specified start and end times parsed using the local timezone. You can use null or an empty string to indicate that one end or the other (or both) is open-ended.

Parameters:

start - the beginning of the time range. Use null or an empty string to indicate that the range is open-ended and has no starting time.

end - the ending of the time range. Use null or an empty string to indicate that the range is open-ended and has no ending time.

Throws:

IllegalArgumentException - if the start time comes after the end time.

DateTimeException - if either String can not be parsed as a DateTime.

See Also:

createUTC(String, String), DateTimeRange(DateTime, DateTime), DateTools.parseLocal(String)

createUTC

public static DateTimeRange createUTC(String start,
                                      String end)
                               throws IllegalArgumentException,
                                      DateTimeException

Creates a new instance with the specified start and end times parsed using the UTC timezone. You can use null or an empty string to indicate that one end or the other (or both) is open-ended. You can also use a Value who's isEmpty() method returns true to indicate that one end or the other (or both) is open-ended.

Parameters:

start - the beginning of the time range. Use null or an empty string to indicate that the range is open-ended and has no starting time.

end - the ending of the time range. Use null or an empty string to indicate that the range is open-ended and has no ending time.

Throws:

IllegalArgumentException - if the start time comes after the end time.

DateTimeException - if either String can not be parsed as a DateTime.

See Also:

createLocal(String, String), DateTimeRange(DateTime, DateTime), DateTools.parseUTC(String)

createWithOpenStart

public static DateTimeRange createWithOpenStart(DateTime end)

Creates a new instance with an open start and the specified end date.

Parameters:

end - the end of the date range.

createWithOpenEnd

public static DateTimeRange createWithOpenEnd(DateTime start)

Creates a new instance with an open end time and the specified start time.

Parameters:

start - the start of the date range.

setStart

public DateTimeRange setStart(DateTime newStart)
                       throws IllegalArgumentException

Returns a new instance with the specified start date and this instance's end time.

Parameters:

newStart - the new start date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end.

See Also:

DateTimeRange(DateTime, DateTime)

setEnd

public DateTimeRange setEnd(DateTime newEnd)
                     throws IllegalArgumentException

Returns a new instance with the specified newEnd date and this instance's start date.

Parameters:

newEnd - the new end date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end.

See Also:

DateTimeRange(DateTime, DateTime)

hasDefinedStart

public boolean hasDefinedStart()

Returns true if this range has a defined start date. If no start is defined, then this range is open-ended and false is returned.

See Also:

getStart()

getStart

public DateTime getStart()

Returns the start of this range. If no starting date was specified, then this range is open-ended and OPEN (null) is returned.

See Also:

hasDefinedStart(), getStartValue()

getStartValue

public Value getStartValue()

Returns the start of this range as a Value. If no starting date was specified, then this range is open-ended and an empty Value is returned. Unlike most of the other getters, a Value is always returned—null is never returned.

See Also:

hasDefinedStart(), getStart()

hasDefinedEnd

public boolean hasDefinedEnd()

Returns true if this range has a defined end date. If no end is defined, then this range is open-ended and false is returned.

See Also:

getEnd()

getEnd

public DateTime getEnd()

Returns the end of this range. If no ending date was specified, then this range is open-ended and OPEN (null) is returned.

See Also:

hasDefinedEnd()

getEndValue

public Value getEndValue()

Returns the end of this range as a Value. If no ending date was specified, then this range is open-ended and an empty Value is returned. Unlike most of the other getters, a Value is always returned—null is never returned.

See Also:

hasDefinedEnd(), getEnd()

contains

public boolean contains(DateTime dateTime)

Returns true if the specified DateTime falls within this range (inclusive of both endpoints). If null is passed in, then false is always returned (regardless of the values of either endpoint). If this instance has a defined start, but an unknown end, then true is returned if the passed date is equal to or comes after the start. If this instance has a defined end, but an unknown start, then true is returned if the passed date is equal to or comes before the end. If this instance has both ends open and the passed parameter is not null, then true is returned.

forceIntoRange

public DateTime forceIntoRange(DateTime value)
                        throws IllegalArgumentException

Forces the specified DateTime into this range. If the specified date is contained with this range (see contains(DateTime)), then the passed date is simply returned (no forcing is necessary). If the range has a defined start and the specified date comes before that start, then the start is returned. If the range has a defined end and the specified date comes after that end, then the end is returned.

Parameters:

value - the date to force into this range.

Returns:

a date that is within this range.

Throws:

IllegalArgumentException - if the specified date is null.

compareTo

public int compareTo(DateTimeRange otherRange)
              throws IllegalArgumentException

Compares this instance to otherRange as defined by OLDEST_FIRST_COMPARATOR.

Specified by:

compareTo in interface Comparable<DateTimeRange>

Throws:

IllegalArgumentException - if null if passed.

equals

public boolean equals(DateTimeRange otherDateTime)

Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance. If null is passed, false is returned.

equals

public boolean equals(Object obj)

Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance. If null is passed, false is returned. If a type other than DateTimeRange is passed in, false is returned (ClassCastException is not thrown).

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

clone

public Object clone()

Simply returns a reference to this instance. No need to actually clone since objects of this type are immutable.

Overrides:

clone in class Object