edu.nrao.sss.measure
Class TimeInterval

java.lang.Object
  edu.nrao.sss.measure.TimeInterval

All Implemented Interfaces:

Cloneable, Comparable<TimeInterval>

public class TimeInterval
extends Object
implements Cloneable, Comparable<TimeInterval>

An interval from one point in time to another.

This interval is half-open; it includes the starting point but does not include the ending point.

Caveat
July 2006. It might be that some of the query methods that compare one interval to another, or to a point, are not accurate for the degenerate case where one or both intervals have zero length. This possibility will be tested, and corrected, in the future. --DMH

Version Info:

$Revision: 1708 $

$Date: 2008-11-14 10:31:42 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2006-03-24

Author:

David M. Harland

Constructor Summary

TimeInterval()
Creates a new large interval.

TimeInterval(Date from, Date to)
Creates a new interval using the given times.

Method Summary

TimeInterval	clone() Returns a time interval that is equal to this one.
int	compareTo(TimeInterval other) Compares this interval to other for order.
boolean	contains(Date time) Returns true if time is contained in this interval.
boolean	contains(TimeInterval other) Returns true if this interval contains other.
boolean	equals(Object o) Returns true if o is equal to this time interval.
Date	getCenterTime() Returns the time that is midway between the endpoints of this interval.
TimeDuration	getDuration() Returns the time duration represented by this interval.
Date	getEnd() Returns a copy of this interval's ending time.
Date	getStart() Returns a copy of this interval's starting time.
int	hashCode() Returns a hash code value for this time interval.
boolean	isAfter(Date time) Returns true if this interval starts after the given time.
boolean	isAfter(TimeInterval other) Returns true if this interval starts after the other one ends.
boolean	isBefore(Date time) Returns true if this interval ends before the given time.
boolean	isBefore(TimeInterval other) Returns true if this interval ends before the other one starts.
boolean	isContainedBy(TimeInterval other) Returns true if the other interval contains this one.
boolean	isContiguousWith(TimeInterval other) Returns true if this interval and the other form a contiguous non-overlapping time interval.
boolean	isInDefaultState() Returns true if this interval is in its default state, no matter how it got there.
TimeInterval	makeGapFiller(TimeInterval other) Returns a new time interval that exactly plugs the gap between this interval and the other.
boolean	overlaps(TimeInterval other) Returns true if this interval overlaps the other interval.
static TimeInterval	parse(String iso8601Interval) Creates a new time interval based on the parameter text.
static TimeInterval	parse(String interval, String dateFormat, String separator) Creates a new time interval by parsing interval with the given formatter and separator.
void	reset() Resets this interval to its initial state.
void	set(Date from, Date to) Sets the starting and ending points of this interval.
void	set(String iso8601Interval)
void	set(String intervalText, String dateFormat, String separator) Sets the endpoints of this interval based on intervalText.
TimeInterval[]	split(Date pointOfSplit) Returns two new intervals that were formed by splitting this one at the given point.
String	toString() Creates a text representation of this time interval.
String	toString(String dateFormat, String separator) Returns a text representation of this interval based on the formatting parameters.

Methods inherited from class java.lang.Object

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

Constructor Detail

TimeInterval

public TimeInterval()

Creates a new large interval. The newly created interval begins prior to the current century and ends after the current millenium.

TimeInterval

public TimeInterval(Date from,
                    Date to)

Creates a new interval using the given times.

The description of the set(Date, Date) method applies to this constructor as well.

Parameters:

from - the starting point of this interval. The starting point is included in the interval.

to - the ending point of this interval. The ending point is not included in the interval.

Method Detail

reset

public void reset()

Resets this interval to its initial state.

A reset interval has the same state as one newly created by the no-argument constructor.

set

public void set(Date from,
                Date to)

Sets the starting and ending points of this interval.

