org.enblom.time
Interface Time

All Superinterfaces:

Comparable<Time>, Serializable

public interface Time
extends Comparable<Time>, Serializable

A complete time with date and time of day, and a lot of utilities.

The time is relative to the local timezone, and contains no timezone information. It is simply a "local time".

The framework is aware of leap years, but not of leap seconds nor daylight saving time corrections.

The timestamp contains year, month, day, hour, minute, second and millisecond information, and the valid range of times is from Jan 1, 1000, 00:00:00.000 to Dec 31, 9999, 23:59:59.999 (inclusive).

Time objects are always immutable - they cannot be changed once created.

The natural order of this class orders instances in chronological order, and two instances are considered equal if and only if they coincide on all parameters down to milliseconds.

Example usage

Create new instances:	Time.factory.now() Time.factory.getDefault() Time.factory.parse(...)
Formatting:	Time.iso().formatXXX() Time.eur().formatXXX() Time.us().formatXXX()
Serializing:	Time.serialize() Time.factory.deserialize()

Author:

Andreas Enblom

Field Summary

static TimeFactory

factory A default implementation of a TimeFactory, for creating new instances.

Method Summary

int	day()
boolean	equals(Object other)
TimeFormatter	eur() Provides a formatter for this time instance that formats timestamps according to some de-facto European standard.
DayDate	getDate()
DayOfWeek	getDayOfWeek() Calculates the day of week of this time.
TimeOfDay	getTimeOfDay()
int	hashCode()
int	hour()
boolean	isAfter(int hours, int minutes) Determines if this is after (inclusive) the given time of day.
boolean	isAfter(int hours, int minutes, int seconds) Determines if this is after (inclusive) the given time of day.
boolean	isAfter(Time time) Determines if this is after (inclusive) the given time.
boolean	isAfter(TimeOfDay timeOfDay) Determines if this is after (inclusive) the given time of day.
boolean	isBefore(int hours, int minutes) Determines if this is before (exclusive) the given time of day.
boolean	isBefore(int hours, int minutes, int seconds) Determines if this is before (exclusive) the given time of day.
boolean	isBefore(Time time) Determines if this is before (exclusive) the given time.
boolean	isBefore(TimeOfDay timeOfDay) Determines if this is before (exclusive) the given time of day.
boolean	isLaterDayThan(Time time) Determines whether this is in a later day than the given time.
boolean	isLaterHourThan(Time time) Determines whether this is in a later hour than the given time.
boolean	isLaterMinuteThan(Time time) Determines whether this is in a later minute than the given time.
boolean	isLaterMonthThan(Time time) Determines whether this is in a later month than the given time.
boolean	isLaterSecondThan(Time time) Determines whether this is in a later second than the given time.
boolean	isLaterYearThan(Time time) Determines whether this is in a later year than the given time.
TimeFormatter	iso() Provides a formatter for this time instance that formats timestamps according to the ISO-8601 standard.
boolean	isSameDayAs(Time time) Determines whether this is in the same day (of the same year) as the given time.
boolean	isSameHourAs(Time time) Determines whether this is in the same hour (of the same day and year) as the given time.
boolean	isSameMinuteAs(Time time) Determines whether this is in the same minute (of the same hour, day and year) as the given time.
boolean	isSameMonthAs(Time time) Determines whether this is in the same month and the same year as the given time.
boolean	isSameSecondAs(Time time) Determines whether this is in the same second (of the same minute, hour, day and year) as the given time.
boolean	isSameYearAs(Time time) Determines whether this is in the same year as the given time.
int	millis()
int	minute()
Month	month()
long	pack() Creates a long representation of the timestamp that is packed into the first 49 bits of the long, and still represents the timestamp uniquely.
Time	plusDays(int offset) Adds or subtracts the given number of days to this time.
Time	plusHours(int offset) Adds or subtracts the given number of hours to this time.
Time	plusMillis(long offset) Adds or subtracts the given number of milliseconds to this time.
Time	plusMinutes(long offset) Adds or subtracts the given number of minutes to this time.
Time	plusMonths(int offset) Adds or subtracts the given number of months to this time.
Time	plusSeconds(long offset) Adds or subtracts the given number of seconds to this time.
Time	plusYears(int offset) Adds or subtracts the given number of years to this time.
int	second()
String	serialize()
Date	toJavaUtilDate() Converts this time to a Date in the default timezone.
Date	toJavaUtilDate(TimeZone timeZone) Converts this time to a Date in the given timezone.
long	toLong() Creates an long representation of the timestamp, which when written in base 10 is the string YYYYMMDDhhmmssnnn, where nnn is the milliseconds.
String	toString() Overrides Object.toString().
TimeFormatter	us() Provides a formatter for this time instance that formats timestamps according to the US standard.
int	year()

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

factory

static final TimeFactory factory

A default implementation of a TimeFactory, for creating new instances. The factory will create serializable instances.

Method Detail

getDate

DayDate getDate()

Returns:

The date represented by this time, a full date with year, month and day of month.

getTimeOfDay

TimeOfDay getTimeOfDay()

