com.cloudhopper.commons.util.time

Class DateTimePeriod

java.lang.Object

com.cloudhopper.commons.util.time.DateTimePeriod

Direct Known Subclasses:

DateTimeDay, DateTimeFiveMinutes, DateTimeHour, DateTimeMonth, DateTimeYear

public abstract class DateTimePeriod
extends Object

Represents two DateTime values that represent the "start" and "end" of a period of time. Useful for selecting data from a database for records between two DateTime values. The "start" DateTime is inclusive for the period, however the "end" DateTime is exclusive for the period. For example, a period of a month such as "January 2009" would have a start DateTime of "2009-01-01 00:00:00.000" and an end DateTime of "2009-02-01 00:00:00.000". Since the start date is inclusive and the end date is exclusive, the resulting SELECT statement would consist of: "DateCol" >= period.getStart() AND "DateCol" < period.getEnd() . NOTE: This cannot be used with a BETWEEN statement since the end date should not actually be included. This is more precise since databases may have different levels of precision such as no milliseconds, or perhaps nano precision. Also, this representation makes the internal calculations much easier since the end date would always be start.plusMonths(1).

Author:

joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DateTimePeriod(org.joda.time.DateTime start, org.joda.time.DateTime end, DateTimeDuration duration, String keyPattern, String longNamePattern, String shortNamePattern, String indexNamePattern)

Method Summary

Methods

Modifier and Type	Method and Description
static DateTimePeriod	create(DateTimeDuration duration, org.joda.time.DateTime start) Creates a new period for the specified duration starting from the provided DateTime.
static DateTimePeriod	createDay(org.joda.time.DateTime start)
static DateTimePeriod	createDay(int year, int month, int day, org.joda.time.DateTimeZone zone)
static DateTimePeriod	createFiveMinutes(org.joda.time.DateTime start)
static DateTimePeriod	createFiveMinutes(int year, int month, int day, int hour, int minute, org.joda.time.DateTimeZone zone)
static DateTimePeriod	createHour(org.joda.time.DateTime start)
static DateTimePeriod	createHour(int year, int month, int day, int hour, org.joda.time.DateTimeZone zone)
static List<DateTimePeriod>	createLastYearMonths(org.joda.time.DateTimeZone zone) Create a list of DateTimePeriods that represent the last year of YearMonth periods.
static DateTimePeriod	createMonth(org.joda.time.DateTime start)
static DateTimePeriod	createMonth(int year, int month, org.joda.time.DateTimeZone zone)
static DateTimePeriod	createYear(org.joda.time.DateTime start)
static DateTimePeriod	createYear(int year, org.joda.time.DateTimeZone zone)
boolean	equals(Object object) Compares another DateTimePeriod for equality if the internal start and end DateTimes equal this period.
abstract DateTimeDuration	getDefaultSubDuration() Gets the default "Group By" enumeration based on the duration for this period.
DateTimeDuration	getDuration() Gets the duration this period represents such as a Month, Year, etc.
org.joda.time.DateTime	getEnd() Gets the exclusive ending DateTime for this period.
String	getIndexName() Gets an index name for this period appropriate for display to only identify the particular row by the smallest possible identifer.
String	getKey() Gets a key that is unique to this period.
String	getLongName() Gets a long name for this period appropriate for display as the title for a report such as "January 2009".
abstract DateTimePeriod	getNext() Gets the next period based on the duration.
abstract DateTimePeriod	getPrevious() Gets the previous period based on the duration.
String	getShortName() Gets a short name for this period appropriate for display within a table of data to identify a row.
org.joda.time.DateTime	getStart() Gets the inclusive starting DateTime for this period.
int	hashCode() Hashcode computed based on the internal start and end DateTime hashCode values.
List<DateTimePeriod>	toDays() Converts this period to a list of day periods.
List<DateTimePeriod>	toFiveMinutes() Converts this period to a list of five minute periods.
List<DateTimePeriod>	toHours() Converts this period to a list of hour periods.
List<DateTimePeriod>	toMonths() Converts this period to a list of month periods.
List<DateTimePeriod>	toPeriods(DateTimeDuration duration) Converts this period to a list of periods for the given duration.
List<DateTimePeriod>	toYears() Converts this period to a list of year periods.

Methods inherited from class java.lang.Object

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

