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:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<java.util.Date>

public class DateTime
extends Date

$Id: DateTime.java,v 1.40 2011/02/20 03:12:32 fortuna Exp $ 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

DateTime()
Default constructor.

DateTime(boolean utc)

DateTime(java.util.Date date)

DateTime(long time)

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

DateTime(java.lang.String value, java.lang.String pattern, boolean utc)

DateTime(java.lang.String value, java.lang.String pattern, TimeZone timezone)

DateTime(java.lang.String value, TimeZone timezone)
Creates a new date-time instance from the specified value in the given timezone.

Method Summary

boolean	equals(java.lang.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.
java.lang.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(java.util.Date date)

Parameters:

date - a date-time value

DateTime

public DateTime(java.lang.String value)
         throws java.text.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:

java.text.ParseException - where the specified string is not a valid date-time

DateTime

public DateTime(java.lang.String value,
                TimeZone timezone)
         throws java.text.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:

java.text.ParseException - where the specified string is not a valid date-time

DateTime

public DateTime(java.lang.String value,
                java.lang.String pattern,
                TimeZone timezone)
         throws java.text.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:

java.text.ParseException - where the specified string is not a valid date-time

DateTime

public DateTime(java.lang.String value,
                java.lang.String pattern,
                boolean utc)
         throws java.text.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:

java.text.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 java.lang.String toString()

Overrides:

toString in class Iso8601

equals

public boolean equals(java.lang.Object arg0)

Overrides:

equals in class java.util.Date

hashCode

public int hashCode()

Overrides:

hashCode in class java.util.Date