org.dmfs.rfc5545

Class DateTime

java.lang.Object

org.dmfs.rfc5545.DateTime

public final class DateTime
extends java.lang.Object

Represents a DATE-TIME or DATE value as specified in RFC 5545, Section 3.3.5. This class stores all aspects of a DATE or DATETIME value.

Objects of this class are immutable.

Field Summary

Fields

Modifier and Type	Field and Description
static CalendarMetrics	GREGORIAN_CALENDAR_SCALE The default calendar scale.
static java.util.TimeZone	UTC Static instance of the time zone UTC.

Constructor Summary

Constructors

Constructor and Description
DateTime(CalendarMetrics calendarMetrics, DateTime dateTime) Clone constructor changing the CalendarMetrics.
DateTime(CalendarMetrics calendarMetrics, int year, int month, int dayOfMonth) Creates a new DateTime for the given all-day date using the given calendar metrics.
DateTime(CalendarMetrics calendarMetrics, int year, int month, int dayOfMonth, int hours, int minutes, int seconds) Create a new floating DateTime using the given calendar metrics.
DateTime(CalendarMetrics calendarMetrics, java.util.TimeZone timezone, DateTime dateTime) Clone constructor that changes the CalendarMetrics and the TimeZone.
DateTime(CalendarMetrics calendarMetrics, java.util.TimeZone timezone, int year, int month, int dayOfMonth, int hours, int minutes, int seconds) Creates a new absolute DateTime instance in the given TimeZone and calendar metrics.
DateTime(CalendarMetrics calendarMetrics, java.util.TimeZone timezone, long timestamp) Create a new DateTime from the given time stamp using the given CalendarMetrics and the given time zone.
DateTime(int year, int month, int dayOfMonth) Creates a new DateTime for the given all-day date using the GREGORIAN_CALENDAR_SCALE.
DateTime(int year, int month, int dayOfMonth, int hours, int minutes, int seconds) Create a new floating DateTime using GREGORIAN_CALENDAR_SCALE.
DateTime(long timestamp) Create a new DateTime from the given time stamp using GREGORIAN_CALENDAR_SCALE and UTC time zone.
DateTime(java.lang.String calScale, int year, int month, int dayOfMonth) Creates a new DateTime for the given all-day date using the given calendar scale.
DateTime(java.lang.String calScale, int year, int month, int dayOfMonth, int hours, int minutes, int seconds) Create a new floating DateTime using the given calendar scale.
DateTime(java.lang.String calScale, java.util.TimeZone timezone, int year, int month, int dayOfMonth, int hours, int minutes, int seconds) Creates a new absolute DateTime instance in the given TimeZone and calendar scale.
DateTime(java.util.TimeZone timezone, int year, int month, int dayOfMonth, int hours, int minutes, int seconds) Creates a new absolute DateTime instance in the given TimeZone using the GREGORIAN_CALENDAR_SCALE.
DateTime(java.util.TimeZone timezone, long timestamp) Create a new DateTime from the given time stamp using GREGORIAN_CALENDAR_SCALE and the given time zone.

Method Summary