By convention, the earlier date should be passed as the from parameter. However, this method will correct the situation where from is later than to, and use the earlier of the two parameters as the starting point of this interval. The later of the two times will be used as the ending point. Note that this range goes up to, but does not include, the ending point. That is, this interval is half-open, with the ending point excluded from the interval.

If either parameter is null, a IllegalArgumentException will be thrown.

Note that this method makes copies of the parameters; it does not maintain a reference to either parameter. This is done in order to maintain the integrity of the relationship between the starting and ending points of this interval.

Parameters:

from - the starting point of this interval. The starting point is included in the interval.

to - the ending point of this interval. The ending point is not included in the interval.

set

public void set(String intervalText,
                String dateFormat,
                String separator)

Sets the endpoints of this interval based on intervalText. If intervalText is null or "" (the empty string), the reset() method is called. Otherwise, the parsing is delegated to parse(String, String, String). See that method for details related to parsing.

set

public void set(String iso8601Interval)

getStart

public Date getStart()

Returns a copy of this interval's starting time. Note that the start time is included in this interval.

Returns:

a copy of this interval's starting time.

See Also:

set(Date, Date)

getEnd

public Date getEnd()

Returns a copy of this interval's ending time. Note that the end time is not included in this interval.

Returns:

a copy of this interval's ending time.

See Also:

set(Date, Date)

getCenterTime

public Date getCenterTime()

Returns the time that is midway between the endpoints of this interval.

Returns:

the center of this interval.

getDuration

public TimeDuration getDuration()

Returns the time duration represented by this interval.

Returns:

the time duration represented by this interval.

contains

public boolean contains(Date time)

Returns true if time is contained in this interval.

Note that this interval is half-open; it does not include its ending point.

Parameters:

time - the time to be tested for containment.

Returns:

true if time is contained in this interval.

contains

public boolean contains(TimeInterval other)

Returns true if this interval contains other.

Note that an interval that is equal to this one is not contained by this one. The best analogy is that of a rigid box with infinitely thin walls: a box that is exactly the same as another cannot fit inside it.

Parameters:

other - an interval that might be contained by this one.

Returns:

true if this interval contains other.

isContainedBy

public boolean isContainedBy(TimeInterval other)

Returns true if the other interval contains this one.

See contains(TimeInterval) for the definition of containment.

Parameters:

other - a time interval that might contain this one.

Returns:

true if the other interval contains this one.

isBefore

public boolean isBefore(TimeInterval other)

Returns true if this interval ends before the other one starts.

Parameters:

other - an interval that might come after this one.

Returns:

true if this interval ends before other starts.

isAfter

public boolean isAfter(TimeInterval other)

Returns true if this interval starts after the other one ends.

Parameters:

other - an interval that might come after this one.

Returns:

true if this interval starts after other ends.

isBefore

public boolean isBefore(Date time)

Returns true if this interval ends before the given time.

Parameters:

time - a point in time that might come after this interval.

Returns:

true if this interval ends before the given time.

isAfter

public boolean isAfter(Date time)

Returns true if this interval starts after the given time.

Parameters:

time - a point in time that might come after this interval.

Returns:

true if this interval starts after the given time.

isContiguousWith

public boolean isContiguousWith(TimeInterval other)

Returns true if this interval and the other form a contiguous non-overlapping time interval. Since a time interval is half open, this method returns true when either this interval starts at the same time the other one ends, or ends at the same time the other starts.

Parameters:

other - an interval that might be contiguous with this one.

Returns:

true if this interval and the other form a contiguous non-overlapping time interval.

overlaps

public boolean overlaps(TimeInterval other)

Returns true if this interval overlaps the other interval.

Note that equal intervals overlap, as do intervals that have a container-contained relationship.

Parameters:

other - an interval that might overlap this one.

Returns:

true if this interval overlaps the other interval.

isInDefaultState

public boolean isInDefaultState()

Returns true if this interval is in its default state, no matter how it got there.

An interval is in its default state if both its endpoints are the same as those of an interval newly created via the no-argument constructor. An interval whose most recent update came via the reset method is also in its default state.