Returns:

The time of day represented by this time.

year

int year()

Returns:

The year represented by this time in the range 1000-9999.

month

Month month()

Returns:

The month represented by this time.

day

int day()

Returns:

The day of month represented by this time in the range 1-28, 1-29, 1-30 or 1-31, depending on what month and year it is. Leap-years are handled correctly.

hour

int hour()

Returns:

The hour of the time of day represented by this time, in the range 0-23.

minute

int minute()

Returns:

The minute of the time of day represented by this time, in the range 0-59.

second

int second()

Returns:

The second of the time of day represented by this time, in the range 0-59.

millis

int millis()

Returns:

The millisecond of the time of day represented by this time, in the range 0-999.

getDayOfWeek

DayOfWeek getDayOfWeek()

Calculates the day of week of this time.

Returns:

The day of week.

plusYears

Time plusYears(int offset)

Adds or subtracts the given number of years to this time. If the resulting time is out of range, a runtime exception is thrown.

Parameters:

offset - The offset in years. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

plusMonths

Time plusMonths(int offset)

Adds or subtracts the given number of months to this time. If the resulting time is out of range, a runtime exception is thrown.

If adding the given number of months would make the day of month over the new month's maximum it will be reduced to the proper maximum. Hence, adding three months to 2011-05-31 will give 2011-08-31, but adding four will give 2011-09-30. And adding 13 months to 2010-01-30 will give the date 2011-02-28.

Parameters:

offset - The offset in months. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

plusDays

Time plusDays(int offset)

Adds or subtracts the given number of days to this time. If the resulting time is out of range, a runtime exception is thrown.

Parameters:

offset - The offset in days. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

plusHours

Time plusHours(int offset)

Adds or subtracts the given number of hours to this time. If the resulting time is out of range, a runtime exception is thrown.

Parameters:

offset - The offset in hours. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

plusMinutes

Time plusMinutes(long offset)

Adds or subtracts the given number of minutes to this time. If the resulting time is out of range, a runtime exception is thrown.

Parameters:

offset - The offset in minutes. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

plusSeconds

Time plusSeconds(long offset)

Adds or subtracts the given number of seconds to this time. If the resulting time is out of range, a runtime exception is thrown.

Parameters:

offset - The offset in seconds. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

plusMillis

Time plusMillis(long offset)

Adds or subtracts the given number of milliseconds to this time. If the resulting time is out of range, a runtime exception is thrown.

Parameters:

offset - The offset in millis. Can be positive, zero or negative.

Returns:

The resulting time.

Throws:

TimeOutOfRangeException - If the resulting time is out of range.

isAfter

boolean isAfter(Time time)

Determines if this is after (inclusive) the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is after the given time.

isAfter

boolean isAfter(TimeOfDay timeOfDay)

Determines if this is after (inclusive) the given time of day.

Parameters:

timeOfDay - The time of day to compare to.

Returns:

Whether this is after the given time of day.

isAfter

boolean isAfter(int hours,
                int minutes)

Determines if this is after (inclusive) the given time of day.

Parameters:

hours - The hour part of the time of day to compare to, in the range 0-23.

minutes - The minute part of the time of day to compare to, in the range 0-59.

Returns:

Whether this is after the given time of day.

isAfter

boolean isAfter(int hours,
                int minutes,
                int seconds)

Determines if this is after (inclusive) the given time of day.

Parameters:

hours - The hour part of the time of day to compare to, in the range 0-23.

minutes - The minute part of the time of day to compare to, in the range 0-59.

seconds - The second part of the time of day to compare to, in the range 0-59.

Returns:

Whether this is after the given time of day.

isBefore

boolean isBefore(Time time)

Determines if this is before (exclusive) the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is before the given time.

isBefore

boolean isBefore(TimeOfDay timeOfDay)

Determines if this is before (exclusive) the given time of day.

Parameters:

timeOfDay - The time of day to compare to.

Returns:

Whether this is before the given time of day.

isBefore

boolean isBefore(int hours,
                 int minutes)

Determines if this is before (exclusive) the given time of day.

Parameters:

hours - The hour part of the time of day to compare to, in the range 0-23.

minutes - The minute part of the time of day to compare to, in the range 0-59.

Returns:

Whether this is before the given time of day.

isBefore

boolean isBefore(int hours,
                 int minutes,
                 int seconds)

Determines if this is before (exclusive) the given time of day.

Parameters:

hours - The hour part of the time of day to compare to, in the range 0-23.

minutes - The minute part of the time of day to compare to, in the range 0-59.

seconds - The second part of the time of day to compare to, in the range 0-59.

Returns:

Whether this is before the given time of day.

isLaterYearThan

boolean isLaterYearThan(Time time)

Determines whether this is in a later year than the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in a later year than the given time.

isSameYearAs

boolean isSameYearAs(Time time)

Determines whether this is in the same year as the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in the same year as the given time.

isLaterMonthThan

boolean isLaterMonthThan(Time time)

Determines whether this is in a later month than the given time. A month of a later year is always considered to be later, e.g. Jan, 2011 is a later month than Nov, 2010.

Parameters:

time - The time to compare to.

Returns:

Whether this is in a later month than the given time.

isSameMonthAs

boolean isSameMonthAs(Time time)

Determines whether this is in the same month and the same year as the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in the same month as the given time.

isLaterDayThan

boolean isLaterDayThan(Time time)

Determines whether this is in a later day than the given time. A day of a later year is always considered to be later, e.g. Feb 5, 2011 is a later day than Nov 10, 2010, and a later day than Jan 10, 2011.

Parameters:

time - The time to compare to.

Returns:

Whether this is in a later day than the given time.

isSameDayAs

boolean isSameDayAs(Time time)

Determines whether this is in the same day (of the same year) as the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in the same day as the given time.

isLaterHourThan

boolean isLaterHourThan(Time time)

Determines whether this is in a later hour than the given time. A hour of a later day is always considered to be later, e.g. 10:13 on Jan 19, 2011 is a later hour than 13:00 on Jan 18, 2011 and than 13:00 on Dec 20, 2010.

Parameters:

time - The time to compare to.

Returns:

Whether this is in a later hour than the given time.

isSameHourAs

boolean isSameHourAs(Time time)

Determines whether this is in the same hour (of the same day and year) as the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in the same hour as the given time.

isLaterMinuteThan

boolean isLaterMinuteThan(Time time)

Determines whether this is in a later minute than the given time. A minute of a later hour or day is always considered to be later, e.g. 10:12 is a later minute than 9:13, and 10:13 on Jan 19 is a later minute than 10:25 on Jan 18, 2011 and than 13:25 on Dec 20, 2010.

Parameters:

time - The time to compare to.

Returns:

Whether this is in a later minute than the given time.

isSameMinuteAs

boolean isSameMinuteAs(Time time)

Determines whether this is in the same minute (of the same hour, day and year) as the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in the same minute as the given time.

isLaterSecondThan

boolean isLaterSecondThan(Time time)

Determines whether this is in a later second than the given time. A second of a later minute, hour or day is always considered to be later, e.g. 10:13:15 is a later second than 10:12:25 and than 9:13:25. And 10:13:15 on Jan 19 is a later second than 10:13:25 on Jan 18, 2011 and than 13:20:25 on Dec 20, 2010.

Parameters:

time - The time to compare to.

Returns:

Whether this is in a later second than the given time.

isSameSecondAs

boolean isSameSecondAs(Time time)

Determines whether this is in the same second (of the same minute, hour, day and year) as the given time.

Parameters:

time - The time to compare to.

Returns:

Whether this is in the same second as the given time.

equals

boolean equals(Object other)

Overrides:

equals in class Object

hashCode

int hashCode()

Overrides:

hashCode in class Object

iso

TimeFormatter iso()

Provides a formatter for this time instance that formats timestamps according to the ISO-8601 standard. For instance, this means that dates are formatted as YYYY-MM-DD and YYYYMMDD.

See also eur() and us().

Returns:

A formatter for this time that uses the ISO-8601 standard.

eur

TimeFormatter eur()

Provides a formatter for this time instance that formats timestamps according to some de-facto European standard. For instance, this means that dates are formatted as DD.MM.YYYY and DDMMYYYY.

See also iso() and us().

Returns:

A formatter for this time that uses some de-facto European standard.

us

TimeFormatter us()

Provides a formatter for this time instance that formats timestamps according to the US standard. For instance, this means that dates are formatted as MM/DD/YYYY and MMDDYYYY.

See also iso() and eur().

Returns:

A formatter for this time that uses the US standard.

serialize

String serialize()

Returns:

The full timestamp on the format YYYYMMDDhhmmssnnnn, where nnn is the milliseconds.

toJavaUtilDate

Date toJavaUtilDate()

Converts this time to a Date in the default timezone.

Returns:

The converted date.

toJavaUtilDate

Date toJavaUtilDate(TimeZone timeZone)

Converts this time to a Date in the given timezone.

Parameters:

timeZone - The time zone, or null to use the default time zone.

Returns:

The converted date.

toString

String toString()

Overrides Object.toString().

Overrides:

toString in class Object

Returns:

The timestamp on the format YYYY-MM-DD hh:mm:ss.nnn, where nnn is the milliseconds.

toLong

long toLong()

Creates an long representation of the timestamp, which when written in base 10 is the string YYYYMMDDhhmmssnnn, where nnn is the milliseconds. E.g, the timestamp 2011-03-02 16:42:14.308 is represented as the long 20110302164214308. Note that the maximum value is 99991231235959999, which is a valid long.

Returns:

The long representation.

pack

long pack()

Creates a long representation of the timestamp that is packed into the first 49 bits of the long, and still represents the timestamp uniquely. The representation is the number of milliseconds between the timestamp and Jan 1, 1000, 00:00:00.000, inclusively.

This can be used instead of the toLong() method (which uses the first 57 bits of the long) whenever data compression is of utmost importance. If it is not, consider using toLong() instead.

Returns:

The long representation.