Modifier and Type	Method and Description
DateTime	addDuration(Duration duration) Add the given duration to this DateTime.
boolean	after(DateTime that) Check if another date is earlier in time than this one.
boolean	before(DateTime that) Check if another date is later in time than this one.
boolean	equals(java.lang.Object obj)
CalendarMetrics	getCalendarMetrics() Returns the CalendarMetrics of this DateTime.
int	getDayOfMonth() Returns the month day of this date-time object.
int	getDayOfWeek() Returns the week day of this DateTime object.
int	getHours() Returns the hours in this date-time object.
long	getInstance() Get the packed instance value of this DateTime.
int	getMinutes() Returns the minutes in this date-time object.
int	getMonth() Returns the month of this date-time object.
int	getSeconds() Returns the seconds in this date-time object.
long	getTimestamp() Returns the timestamp of this DateTime instance.
java.util.TimeZone	getTimeZone() Returns the TimeZone of this DateTime.
int	getWeekOfYear() Returns the week of year of this date-time object.
int	getYear() Returns the year of this date-time object.
int	hashCode()
boolean	isAllDay() Returns whether this is an all-day instance.
boolean	isFloating() Returns whether this is a floating instance.
static DateTime	now() Return a new DateTime having the current date and time in UTC.
static DateTime	now(java.util.TimeZone timeZone) Return a new DateTime having the current date and time in the given TimeZone.
static DateTime	nowAndHere() Return a new DateTime having the current date and time in the local TimeZone.
static DateTime	parse(CalendarMetrics calendarMetrics, java.util.TimeZone timeZone, java.lang.String string) Parses a date-time string as specified in RFC 5545, Section 3.3.5.
static DateTime	parse(java.lang.String string) Parses a date-time string as specified in RFC 5545, Section 3.3.5.
static DateTime	parse(java.lang.String timeZone, java.lang.String string) Parses a date-time string as specified in RFC 5545, Section 3.3.5.
static DateTime	parse(java.lang.String calScale, java.util.TimeZone timeZone, java.lang.String string) Parses a date-time string as specified in RFC 5545, Section 3.3.5.
static DateTime	parse(java.util.TimeZone timeZone, java.lang.String string) Parses a date-time string as specified in RFC 5545, Section 3.3.5.
DateTime	shiftTimeZone(java.util.TimeZone timezone) Replace the current time zone by the given one, keeping the absolute time constant.
DateTime	startOfDay() Return the start of this day.
DateTime	swapTimeZone(java.util.TimeZone timezone) Replace the current time zone by the given one, keeping the local time constant.
DateTime	toAllDay() Get an all-day DateTime representing the day of this DateTime instance.
static DateTime	today() Return a new DateTime having the current date.
java.lang.String	toString()
void	writeTo(java.lang.StringBuilder out) Write the date-time string represented by this object to the given StringBuilder.
void	writeTo(java.io.Writer out) Write the date-time string represented by this object to the given Writer..

Methods inherited from class java.lang.Object

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

Field Detail

GREGORIAN_CALENDAR_SCALE

public static final CalendarMetrics GREGORIAN_CALENDAR_SCALE

The default calendar scale. By default all DateTime and Date values use the Gregorian calendar scale if not specified otherwise.

UTC

public static final java.util.TimeZone UTC

Static instance of the time zone UTC.

Constructor Detail

DateTime

public DateTime(CalendarMetrics calendarMetrics,
                DateTime dateTime)

Clone constructor changing the CalendarMetrics. It will represent the same absolute time, but instances will be in another calendar scale. All-day and floating instances will still be all-day respective floating.

Parameters:

calendarMetrics - The new calendar scale.

dateTime - The DateTime representing the absolute time.

DateTime

public DateTime(CalendarMetrics calendarMetrics,
                java.util.TimeZone timezone,
                DateTime dateTime)

Clone constructor that changes the CalendarMetrics and the TimeZone. It will represent the same absolute time, but instances will be in another calendar scale and time zone. You can use this to convert between calendar scales.

If the given DateTime is all-day the time zone will be ignored. If the given DateTime is floating it will be converted to an absolute time

Parameters:

calendarMetrics - The calendar scale to use.

timezone - The new TimeZone.

dateTime - The DateTime to clone from.

DateTime

public DateTime(long timestamp)

Create a new DateTime from the given time stamp using GREGORIAN_CALENDAR_SCALE and UTC time zone.

Parameters:

timestamp - The time in milliseconds since the epoch of this date-time value.

DateTime

public DateTime(java.util.TimeZone timezone,
                long timestamp)

Create a new DateTime from the given time stamp using GREGORIAN_CALENDAR_SCALE and the given time zone.

Parameters:

timezone - The TimeZone of the new instance.

timestamp - The time in milliseconds since the epoch of this date-time value.

DateTime

public DateTime(CalendarMetrics calendarMetrics,
                java.util.TimeZone timezone,
                long timestamp)

Create a new DateTime from the given time stamp using the given CalendarMetrics and the given time zone.

Parameters:

calendarMetrics - The CalendarMetrics of the DateTime.

timezone - The TimeZone of the new instance.

timestamp - The time in milliseconds since the epoch of this date-time value.

DateTime

public DateTime(int year,
                int month,
                int dayOfMonth)

