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.

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.

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.
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
protected void	set(Date aStart, Date anEnd) Sets the start and end date, ensuring that start is before end Calls setStart(Date) and setEnd(Date) which clone the parameters passed.
protected void	set(Date aStart, Duration duration) Sets Period using an end date and duration Note that this method is protected rather than private to allow MutableInterval to set the start and end fields.
protected void	set(Duration duration, Date anEnd) Sets Period using an end date and duration Note that this method is protected rather than private to allow MutableInterval to set the start and end fields.
protected void	setEnd(Date anEnd) Changes the Period end date.
protected void	setStart(Date aStart) Changes the Period start date.
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, finalize, 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

setStart

protected void setStart(Date aStart)

Changes the Period start date. This method is made protected rather than private to allow MutableInterval to set the start and end fields.

Parameters:

aStart - the new start date for the Period (cloned), which must be before the current ending date.

See Also:

set(Date,Date)

setEnd

protected void setEnd(Date anEnd)

Changes the Period end date. This method is made protected rather than private to allow MutableInterval to set the start and end fields.

Parameters:

anEnd - the new end date for the Period (cloned), which must be after the current starting date,

See Also:

set(Date,Date)

set

protected void set(Date aStart,
                   Date anEnd)

Sets the start and end date, ensuring that start is before end Calls setStart(Date) and setEnd(Date) which clone the parameters passed. Note that this method is called by the Period constructors. It is made protected rather than private to allow MutableInterval to set the start and end fields.

set

protected void set(Duration duration,
                   Date anEnd)

Sets Period using an end date and duration Note that this method is protected rather than private to allow MutableInterval to set the start and end fields.

set

protected void set(Date aStart,
                   Duration duration)

Sets Period using an end date and duration Note that this method is protected rather than private to allow MutableInterval to set the start and end fields.

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()

Overrides:

toString in class Object

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()

Overrides:

clone in class Object

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.