Constructor Detail

DateTimePeriod

protected DateTimePeriod(org.joda.time.DateTime start,
              org.joda.time.DateTime end,
              DateTimeDuration duration,
              String keyPattern,
              String longNamePattern,
              String shortNamePattern,
              String indexNamePattern)

Method Detail

getStart

public org.joda.time.DateTime getStart()

Gets the inclusive starting DateTime for this period.

Returns:

The inclusive starting DateTime for this period.

getEnd

public org.joda.time.DateTime getEnd()

Gets the exclusive ending DateTime for this period.

Returns:

The exclusive ending DateTime for this period.

getDuration

public DateTimeDuration getDuration()

Gets the duration this period represents such as a Month, Year, etc.

Returns:

The duration for this period

getKey

public String getKey()

Gets a key that is unique to this period. This key is unique and could be used in a HashTable, "select" box on a webpage, etc. A period can be recreated back from a key. For example:

• The year 2009 would have a key of "2009"
• The month January 2009 would have key of "2009-01"
• The day January 24, 2009 would have a key of "2009-01-24"
• The hour January 24, 2009 at 7 AM would have a key of "2009-01-24-07"
• The hour January 24, 2009 at 2 PM would have a key of "2009-01-24-14"
• The five minutes at January 24, 2009 at 2:15 PM would have a key of "2009-01-24-14-15"

Returns:

A key to this period such as "2009-01" to represent a period for January 2009.

getLongName

public String getLongName()

Gets a long name for this period appropriate for display as the title for a report such as "January 2009". For example:

• The year 2009 would have a long name of "2009"
• The month January 2009 would have a long name of "January 2009"
• The day January 24, 2009 would have a long name of "January 24, 2009"
• The hour January 24, 2009 at 7 AM would have a long name of "January 24, 2009 07:00"
• The hour January 24, 2009 at 2 PM would have a long name of "January 24, 2009 14:00"
• The five minutes at January 24, 2009 at 2:15 PM would have a long name of "January 24, 2009 14:15"

Returns:

The long name of the period such as "January 2009"

See Also:

getShortName(), getIndexName()

getShortName

public String getShortName()

Gets a short name for this period appropriate for display within a table of data to identify a row. A short name will be no longer than 10 characters. For example:

• The year 2009 would have a short name of "2009"
• The month January 2009 would have a short name of "2009-01"
• The day January 24, 2009 would have a short name of "2009-01-24"
• The hour January 24, 2009 at 7 AM would have a short name of "07:00"
• The hour January 24, 2009 at 2 PM would have a short name of "14:00"
• The five minutes at January 24, 2009 at 2:15 PM would have a short name of "14:15"

Returns:

The short name of the period such as "2009-01-24"

See Also:

getLongName(), getIndexName()

getIndexName

public String getIndexName()

Gets an index name for this period appropriate for display to only identify the particular row by the smallest possible identifer. An index name will be no longer than 4 characters. For example:

• The year 2009 would have an index name of "2009"
• The month January 2009 would have an index name of "01"
• The day January 24, 2009 would have an index name of "24"
• The hour January 24, 2009 at 7 AM would have an index name of "07"
• The hour January 24, 2009 at 2 PM would have an index name of "14"
• The five minutes at January 24, 2009 at 2:15 PM would have an index name of "15"

Returns:

The index name of the period such as "01" for January

See Also:

getLongName(), getShortName()

getNext

public abstract DateTimePeriod getNext()

Gets the next period based on the duration. For example, if this period represents a Month, this will return a period for the next Month.

Returns:

The next period

getPrevious

public abstract DateTimePeriod getPrevious()

Gets the previous period based on the duration. For example, if this period represents a Month, this will return a period for the previous Month.

Returns:

The previous period

getDefaultSubDuration

public abstract DateTimeDuration getDefaultSubDuration()

Gets the default "Group By" enumeration based on the duration for this period. The default "Group By" is usually the period "slice" one level below this one. For example, if this period is a month, this would return a grouping by year-month-day. If this period is a year, this would return a grouping by year-quarter.

Returns:

A default group by determined by this period's duration

toPeriods

public List<DateTimePeriod> toPeriods(DateTimeDuration duration)