Creates a new DateTime for the given all-day date using the GREGORIAN_CALENDAR_SCALE. As a result of this the all-day flag will be set to true.

Parameters:

year - The year of the event.

month - The month of the event.

dayOfMonth - The monthday of the event.

DateTime

public DateTime(int year,
                int month,
                int dayOfMonth,
                int hours,
                int minutes,
                int seconds)

Create a new floating DateTime using GREGORIAN_CALENDAR_SCALE.

Parameters:

year - The year.

month - The month.

dayOfMonth - The day of the month.

hours - The hour.

minutes - The minutes.

seconds - The seconds.

DateTime

public DateTime(java.util.TimeZone timezone,
                int year,
                int month,
                int dayOfMonth,
                int hours,
                int minutes,
                int seconds)

Creates a new absolute DateTime instance in the given TimeZone using the GREGORIAN_CALENDAR_SCALE.

Parameters:

timezone - The TimeZone of the date, may be null to create a floating date.

year - The year of the date.

month - The month.

dayOfMonth - The month day.

hours - The hours.

minutes - The minutes.

seconds - The seconds.

DateTime

public DateTime(java.lang.String calScale,
                int year,
                int month,
                int dayOfMonth)

Creates a new DateTime for the given all-day date using the given calendar scale. As a result of this the all-day flag will be set to true.

Parameters:

calScale - The name of the calendar scale to use.

year - The year of the event.

month - The month of the event.

dayOfMonth - The monthday of the event.

DateTime

public DateTime(java.lang.String calScale,
                int year,
                int month,
                int dayOfMonth,
                int hours,
                int minutes,
                int seconds)

Create a new floating DateTime using the given calendar scale.

Parameters:

calScale - The name of the calendar scale to use.

year - The year.

month - The month.

dayOfMonth - The day of the month.

hours - The hour.

minutes - The minutes.

seconds - The seconds.

DateTime

public DateTime(java.lang.String calScale,
                java.util.TimeZone timezone,
                int year,
                int month,
                int dayOfMonth,
                int hours,
                int minutes,
                int seconds)

Creates a new absolute DateTime instance in the given TimeZone and calendar scale.

Parameters:

calScale - The name of the calendar scale to use.

timezone - The TimeZone of the date, may be null to create a floating date.

year - The year of the date.

month - The month.

dayOfMonth - The month day.

hours - The hours.

minutes - The minutes.

seconds - The seconds.

DateTime

public DateTime(CalendarMetrics calendarMetrics,
                int year,
                int month,
                int dayOfMonth)

Creates a new DateTime for the given all-day date using the given calendar metrics.

Parameters:

calendarMetrics - The CalendarMetrics to use.

year - The year of the event.

month - The month of the event.

dayOfMonth - The monthday of the event.

DateTime

public DateTime(CalendarMetrics calendarMetrics,
                int year,
                int month,
                int dayOfMonth,
                int hours,
                int minutes,
                int seconds)

Create a new floating DateTime using the given calendar metrics.

Parameters:

calendarMetrics - The CalendarMetrics to use.

year - The year.

month - The month.

dayOfMonth - The day of the month.

hours - The hour.

minutes - The minutes.

seconds - The seconds.

DateTime

public DateTime(CalendarMetrics calendarMetrics,
                java.util.TimeZone timezone,
                int year,
                int month,
                int dayOfMonth,
                int hours,
                int minutes,
                int seconds)

Creates a new absolute DateTime instance in the given TimeZone and calendar metrics.

Parameters:

calendarMetrics - The CalendarMetrics to use.

timezone - The TimeZone of the date, may be null to create a floating date.

year - The year of the date.

month - The month.

dayOfMonth - The month day.

hours - The hours.

minutes - The minutes.

seconds - The seconds.

Method Detail

now

public static DateTime now()

Return a new DateTime having the current date and time in UTC. This is short for new DateTime(DateTime.GREGORIAN_CALENDAR_SCALE, DateTime.UTC, System.currentTimeMillis()).

nowAndHere

public static DateTime nowAndHere()