Returns:

true if this interval is in its default state.

split

public TimeInterval[] split(Date pointOfSplit)

Returns two new intervals that were formed by splitting this one at the given point. This interval is not altered by this method.

Scenario One. If this interval contains pointOfSplit, then the first interval in the array runs from this interval's starting point to pointOfSplit, and the second interval runs from pointOfSplit to this interval's ending point.

Scenario Two. If this interval does not contain pointOfSplit, then the first interval in the array will be equal to this one, and the second interval will be a zero length interval whose starting and ending endpoints are both pointOfSplit.

Parameters:

pointOfSplit - the point at which to split this interval in two.

Returns:

an array of two intervals whose combined length equals this interval's length.

makeGapFiller

public TimeInterval makeGapFiller(TimeInterval other)

Returns a new time interval that exactly plugs the gap between this interval and the other.

If this interval is contiguous with, or overlaps, other, null is returned. Otherwise, a new interval is created and valued such that it fills the gap between this interval and the other. Note that the gap is filled regardless of whether other is before or after this interval.

Parameters:

other - an interval that might not overlap, or be contiguous with, this interval, and for which a gap-filling interval is sought.

Returns:

a new interval that fills the gap between this one and other, or null if there is no gap.

parse

public static TimeInterval parse(String iso8601Interval)

Creates a new time interval based on the parameter text.

This is a convenience method that is equivalent to:

   parse(iso8601Interval, FormatString.ISO8601_DATE_TIME_TIMEZONE,
                          FormatString.ISO8601_TIME_INTERVAL_SEPARATOR);

Parameters:

iso8601Interval - the text to be parsed and converted into a time interval.

Returns:

a new time interval based on iso8601Interval. If iso8601Interval is null or "" (the empty string), a new time interval of length zero is returned.

See Also:

parse(String, String, String)

parse

public static TimeInterval parse(String interval,
                                 String dateFormat,
                                 String separator)

Creates a new time interval by parsing interval with the given formatter and separator. The general form is StartDateSeparatorEndDate, with the particulars of the date format determined by dateFormat.

Parameters:

interval - the text to be parsed and converted into a time interval. If this value is null or "" (the empty string), a new time interval of length zero is returned.

dateFormat - the text that determines the format of the start and end dates in interval. These are the same formats used in SimpleDateFormat. A list of ISO 8601 format strings may be found in FormatString.

separator - the text that separates the start date from the end date in interval.

Returns:

a new time interval based on the text of interval.

Throws:

IllegalArgument - if interval cannot be parsed using dateFormat and separator.

toString

public String toString()

Creates a text representation of this time interval. The format of the returned string is the full ISO 8601 representation of a time interval and looks something like this: yyyy-mm-ddThh:mm:ss.sss+zzzz/yyyy-mm-ddThh:mm:ss.sss+zzzz, where the 'T' and '/' are literals and the '+' is either a '+' or '-'.

A call to this method is equivalent to:

    toString(FormatString.ISO8601_DATE_TIME_TIMEZONE,
             FormatString.ISO8601_TIME_INTERVAL_SEPARATOR);

Overrides:

toString in class Object

toString

public String toString(String dateFormat,
                       String separator)

Returns a text representation of this interval based on the formatting parameters. For a description of these parameters, see parse(String, String, String).

clone

public TimeInterval clone()

Returns a time interval that is equal to this one.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this time interval.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this time interval.

Overrides:

hashCode in class Object

compareTo

public int compareTo(TimeInterval other)

Compares this interval to other for order.

One interval is deemed to be "less than" the other if it begins before the other. In the case that two intervals start at the same time, the one that ends first is considered to be less than the other.

Specified by:

compareTo in interface Comparable<TimeInterval>

Parameters:

other - the time interval to which this one is compared.

Returns:

a negative integer, zero, or a positive integer as this interval is less than, equal to, or greater than the other interval.