net.agmodel.physical
Class Period

java.lang.Object
  net.agmodel.physical.Period

All Implemented Interfaces:

Cloneable, Comparable, Serializable

Direct Known Subclasses:

Interval

public class Period

extends Object

implements Serializable, Comparable, Cloneable

Represents a subset of time with an optional beginning and an optional end. See Interval for a more useful way of representing Periods which have both beginning and ending times.
For convenience, Periods implement the beginning and end of time as an early Date (0 AD), and the latest Date supported by Java respectively. These have the advantage of comparing sensibly with other dates. Calls to getBeginning() and getEnd() will return these dates, but applications can avoid using them with the hasBeginning and hasEnd() functions.
Periods are immutable.

Author:

Matthew Laurenson

See Also:

Serialized Form

Constructor Summary

Period()
Constructs a Period with no beginning and no end.

Period(Date aDate, boolean endless)
Constructs a Period from a date and an indicator as whether endless.
If endless is true, construct an period starting from aDate but not ending.
If endless is false, construct a period with no beginning ending at aDate.

Period(Date aStart, Date anEnd)
Constructs a Period from a starting and an ending Date (both non-null with ending date after starting date) After some experimentation I've let startdate==enddate - it is more useful.

Period(Date aStart, Duration duration)
Constructs a Period from an starting Date and a duration

Period(Duration duration, Date anEnd)
Constructs a Period from a duration and an ending Date

Method Summary

Object	clone()
boolean	coincidesWith(Date input) Indicates whether the input date falls within the partially closed interval (start,end] This method is consistent with coincides(Period); See coincidesWith(Date boolean, boolean) for a more flexible version
boolean	coincidesWith(Date input, boolean includeStart, boolean includeEnd) Indicates whether the input date falls within the interval See coincidesWith(Date) for a simpler version
boolean	coincidesWith(Period another) Indicates whether this period overlaps in time with another. Returns true if this period
int	compareTo(Object a) Compares two periods based on start time, and then end time if the start times are equal
boolean	encompasses(Period another) Determines whether another Period lies within this one.
static Date	getBeginningOfTime() A Date which will suffice in most situations as the beginning of time This implementation may change to an earlier date at a later date.
static Date	getEarlierOf(Date a, Date b) Selects the earlier of two Dates Both Dates must be non-null.
Date	getEnd()
static Date	getEndOfTime() A Date corresponding to the end of time
static Date	getLaterOf(Date a, Date b) Selects the later of two Dates Both Dates must be non-null.
Date	getStart()
boolean	hasBeginning() Indicates whether the Period begins
boolean	hasEnd() Indicates whether the Period ends
String	toString()
Period	unionWith(Period another) Creates a new Period which minimally encompasses both this Period and the other The new period starts from the earlier of this period.getStart() and another.getStart() and ends at the later of thisPeriod.getEnd() and another.getEnd();

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Period

public Period(Date aStart,
              Date anEnd)

Constructs a Period from a starting and an ending Date (both non-null with ending date after starting date) After some experimentation I've let startdate==enddate - it is more useful.

Throws:

IllegalArgumentException - if aStart is after aEnd

Period

public Period(Duration duration,
              Date anEnd)

Constructs a Period from a duration and an ending Date

Parameters:

duration - the duration of the period

anEnd - the ending date of the period

Period

public Period(Date aStart,
              Duration duration)

Constructs a Period from an starting Date and a duration

Parameters:

aStart - the starting date of the period

duration - the duration of the period

Period

public Period(Date aDate,
              boolean endless)

Constructs a Period from a date and an indicator as whether endless.
If endless is true, construct an period starting from aDate but not ending.
If endless is false, construct a period with no beginning ending at aDate.

Parameters:

aDate - the starting or ending date of a one-ended interval

endless - how to interpret aDate

Period

public Period()

Constructs a Period with no beginning and no end.

Method Detail

coincidesWith

public boolean coincidesWith(Period another)

Indicates whether this period overlaps in time with another.
Returns true if this period

|-----|

overlaps in time with another

|=======|

passed as the parameter.
This overlap can take several forms but the method doesn't distinguish between them.

  |---|
 |======|
 

or

 |----|
   |=====|
 

both return true.

If the start of the one equals the end of the other, the method returns false. eg

 |-----|
       |======|
 

returns false, and

              |-----|
       |======|

 

returns false.

This helps to avoid "double counting" of matching periods.

Parameters:

another - period to compare with this one

Returns:

true if the period passed overlaps with this period, false otherwise

coincidesWith

public boolean coincidesWith(Date input)

Indicates whether the input date falls within the partially closed interval (start,end] This method is consistent with coincides(Period); See coincidesWith(Date boolean, boolean) for a more flexible version

Parameters:

input - the Date in question

Returns:

true if input is within the exclusive interval (start,end)

coincidesWith

public boolean coincidesWith(Date input,
                             boolean includeStart,
                             boolean includeEnd)

Indicates whether the input date falls within the interval See coincidesWith(Date) for a simpler version

Parameters:

input - the Date in question

includeStart - if input=Interval.start then also return true

includeEnd - if input=Interval.end then also return true

Returns:

true if input is within the interval (start,end), (start,end], [start,end) or [start,end]

hasBeginning

public boolean hasBeginning()

Indicates whether the Period begins

Returns:

true if the Period has a beginning date, false if it doesn't

hasEnd

public boolean hasEnd()

Indicates whether the Period ends

Returns:

true if the Period has an ending date, false if it doesn't

getStart

public Date getStart()

Returns:

the starting date of the period. See hasBeginning for a nice way to handle periods with no end.

getEnd

public Date getEnd()

Returns:

the end of the period. See hasEnd for a nice way to handle periods with no end.

toString

public String toString()

compareTo

public int compareTo(Object a)

Compares two periods based on start time, and then end time if the start times are equal

Specified by:

compareTo in interface Comparable

Parameters:

a - Object to compare - assumed to be a Period

Returns:

-1 if this period starts before the other, or if the start times are equal and this period ends sooner.

clone

public Object clone()

getBeginningOfTime

public static Date getBeginningOfTime()

A Date which will suffice in most situations as the beginning of time This implementation may change to an earlier date at a later date.

Returns:

an early date (the birth of Christ approximately)

getEndOfTime

public static Date getEndOfTime()

A Date corresponding to the end of time

Returns:

latest date currently supported by Java

getEarlierOf

public static Date getEarlierOf(Date a,
                                Date b)

Selects the earlier of two Dates Both Dates must be non-null. The dates aren't cloned.

Parameters:

a - one date

b - another date

Returns:

the date which is before the other

getLaterOf

public static Date getLaterOf(Date a,
                              Date b)

Selects the later of two Dates Both Dates must be non-null. The dates aren't cloned.

Parameters:

a - one date

b - another date

Returns:

the date which is after the other

unionWith

public Period unionWith(Period another)

Creates a new Period which minimally encompasses both this Period and the other The new period starts from the earlier of this period.getStart() and another.getStart() and ends at the later of thisPeriod.getEnd() and another.getEnd();

Parameters:

another - the period to combine with this one

Returns:

a new Period covering the same period as both this and the other.

encompasses

public boolean encompasses(Period another)

Determines whether another Period lies within this one.

Parameters:

another - the period to test against this one

Returns:

true if the other period doesn't start earlier nor end later than this one.