net.fortuna.ical4j.model

## Class DateTime

- java.lang.Object
- - java.util.Date
  - - net.fortuna.ical4j.model.Iso8601
    - - net.fortuna.ical4j.model.Date
      - - net.fortuna.ical4j.model.DateTime

All Implemented Interfaces:
  Serializable, Cloneable, Comparable<Date>

    public class DateTime
    extends Date

$Id$ Created on 26/06/2005 Represents a time of day on a specific date.

     4.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.

        Formal Definition: The 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 character (US-ASCII decimal 44) separated list
        of values. No additional content value encoding (i.e., BACKSLASH
        character encoding) is defined for this value type.

        The "DATE-TIME" data type is used to identify values that contain a
        precise calendar date and time of day. The format is based on the
        [ISO 8601] 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 (US-ASCII decimal
        84) time designator, followed by the "time" format.

        The "DATE-TIME" data 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:

          DTSTART: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 Janurary 18, 1998, at 11 PM:

          DTSTART: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 (US-ASCII decimal 90), the UTC
        designator, appended to the time value. For example, the following
        represents January 19, 1998, at 0700 UTC:

          DTSTART: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 the
        section on Time Zone. For example, the following represents 2 AM in
        New York on Janurary 19, 1998:

               DTSTART;TZID=US-Eastern:19980119T020000

        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=US-Eastern:19970714T133000    ;Local time and time
                             ; zone reference

        A time value MUST ONLY specify 60 seconds when specifying the
        periodic "leap second" in the time value. For example:

          COMPLETED:19970630T235960Z

Author:
  Ben Fortuna
See Also:
  Serialized Form

### Constructor Summary

Constructors
Constructor and Description
`DateTime()` Default constructor.
`DateTime(boolean utc)`
`DateTime(Date date)`
`DateTime(long time)`
`DateTime(String value)` Constructs a new DateTime instance from parsing the specified string representation in the default (local) timezone.
`DateTime(String value, String pattern, boolean utc)`
`DateTime(String value, String pattern, TimeZone timezone)`
`DateTime(String value, TimeZone timezone)` Creates a new date-time instance from the specified value in the given timezone.

### Method Summary

Methods
`boolean` `equals(Object arg0)`
`TimeZone` `getTimeZone()` Returns the current timezone associated with this date-time value.
`int` `hashCode()`
`boolean` `isUtc()`
`void` `setTime(long time)`
`void` `setTimeZone(TimeZone timezone)` Sets the timezone associated with this date-time instance.
`void` `setUtc(boolean utc)` Updates this date-time to display in UTC time if the argument is true.
`String` `toString()`

### Methods inherited from class net.fortuna.ical4j.model.Iso8601

`getFormat`

### Methods inherited from class java.util.Date

`after, before, clone, compareTo, getDate, getDay, getHours, getMinutes, getMonth, getSeconds, getTime, getTimezoneOffset, getYear, parse, setDate, setHours, setMinutes, setMonth, setSeconds, setYear, toGMTString, toLocaleString, UTC`

### Methods inherited from class java.lang.Object

`finalize, getClass, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### DateTime

    public DateTime()

Default constructor.

#### DateTime

    public DateTime(boolean utc)

Parameters:
  `utc` - indicates if the date is in UTC time

#### DateTime

    public DateTime(long time)

Parameters:
  `time` - a date-time value in milliseconds

#### DateTime

    public DateTime(Date date)

Parameters:
  `date` - a date-time value

#### DateTime

    public DateTime(String value)
             throws ParseException

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

Parameters:
  `value` - a string representation of a date-time
Throws:
  `ParseException` - where the specified string is not a valid date-time

#### DateTime

    public DateTime(String value,
            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 `TimeZone.getDefault()`) is used.

Parameters:
  `value` - a string representation of a date-time
  `timezone` - the timezone for the date-time instance
Throws:
  `ParseException` - where the specified string is not a valid date-time

#### DateTime

    public DateTime(String value,
            String pattern,
            TimeZone timezone)
             throws ParseException

Parameters:
  `value` - a string representation of a date-time
  `pattern` - a pattern to apply when parsing the date-time value
  `timezone` - the timezone for the date-time instance
Throws:
  `ParseException` - where the specified string is not a valid date-time

#### DateTime

    public DateTime(String value,
            String pattern,
            boolean utc)
             throws ParseException

Parameters:
  `value` - a string representation of a date-time
  `pattern` - a pattern to apply when parsing the date-time value
  `utc` - indicates whether the date-time is in UTC time
Throws:
  `ParseException` - where the specified string is not a valid date-time

### Method Detail

#### setTime

    public final void setTime(long time)

Overrides:
  `setTime` in class `Iso8601`

#### isUtc

    public final boolean isUtc()

Returns:
  Returns the utc.

#### setUtc

    public final void setUtc(boolean utc)

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

Parameters:
  `utc` - The utc to set.

#### setTimeZone

    public final void setTimeZone(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` - a timezone to apply to the instance

#### getTimeZone

    public final TimeZone getTimeZone()

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

Returns:
  a Java timezone

#### toString

    public final String toString()

Overrides:
  `toString` in class `Iso8601`

#### equals

    public boolean equals(Object arg0)

Overrides:
  `equals` in class `Date`

#### hashCode

    public int hashCode()

Overrides:
  `hashCode` in class `Date`