Return a new DateTime having the current date and time in the local TimeZone. This is short for new DateTime(DateTime.GREGORIAN_CALENDAR_SCALE, TimeZone.getDefault(), System.currentTimeMillis()).

now

public static DateTime now(java.util.TimeZone timeZone)

Return a new DateTime having the current date and time in the given TimeZone. This is short for new DateTime(DateTime.GREGORIAN_CALENDAR_SCALE, timeZone, System.currentTimeMillis()).

Parameters:

timeZone - The TimeZone of the DateTime instance.

today

public static DateTime today()

Return a new DateTime having the current date. This is short for new DateTime(DateTime.GREGORIAN_CALENDAR_SCALE, TimeZone.getDefault(), System.currentTimeMillis()).toAllDay().

parse

public static DateTime parse(java.lang.String string)

Parses a date-time string as specified in RFC 5545, Section 3.3.5. This method uses the default calendar scale GREGORIAN_CALENDAR_SCALE. Unless the given String ends with "Z" the resulting DateTime will be floating.

Parameters:

string - A valid date-time string.

Returns:

A new DateTime instance.

See Also:

parse(CalendarMetrics, TimeZone, String)

parse

public static DateTime parse(java.lang.String timeZone,
                             java.lang.String string)

Parses a date-time string as specified in RFC 5545, Section 3.3.5. This method uses the default calendar scale GREGORIAN_CALENDAR_SCALE.

Parameters:

timeZone - A time zone to apply to non-allday and non-UTC date-time values. If timeZone is null the event will be floating.

string - A valid date-time string.

Returns:

A new DateTime instance.

See Also:

parse(CalendarMetrics, TimeZone, String)

parse

public static DateTime parse(java.util.TimeZone timeZone,
                             java.lang.String string)

Parses a date-time string as specified in RFC 5545, Section 3.3.5. This method uses the default calendar scale GREGORIAN_CALENDAR_SCALE.

Parameters:

timeZone - A time zone to apply to non-allday and non-UTC date-time values. If timeZone is null the event will be floating.

string - A valid date-time string.

Returns:

A new DateTime instance.

See Also:

parse(CalendarMetrics, TimeZone, String)

parse

public static DateTime parse(java.lang.String calScale,
                             java.util.TimeZone timeZone,
                             java.lang.String string)

Parses a date-time string as specified in RFC 5545, Section 3.3.5. This method takes the name of the calendar scale to use.

Parameters:

calScale - The name of the calendar scale to use.

timeZone - A time zone to apply to non-allday and non-UTC date-time values. If timeZone is null the event will be floating.

string - A valid date-time string.

Returns:

A new DateTime instance.

See Also:

parse(CalendarMetrics, TimeZone, String)

parse

public static DateTime parse(CalendarMetrics calendarMetrics,
                             java.util.TimeZone timeZone,
                             java.lang.String string)

Parses a date-time string as specified in RFC 5545, Section 3.3.5. There are three valid forms of such a String:

• YYYYMMDD
• YYYYMMDD'T'HHMMSS
• YYYYMMDD'T'HHMMSS'Z'

where YYYYMMDD means a date (year, month, day of month) and HHMMSS means a time (hour, minute, second). 'T' and 'Z' stand for the literals T and Z.

If 'Z' is present the time zone is UTC. Otherwise the time zone is specified in an additional parameter or if no such parameter exists it's floating (i.e. always local time).

Use swapTimeZone(TimeZone) to set a specific time zone.

Parameters:

calendarMetrics - The CalendarMetrics to use.

timeZone - A time zone to apply to non-allday and non-UTC date-time values. If timeZone is null the event will be floating unless it ends with 'Z'.

string - A valid date-time string.

Returns:

A new DateTime instance.

getCalendarMetrics

public CalendarMetrics getCalendarMetrics()

Returns the CalendarMetrics of this DateTime.

Returns:

The CalendarMetrics instance.

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the TimeZone of this DateTime.

Returns:

The TimeZone or null for floating instances.

getTimestamp

public long getTimestamp()

Returns the timestamp of this DateTime instance. For floating dates, this equals the timestamp in UTC.

Returns:

the time in milliseconds since the epoch.

toAllDay

public DateTime toAllDay()

