Top Description Inners Fields Constructors Methods
net.fortuna.ical4j.model

public Class DateTime

extends Date
Class Inheritance
Annotations
@Deprecated
Imports
net.fortuna.ical4j.util.CompatibilityHints, .Dates, .TimeZones, org.apache.commons.lang3.builder.EqualsBuilder, java.text.DateFormat, .ParseException, .SimpleDateFormat, java.util.Collections, .Map, .WeakHashMap

Deprecated

Use java.time.Instant, java.time.LocalDateTime or java.time.ZonedDateTime for iCalendar DATE-TIME representations.

A representation of the DATE-TIME object defined in RFC5445.

Extract from RFC5545:

3.3.5.  Date-Time

Value Name:  DATE-TIME

Purpose:  This value type is used to identify values that specify a
precise calendar date and time of day.

Format Definition:  This value type is defined by the following
notation:

date-time  = date "T" time ;As specified in the DATE and TIME
;value definitions

Description:  If the property permits, multiple "DATE-TIME" values
are specified as a COMMA-separated list of values.  No additional
content value encoding (i.e., BACKSLASH character encoding, see
Section 3.3.11) is defined for this value type.

The "DATE-TIME" value type is used to identify values that contain
a precise calendar date and time of day.  The format is based on
the [ISO.8601.2004] complete representation, basic format for a
calendar date and time of day.  The text format is a concatenation
of the "date", followed by the LATIN CAPITAL LETTER T character,
the time designator, followed by the "time" format.

The "DATE-TIME" value type expresses time values in three forms:

The form of date and time with UTC offset MUST NOT be used.  For
example, the following is not valid for a DATE-TIME value:

19980119T230000-0800       ;Invalid time format

FORM #1: DATE WITH LOCAL TIME

The date with local time form is simply a DATE-TIME value that
does not contain the UTC designator nor does it reference a time
zone.  For example, the following represents January 18, 1998, at
11 PM:

19980118T230000

DATE-TIME values of this type are said to be "floating" and are
not bound to any time zone in particular.  They are used to
represent the same hour, minute, and second value regardless of
which time zone is currently being observed.  For example, an
event can be defined that indicates that an individual will be
busy from 11:00 AM to 1:00 PM every day, no matter which time zone
the person is in.  In these cases, a local time can be specified.
The recipient of an iCalendar object with a property value
consisting of a local time, without any relative time zone
information, SHOULD interpret the value as being fixed to whatever
time zone the "ATTENDEE" is in at any given moment.  This means
that two "Attendees", in different time zones, receiving the same
event definition as a floating time, may be participating in the
event at different actual times.  Floating time SHOULD only be
used where that is the reasonable behavior.

In most cases, a fixed time is desired.  To properly communicate a
fixed time in a property value, either UTC time or local time with
time zone reference MUST be specified.

The use of local time in a DATE-TIME value without the "TZID"
property parameter is to be interpreted as floating time,
regardless of the existence of "VTIMEZONE" calendar components in
the iCalendar object.

FORM #2: DATE WITH UTC TIME

The date with UTC time, or absolute time, is identified by a LATIN
CAPITAL LETTER Z suffix character, the UTC designator, appended to
the time value.  For example, the following represents January 19,
1998, at 0700 UTC:

19980119T070000Z

The "TZID" property parameter MUST NOT be applied to DATE-TIME
properties whose time values are specified in UTC.

FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE

The date and local time with reference to time zone information is
identified by the use the "TZID" property parameter to reference
the appropriate time zone definition.  "TZID" is discussed in
detail in Section 3.2.19.  For example, the following represents
2:00 A.M. in New York on January 19, 1998:

TZID=America/New_York:19980119T020000

If, based on the definition of the referenced time zone, the local
time described occurs more than once (when changing from daylight
to standard time), the DATE-TIME value refers to the first
occurrence of the referenced time.  Thus, TZID=America/
New_York:20071104T013000 indicates November 4, 2007 at 1:30 A.M.
EDT (UTC-04:00).  If the local time described does not occur (when
changing from standard to daylight time), the DATE-TIME value is
interpreted using the UTC offset before the gap in local times.
Thus, TZID=America/New_York:20070311T023000 indicates March 11,
2007 at 3:30 A.M. EDT (UTC-04:00), one hour after 1:30 A.M. EST
(UTC-05:00).

A time value MUST only specify the second 60 when specifying a
positive leap second.  For example:

19970630T235960Z

Implementations that do not support leap seconds SHOULD interpret
the second 60 as equivalent to the second 59.

Example:  The following represents July 14, 1997, at 1:30 PM in New
York City in each of the three time formats, using the "DTSTART"
property.

DTSTART:19970714T133000                   ; Local time
DTSTART:19970714T173000Z                  ; UTC time
DTSTART;TZID=America/New_York:19970714T133000
; Local time and time
; zone reference
Author
Ben Fortuna
Version
2.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
DateTime.DateFormatCache

This cache class is a workaround for DateFormat not being threadsafe.

Field Summary

Modifier and TypeField and Description
private static final DateTime.DateFormatCache
DEFAULT_FORMAT

Used for parsing times in a local date-time representation.

private static final String
private static final DateTime.DateFormatCache
private static final DateTime.DateFormatCache
private static final String
private static final long
private Time
time

References Deprecated Time is deprecated or references (maybe indirectly) at least one deprecated element.
private TimeZone
private static final DateTime.DateFormatCache
UTC_FORMAT

Used for parsing times in a UTC date-time representation.

private static final String
private static final DateTime.DateFormatCache
private static final String

Constructor Summary

AccessConstructor and Description
public
DateTime()

Default constructor.

public
DateTime(final boolean
indicates if the date is in UTC time
utc
)

public
DateTime(final long
a date-time value in milliseconds
time
)

public
DateTime(final Date
a date-time value
date
)

public
DateTime(final Date date, TimeZone timeZone)

public
DateTime(final String
a string representation of a date-time
value
)

Constructs a new DateTime instance from parsing the specified string representation in the default (local) timezone.

public
DateTime(final String
a string representation of a date-time
value
,
final TimeZone
the timezone for the date-time instance
timezone
)

Creates a new date-time instance from the specified value in the given timezone.

public
DateTime(String
a string representation of a date-time
value
,
String
a pattern to apply when parsing the date-time value
pattern
,
TimeZone
the timezone for the date-time instance
timezone
)

public
DateTime(String
a string representation of a date-time
value
,
String
a pattern to apply when parsing the date-time value
pattern
,
boolean
indicates whether the date-time is in UTC time
utc
)

Method Summary

Modifier and TypeMethod and Description
public boolean
equals(final Object
the object to compare with.
arg0
)

Overrides java.util.Date.equals.

Compares two dates for equality.

public final TimeZone

Returns:

a Java timezone
getTimeZone
()

Returns the current timezone associated with this date-time value.

public int
hashCode()

Overrides java.util.Date.hashCode.

Returns a hash code value for this object.

public final boolean

Returns:

Returns the utc.
isUtc
()

private void
resetTimeZone()

Reset the timezone to default.

private void
setTime(final String value, final DateFormat
a DateFormat, protected by the use of a ThreadLocal.
format
,
final TimeZone tz)

Internal set of time by parsing value string.

public final void
setTime(final long
the number of milliseconds.
time
)

Overrides net.fortuna.ical4j.model.Iso8601.setTime.

Sets this Date object to represent a point in time that is time milliseconds after January 1, 1970 00:00:00 GMT.

public final void
setTimeZone(final TimeZone
a timezone to apply to the instance
timezone
)

Sets the timezone associated with this date-time instance.

public final void
setUtc(final boolean
The utc to set.
utc
)

Updates this date-time to display in UTC time if the argument is true.

public final String
toString()

Overrides net.fortuna.ical4j.model.Iso8601.toString.

Converts this Date object to a String of the form:

dow mon dd hh:mm:ss zzz yyyy

Field Detail

DEFAULT_FORMATback to summary
private static final DateTime.DateFormatCache DEFAULT_FORMAT

Used for parsing times in a local date-time representation.

DEFAULT_PATTERNback to summary
private static final String DEFAULT_PATTERN

Hides net.fortuna.ical4j.model.Date.DEFAULT_PATTERN.

LENIENT_DEFAULT_FORMATback to summary
private static final DateTime.DateFormatCache LENIENT_DEFAULT_FORMAT
RELAXED_FORMATback to summary
private static final DateTime.DateFormatCache RELAXED_FORMAT
RELAXED_PATTERNback to summary
private static final String RELAXED_PATTERN
serialVersionUIDback to summary
private static final long serialVersionUID

Hides net.fortuna.ical4j.model.Date.serialVersionUID.

timeback to summary
private Time time

References Deprecated

Time is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

timezoneback to summary
private TimeZone timezone
UTC_FORMATback to summary
private static final DateTime.DateFormatCache UTC_FORMAT

Used for parsing times in a UTC date-time representation.

UTC_PATTERNback to summary
private static final String UTC_PATTERN
VCARD_FORMATback to summary
private static final DateTime.DateFormatCache VCARD_FORMAT
VCARD_PATTERNback to summary
private static final String VCARD_PATTERN

Hides net.fortuna.ical4j.model.Date.VCARD_PATTERN.

Constructor Detail

DateTimeback to summary
public DateTime()

Default constructor.

DateTimeback to summary
public DateTime(final boolean utc)
Parameters
utc:boolean

indicates if the date is in UTC time

DateTimeback to summary
public DateTime(final long time)
Parameters
time:long

a date-time value in milliseconds

DateTimeback to summary
public DateTime(final Date date)
Parameters
date:Date

a date-time value

DateTimeback to summary
public DateTime(final Date date, TimeZone timeZone)
DateTimeback to summary
public DateTime(final String value) throws ParseException

Constructs a new DateTime instance from parsing the specified string representation in the default (local) timezone.

Parameters
value:String

a string representation of a date-time

Exceptions
ParseException:
where the specified string is not a valid date-time
DateTimeback to summary
public DateTime(final String value, final TimeZone timezone) throws ParseException