Converts this period to a list of periods for the given duration. This is an alternative way to create a list of periods instead of calling each specific duration method such as toHours() or toDays(). Partial periods will not be included.

Returns:

A list of periods contained within this period for the specified duration

See Also:

toFiveMinutes(), toHours(), toDays(), toMonths(), toYears()

toFiveMinutes

public List<DateTimePeriod> toFiveMinutes()

Converts this period to a list of five minute periods. Partial five minute periods will not be included. For example, a period of "January 20, 2009 7 to 8 AM" will return a list of 12 five minute periods - one for each 5 minute block of time 0, 5, 10, 15, etc. On the other hand, a period of "January 20, 2009 at 13:04" would return an empty list since partial five minute periods are not included.

Returns:

A list of five minute periods contained within this period

toHours

public List<DateTimePeriod> toHours()

Converts this period to a list of hour periods. Partial hours will not be included. For example, a period of "January 20, 2009" will return a list of 24 hours - one for each hour on January 20, 2009. On the other hand, a period of "January 20, 2009 13:10" would return an empty list since partial hours are not included.

Returns:

A list of hour periods contained within this period

toDays

public List<DateTimePeriod> toDays()

Converts this period to a list of day periods. Partial days will not be included. For example, a period of "January 2009" will return a list of 31 days - one for each day in January. On the other hand, a period of "January 20, 2009 13:00-59" would return an empty list since partial days are not included.

Returns:

A list of day periods contained within this period

toMonths

public List<DateTimePeriod> toMonths()

Converts this period to a list of month periods. Partial months will not be included. For example, a period of "2009" will return a list of 12 months - one for each month in 2009. On the other hand, a period of "January 20, 2009" would return an empty list since partial months are not included.

Returns:

A list of month periods contained within this period

toYears

public List<DateTimePeriod> toYears()

Converts this period to a list of year periods. Partial years will not be included. For example, a period of "2009-2010" will return a list of 2 years - one for 2009 and one for 2010. On the other hand, a period of "January 2009" would return an empty list since partial years are not included.

Returns:

A list of year periods contained within this period

equals

public boolean equals(Object object)

Compares another DateTimePeriod for equality if the internal start and end DateTimes equal this period.

Overrides:

equals in class Object

Parameters:

object - The other DateTimePeriod

Returns:

True if the internal start and end DateTimes equal this period.

hashCode

public int hashCode()

Hashcode computed based on the internal start and end DateTime hashCode values.

Overrides:

hashCode in class Object

Returns:

A hashCode based on the hashCode of the internal start and end DateTime values.

create

public static DateTimePeriod create(DateTimeDuration duration,
                    org.joda.time.DateTime start)

Creates a new period for the specified duration starting from the provided DateTime.

Parameters:

duration - The duration for this period such as Month, Hour, etc.

start - The DateTime to start this period from

Returns:

A new period

createYear

public static DateTimePeriod createYear(int year,
                        org.joda.time.DateTimeZone zone)

createYear

public static DateTimePeriod createYear(org.joda.time.DateTime start)

createMonth

public static DateTimePeriod createMonth(int year,
                         int month,
                         org.joda.time.DateTimeZone zone)

createMonth

public static DateTimePeriod createMonth(org.joda.time.DateTime start)

createDay

public static DateTimePeriod createDay(int year,
                       int month,
                       int day,
                       org.joda.time.DateTimeZone zone)

createDay

public static DateTimePeriod createDay(org.joda.time.DateTime start)

createHour

public static DateTimePeriod createHour(int year,
                        int month,
                        int day,
                        int hour,
                        org.joda.time.DateTimeZone zone)

createHour

public static DateTimePeriod createHour(org.joda.time.DateTime start)

createFiveMinutes

public static DateTimePeriod createFiveMinutes(int year,
                               int month,
                               int day,
                               int hour,
                               int minute,
                               org.joda.time.DateTimeZone zone)

createFiveMinutes

public static DateTimePeriod createFiveMinutes(org.joda.time.DateTime start)

createLastYearMonths

public static List<DateTimePeriod> createLastYearMonths(org.joda.time.DateTimeZone zone)

Create a list of DateTimePeriods that represent the last year of YearMonth periods. For example, if its currently January 2009, this would return periods representing "January 2009, December 2008, ... February 2008"

Parameters:

zone -

Returns: