org.jcoderz.commons.types
Class Period

java.lang.Object
  org.jcoderz.commons.types.Period

All Implemented Interfaces:

Serializable

public final class Period
extends Object
implements Serializable

A Period data type represents a period in time.

There are two types of periods. One that is day bound and the other one is milli-second bound. The day bound period has just set the hours, minutes, seconds, and milli-seconds set to zero. In other words, the first one is in day resolution whereas the second one is in milli-second resolution.

TODO: Refine

Author:

Michael Rumpf

See Also:

Serialized Form

Field Summary

static String

TYPE_NAME The name of this type.

Method Summary

boolean	after(Period other) Checks if this period is after the given period.
boolean	before(Period other) Checks if this period is before the given period.
static Period	createDayPeriod(Date date) A factory method to create a day period.
static Period	createDayPeriod(Date start, Date end) A factory method to create a period from two timestamps where the hours, minutes, seconds, and milli-seconds are stripped off.
static Period	createMonthPeriod(Date date) A factory method to create a month period.
static Period	createPeriod(Date start, Date end) A factory method to create a period from two timestamps of the type Date.
long	duration() Returns the duration of this Period in milliseconds.
boolean	equals(Object o)
Date	getEndTime() Returns the end date of the period.
Date	getNextPeriodStartTime() Returns the start time for the next period.
Date	getPrevPeriodEndTime() Returns the end time of the previous period.
Date	getStartTime() Returns the start date of the period.
int	hashCode()
Period	intersection(Period other) Returns the intersection of two periods.
boolean	isIncluded(Date date) Checks whether a specified date falls into the period defined by the instance.
boolean	isIncluded(Period other) Checks whether a specified period falls into the period defined by the instance.
Period	minus(long offset) Returns a Period object whose start/end time lies exactly offset milliseconds before the start/end time of this period.
Period	next() Returns the next Period.
Period	nextDay() Returns the day period, that lies after this period.
static Period	nextDay(Date date) Returns the day period, that lies after the given date.
Period	nextHour() Returns the next clock hour period, that lies after this period.
static Period	nextHour(Date date) Returns the next clock hour period, that lies after the given date.
Period	nextMonth() Returns the month period, that lies after this period.
static Period	nextMonth(Date date) Returns the month period, that lies after the given date.
boolean	overlap(Period period) Checks whether a specified period overlaps with this period.
Period	plus(long offset) Returns a Period object whose start/end time lies exactly offset milliseconds after the start/end time of this period.
Period	previous() Returns the previous Period.
Period	previousDay() Returns the day period, that lies before this period.
static Period	previousDay(Date date) Returns the day period, that lies before the given date.
Period	previousHour() Returns the next clock hour period, that lies this this period.
static Period	previousHour(Date date) Returns the previous clock hour period, that lies befor the given date.
Period	previousMonth() Returns the month period, that lies before this period.
static Period	previousMonth(Date date) Returns the month period, that lies before the given date.
String	toString()
Period	union(Period other) Returns the union of two periods.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_NAME

public static final String TYPE_NAME

The name of this type.

See Also:

Constant Field Values

Method Detail

createPeriod

public static Period createPeriod(Date start,
                                  Date end)
                           throws ArgumentMalformedException

A factory method to create a period from two timestamps of the type Date.

Parameters:

start - The start time to create the period from.

end - The end time to create the period from.

Returns:

The period created by the two timestamps.

Throws:

ArgumentMalformedException - when the end date is before the start date.

createDayPeriod

public static Period createDayPeriod(Date start,
                                     Date end)
                              throws ArgumentMalformedException

A factory method to create a period from two timestamps where the hours, minutes, seconds, and milli-seconds are stripped off.

Parameters:

start - The start time to create the period from.

end - The end time to create the period from.

Returns:

The period created by the two timestamps.

Throws:

ArgumentMalformedException - when the end date is before the start date.

createDayPeriod

public static Period createDayPeriod(Date date)
                              throws ArgumentMalformedException

A factory method to create a day period. This period starts and ends on the same day as the given date. The duration of this period is exactly Date.MILLIS_PER_DAY milliseconds. Example: for the date 2004-09-03T11:52:03.437Z this method will return the period 2004-09-03T00:00:00.000Z-2004-09-03T23:59:59.999Z.

Parameters:

date - The date that falls within the returned period.

Returns:

The period created by the two timestamps.

Throws:

ArgumentMalformedException - when the parameter date is null.

createMonthPeriod

public static Period createMonthPeriod(Date date)
                                throws ArgumentMalformedException

A factory method to create a month period. This period starts and ends on the same month as the given date. The duration of this period is exactly the duration of the month of the date. Example: for the date 2004-09-03T11:52:03.437Z this method will return a period 2004-09-01T00:00:00.000Z-2004-09-30T23:59:59.999Z.

Parameters:

date - The date that falls within the returned period.

Returns:

The period created by the two timestamps.

Throws:

ArgumentMalformedException - when the parameter date is null.

getStartTime

public Date getStartTime()

Returns the start date of the period.

Returns:

A Date marking the start of the period.

getEndTime

public Date getEndTime()

Returns the end date of the period.

Returns:

A Date marking the end of the period.

intersection

public Period intersection(Period other)

Returns the intersection of two periods.

Parameters:

other - The period that will be intersected with this instance.

Returns:

A new period that is the intersection between the two periods. Null is returned in case there is no intersection between the two periods.

union

public Period union(Period other)

Returns the union of two periods.

Parameters:

other - The period to create a union period with this instance.

Returns:

A new period that contains the intersection between the two periods or null if the two periods do not intersect.

isIncluded

public boolean isIncluded(Date date)

Checks whether a specified date falls into the period defined by the instance.

Parameters:

date - The date that is checked whether it lies in the period.

Returns:

true when the date falls into the period, false otherwise.

isIncluded

public boolean isIncluded(Period other)

Checks whether a specified period falls into the period defined by the instance.

Parameters:

other - The period that is checked whether it lies in this period.

Returns:

true when the period falls into the period, false otherwise.

overlap

public boolean overlap(Period period)

Checks whether a specified period overlaps with this period.

Parameters:

period - The period to check for overlap with this period.

Returns:

true when the periods overlap, false otherwise.

getNextPeriodStartTime

public Date getNextPeriodStartTime()

Returns the start time for the next period.

Returns:

the start time for the next period.

getPrevPeriodEndTime

public Date getPrevPeriodEndTime()

Returns the end time of the previous period.

Returns:

the end time of the previous period.

duration

public long duration()

Returns the duration of this Period in milliseconds.

Returns:

The duration of this Period in milliseconds.

next

public Period next()

Returns the next Period. The duration of the next period is exactly the same as duration of this Period. The next period starts 1 millisecond after the end time of this period.

Returns:

The next Period.

previous

public Period previous()

Returns the previous Period. The duration of the previous period is exactly the same as duration of this Period. The previous period ends 1 millisecond before the start time of this period.

Returns:

The previous Period.

plus

public Period plus(long offset)

Returns a Period object whose start/end time lies exactly offset milliseconds after the start/end time of this period.

Parameters:

offset - The offset in milliseconds.

Returns:

The Period object whose start/end time lies exactly offset milliseconds after the start/end time of this period.

nextHour

public static Period nextHour(Date date)

Returns the next clock hour period, that lies after the given date. Example: for the date 2004-09-03T11:52:03 this method will return the period 2004-09-03T12:00:00.000Z-2004-09-03T12:59:59.999Z.

Parameters:

date - The date to get the next clock hour period.

Returns:

The next clock hour period, that lies after the given date.

nextHour

public Period nextHour()

Returns the next clock hour period, that lies after this period. This method returns Period.nextHour(getEndTime()).

Returns:

the next clock hour period, that lies after this period.

previousHour

public static Period previousHour(Date date)

Returns the previous clock hour period, that lies befor the given date. Example: for the date 2004-09-03T11:52:03 this method will return the period 2004-09-03T10:00:00.000Z-2004-09-03T10:59:59.999Z.

Parameters:

date - The date to get the previous clock hour period.

Returns:

the previous clock hour period, that lies befor the given date.

previousHour

public Period previousHour()

Returns the next clock hour period, that lies this this period. This method returns Period.previousHour(getSrartTime()).

Returns:

the next clock hour period, that lies before this period.

nextDay

public static Period nextDay(Date date)

Returns the day period, that lies after the given date. Example: for the date 2004-09-03T11:52:03 this method will return the period 2004-09-04T00:00:00.000Z-2004-09-04T23:59:59.999Z.

Parameters:

date - The date to get the next day period.

Returns:

The day period, that lies after the given date.

nextDay

public Period nextDay()

Returns the day period, that lies after this period. This method returns Period.nextDay(getEndTime()).

Returns:

The day period, that lies after the given date.

See Also:

nextDay(Date)

previousDay

public static Period previousDay(Date date)

Returns the day period, that lies before the given date. Example: for the date 2004-09-03T11:52:03 this method will return the period 2004-09-02T00:00:00.000Z-2004-09-02T23:59:59.999Z.

Parameters:

date - The date to get the previous day period.

Returns:

The day period, that lies before the given date.

previousDay

public Period previousDay()

Returns the day period, that lies before this period. This method returns Period.previousDay(getStartTime()).

Returns:

The the day period, that lies before this period.

See Also:

previousDay(Date)

nextMonth

public static Period nextMonth(Date date)

Returns the month period, that lies after the given date. Example: for the date 2004-09-03T11:52:03 this method will return the period 2004-10-01T00:00:00.000Z-2004-10-31T23:59:59.999Z.

Parameters:

date - The date to get the next month period.

Returns:

The the month period, that lies after the given date.

nextMonth

public Period nextMonth()

Returns the month period, that lies after this period. This method returns Period.nextMonth(getEndTime()).

Returns:

The the month period, that lies after this period.

See Also:

nextMonth(Date)

previousMonth

public static Period previousMonth(Date date)

Returns the month period, that lies before the given date. Example: for the date 2004-09-03T11:52:03 this method will return the period 2004-08-01T00:00:00.000Z-2004-08-31T23:59:59.999Z.

Parameters:

date - The date to get the previous month period.

Returns:

The the month period, that lies before the given date.

previousMonth

public Period previousMonth()

Returns the month period, that lies before this period. This method returns Period.previousMonth(getStartTime()).

Returns:

The the month period, that lies before this period.

See Also:

previousMonth(Date)

minus

public Period minus(long offset)

Returns a Period object whose start/end time lies exactly offset milliseconds before the start/end time of this period.

Parameters:

offset - The offset in milliseconds.

Returns:

The Period object whose start/end time lies exactly offset milliseconds before the start/end time of this period.

before

public boolean before(Period other)

Checks if this period is before the given period.

Parameters:

other - the period to compare with.

Returns:

true, if this period is before the given period.

after

public boolean after(Period other)

Checks if this period is after the given period.

Parameters:

other - the period to compare with.

Returns:

true, if this period is after the given period.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object