Creates a new date-time instance from the specified value in the given timezone. If a timezone is not specified, the default timezone (as returned by TimeZones#getDefault()) is used.

Parameters
value:String

a string representation of a date-time

timezone:TimeZone

the timezone for the date-time instance

Exceptions
ParseException:
where the specified string is not a valid date-time
DateTimeback to summary
public DateTime(String value, String pattern, TimeZone timezone) throws ParseException
Parameters
value:String

a string representation of a date-time

pattern:String

a pattern to apply when parsing the date-time value

timezone:TimeZone

the timezone for the date-time instance

Exceptions
ParseException:
where the specified string is not a valid date-time
DateTimeback to summary
public DateTime(String value, String pattern, boolean utc) throws ParseException
Parameters
value:String

a string representation of a date-time

pattern:String

a pattern to apply when parsing the date-time value

utc:boolean

indicates whether the date-time is in UTC time

Exceptions
ParseException:
where the specified string is not a valid date-time

Method Detail

equalsback to summary
public boolean equals(final Object arg0)

Overrides java.util.Date.equals.

Doc from java.util.Date.equals.

Compares two dates for equality. The result is true if and only if the argument is not null and is a Date object that represents the same point in time, to the millisecond, as this object.

Thus, two Date objects are equal if and only if the getTime method returns the same long value for both.

Parameters
arg0:Object

the object to compare with.

Returns:boolean

true if the objects are the same; false otherwise.

Annotations
@Override
getTimeZoneback to summary
public final TimeZone getTimeZone()

Returns the current timezone associated with this date-time value.

Returns:TimeZone

a Java timezone

hashCodeback to summary
public int hashCode()

Overrides java.util.Date.hashCode.

Doc from java.util.Date.hashCode.

Returns a hash code value for this object. The result is the exclusive OR of the two halves of the primitive long value returned by the Date#getTime method. That is, the hash code is the value of the expression:

(int)(this.getTime()^(this.getTime() >>> 32))
Returns:int

a hash code value for this object.

Annotations
@Override
isUtcback to summary
public final boolean isUtc()
Returns:boolean

Returns the utc.

resetTimeZoneback to summary
private void resetTimeZone()

Reset the timezone to default.

setTimeback to summary
private void setTime(final String value, final DateFormat format, final TimeZone tz) throws ParseException

Internal set of time by parsing value string.

Parameters
format:DateFormat

a DateFormat, protected by the use of a ThreadLocal.

setTimeback to summary
public final void setTime(final long time)

Overrides net.fortuna.ical4j.model.Iso8601.setTime.

Doc from net.fortuna.ical4j.model.Iso8601.setTime.

Sets this Date object to represent a point in time that is time milliseconds after January 1, 1970 00:00:00 GMT.

Parameters
time:long

Doc from java.util.Date.setTime.

the number of milliseconds.

Annotations
@Override
setTimeZoneback to summary
public final void setTimeZone(final TimeZone timezone)

Sets the timezone associated with this date-time instance. If the specified timezone is null, it will reset to the default timezone. If the date-time instance is utc, it will turn into either a floating (no timezone) date-time, or a date-time with a timezone.

Parameters
timezone:TimeZone

a timezone to apply to the instance

setUtcback to summary
public final void setUtc(final boolean utc)

Updates this date-time to display in UTC time if the argument is true. Otherwise, resets to the default timezone.

Parameters
utc:boolean

The utc to set.

toStringback to summary
public final String toString()

Overrides net.fortuna.ical4j.model.Iso8601.toString.

Doc from net.fortuna.ical4j.model.Iso8601.toString.

Converts this Date object to a String of the form:

dow mon dd hh:mm:ss zzz yyyy
where:
  • dow is the day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat).
  • mon is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
  • dd is the day of the month (01 through 31), as two decimal digits.
  • hh is the hour of the day (00 through 23), as two decimal digits.
  • mm is the minute within the hour (00 through 59), as two decimal digits.
  • ss is the second within the minute (00 through 61), as two decimal digits.
  • zzz is the time zone (and may reflect daylight saving time). Standard time zone abbreviations include those recognized by the method parse. If time zone information is not available, then zzz is empty - that is, it consists of no characters at all.
  • yyyy is the year, as four decimal digits.
Returns:String

Doc from java.util.Date.toString.

a string representation of this date.

Annotations
@Override
net.fortuna.ical4j.model back to summary

private Class DateTime.DateFormatCache

extends Object
Class Inheritance

This cache class is a workaround for DateFormat not being threadsafe. We maintain map from Thread to DateFormat instance so that the instances are not shared between threads (effectively a ThreadLocal).

Todo

once the project targets Java 8+, the new date utilities are thread-safe and we should remove this code.

Field Summary

Modifier and TypeField and Description
private final DateFormat
private final Map<Thread, DateFormat>
threadMap

This map needs to keep weak references (to avoid memory leaks - see r1.37) and be thread-safe (since it may be concurrently modified in get() below).

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public DateFormat
get()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

templateFormatback to summary
private final DateFormat templateFormat
threadMapback to summary
private final Map<Thread, DateFormat> threadMap

This map needs to keep weak references (to avoid memory leaks - see r1.37) and be thread-safe (since it may be concurrently modified in get() below).

Constructor Detail

DateFormatCacheback to summary
private DateFormatCache(DateFormat dateFormat)

Method Detail

getback to summary
public DateFormat get()