Get an all-day DateTime representing the day of this DateTime instance.

startOfDay

public DateTime startOfDay()

Return the start of this day. If this DateTime is floating or an all-day date, the result will be a floating DateTime at 0:00 local time. If this DateTime is not floating, the result will be at 0:00 in the current TimeZone.

Returns:

The start of this day.

swapTimeZone

public DateTime swapTimeZone(java.util.TimeZone timezone)

Replace the current time zone by the given one, keeping the local time constant. In effect the absolute time will change by the difference of the offsets to UTC of both time zones. Use this to convert a floating time to an absolute time in specific time zone.

Parameters:

timezone - The new TimeZone.

Throws:

java.lang.IllegalStateException - if the date is all-day.

shiftTimeZone

public DateTime shiftTimeZone(java.util.TimeZone timezone)

Replace the current time zone by the given one, keeping the absolute time constant. In effect the local time will change by the difference of the offsets to UTC of both time zones.

FIXME: There is a problem in case the time falls on a DST change. In that case the time might not be calculated as expected.

Parameters:

timezone - The new TimeZone.

Throws:

java.lang.IllegalStateException - if the date is all-day.

isAllDay

public boolean isAllDay()

Returns whether this is an all-day instance.

Returns:

true if this is all-day, false otherwise.

isFloating

public boolean isFloating()

Returns whether this is a floating instance.

Returns:

true if this is floating, false otherwise.

getYear

public int getYear()

Returns the year of this date-time object.

Returns:

The year of this date-time object.

getMonth

public int getMonth()

Returns the month of this date-time object.

Returns:

The month of this date-time object.

getWeekOfYear

public int getWeekOfYear()

Returns the week of year of this date-time object.

Returns:

The week of year of this date-time object.

getDayOfWeek

public int getDayOfWeek()

Returns the week day of this DateTime object.

Returns:

The week day of this DateTime object.

getDayOfMonth

public int getDayOfMonth()

Returns the month day of this date-time object.

Returns:

The month day of this date-time object.

getHours

public int getHours()

Returns the hours in this date-time object. For all-day dates this always returns 0.

Returns:

The hours in this date-time object.

getMinutes

public int getMinutes()

Returns the minutes in this date-time object. For all-day dates this always returns 0.

Returns:

The minutes in this date-time object.

getSeconds

public int getSeconds()

Returns the seconds in this date-time object. For all-day dates this always returns 0.

Returns:

The seconds in this date-time object.

addDuration

public DateTime addDuration(Duration duration)

Add the given duration to this DateTime. This method returns a new DateTime instance that represents the value after the duration has been added. Values are added with respect to the time zone, so daylight saving changes are taken into account when adding hours, minutes or seconds.

Parameters:

duration - The Duration to add.

Returns:

The new DateTime.

getInstance

public long getInstance()

Get the packed instance value of this DateTime. This is mostly for internal use.

Returns:

The packed instance value.

after

public boolean after(DateTime that)

Check if another date is earlier in time than this one.

Note: it doesn't make sense to compare a floating time to an absolute time. However, this method won't complain and treat floating times like UTC times.

Parameters:

that - The DateTime to compare to.

Returns:

true if this instance is after the given instance.

before

public boolean before(DateTime that)

Check if another date is later in time than this one.

Note: it doesn't make sense to compare a floating time to an absolute time. However, this method won't complain and treat floating times like UTC times.

Parameters:

that - The DateTime to compare to.

Returns:

true if this instance is before the given instance.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

writeTo

public void writeTo(java.lang.StringBuilder out)
             throws java.io.IOException

Write the date-time string represented by this object to the given StringBuilder. The written value conforms to RFC 5545, Section 3.3.5.

Examples:

 20150320
 20150320T123000
 20150320T123000Z
 

Parameters:

out - The StringBuilder to write to.

Throws:

java.io.IOException

writeTo

public void writeTo(java.io.Writer out)
             throws java.io.IOException

Write the date-time string represented by this object to the given Writer.. The written value conforms to RFC 5545, Section 3.3.5.

Examples:

 20150320
 20150320T123000
 20150320T123000Z
 

Parameters:

out - The Writer to write to.

Throws:

java.io.IOException