org.restlet.engine.util

Class InternetDateFormat

java.lang.Object

java.text.Format

java.text.DateFormat

org.restlet.engine.util.InternetDateFormat

All Implemented Interfaces:

Serializable, Cloneable

public class InternetDateFormat
extends DateFormat

This class handles Internet date/time strings in accordance with RFC 3339. It provides static methods to convert from various Java constructs (long, Date, and Calendar) to RFC 3339 format strings and to parse these strings back into the same Java constructs.

In addition to the static utility methods, this class also wraps a Calendar object allowing this class to be used as a value object in place of a Java construct.

Strings are parsed in accordance with the RFC 3339 format:

 YYYY-MM-DD(T|t|\s)hh:mm:ss[.ddd][tzd]
 

The tzd represents the time zone designator and is either an upper or lower case 'Z' indicating UTC or a signed hh:mm offset.

Author:

Frank Hellwig (frank@hellwig.org)

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.text.DateFormat

DateFormat.Field

Field Summary

Fields

Modifier and Type	Field and Description
static TimeZone	UTC A time zone with zero offset and no DST.

Fields inherited from class java.text.DateFormat

AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD

Constructor Summary

Constructors

Constructor and Description
InternetDateFormat() Creates a new InternetDateFormat object set to the current time using the UTC (Z) time zone.
InternetDateFormat(Calendar cal) Creates a new InternetDateFormat object initialized from a Calendar object.
InternetDateFormat(Date date) Creates a new InternetDateFormat object initialized from a Date object using the UTC (Z) time zone.
InternetDateFormat(Date date, TimeZone zone) Creates a new InternetDateFormat object initialized from a Date object using the specified time zone.
InternetDateFormat(long time) Creates a new InternetDateFormat object initialized from a millisecond time value using the UTC (Z) time zone.
InternetDateFormat(long time, TimeZone zone) Creates a new InternetDateFormat object initialized from a millisecond time value using the specified time zone.
InternetDateFormat(String s) Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.
InternetDateFormat(TimeZone zone) Creates a new InternetDateFormat object set to the current time using the specified time zone.

Method Summary

Methods

Modifier and Type	Method and Description
StringBuffer	format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition)
Calendar	getCalendar() Gets the Calendar object wrapped by this InternetDateFormat object.
Date	getDate() Gets the value of this InternetDateFormat object as a Date object.
long	getTime() Gets the value of this InternetDateFormat object as millisecond time value.
static String	now() Returns the current date and time as an RFC 3339 date/time string using the UTC (Z) time zone.
static String	now(TimeZone zone) Returns the current date and time as an RFC 3339 date/time string using the specified time zone.
Date	parse(String source)
Date	parse(String source, ParsePosition pos)
static Calendar	parseCalendar(String s) Parses an RFC 3339 date/time string to a Calendar object.
static Date	parseDate(String s) Parses an RFC 3339 date/time string to a Date object.
static long	parseTime(String s) Parses an RFC 3339 date/time string to a millisecond time value.
String	toString() Converts this InternetDateFormat object to an RFC 3339 date/time string.
static String	toString(Calendar cal) Converts the specified Calendar object to an RFC 3339 date/time string.
static String	toString(Date date) Converts the specified Date object to an RFC 3339 date/time string using the UTC (Z) time zone.
static String	toString(Date date, TimeZone zone) Converts the specified Date object to an RFC 3339 date/time string using the specified time zone.
static String	toString(long time) Converts the specified millisecond time value to an RFC 3339 date/time string using the UTC (Z) time zone.
static String	toString(long time, TimeZone zone) Converts the specified millisecond time value to an RFC 3339 date/time string using the specified time zone.
static InternetDateFormat	valueOf(Date date) Creates a new InternetDateFormat object from the specified Date object using the UTC (Z) time zone.
static InternetDateFormat	valueOf(Date date, TimeZone zone) Creates a new InternetDateFormat object from the specified Date object using the specified time zone.
static InternetDateFormat	valueOf(long time) Creates a new InternetDateFormat object from the specified millisecond time value using the UTC (Z) time zone.
static InternetDateFormat	valueOf(long time, TimeZone zone) Creates a new InternetDateFormat object from the specified millisecond time value using the specified time zone.
static InternetDateFormat	valueOf(String s) Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.

Methods inherited from class java.text.DateFormat

clone, equals, format, format, getAvailableLocales, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, hashCode, isLenient, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone

Methods inherited from class java.text.Format

format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

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

Field Detail

UTC

public static final TimeZone UTC

A time zone with zero offset and no DST.

Constructor Detail

InternetDateFormat

public InternetDateFormat()

Creates a new InternetDateFormat object set to the current time using the UTC (Z) time zone.

InternetDateFormat

public InternetDateFormat(Calendar cal)

Creates a new InternetDateFormat object initialized from a Calendar object. The specified calendar object is cloned thereby isolating this InternetDateFormat object from any changes made to the specified calendar object after calling this constructor.

Parameters:

cal - the Calendar object

InternetDateFormat

public InternetDateFormat(Date date)

Creates a new InternetDateFormat object initialized from a Date object using the UTC (Z) time zone.

Parameters:

date - the Date object

InternetDateFormat

public InternetDateFormat(Date date,
                  TimeZone zone)

Creates a new InternetDateFormat object initialized from a Date object using the specified time zone.

Parameters:

date - the Date object

zone - the time zone to use

InternetDateFormat

public InternetDateFormat(long time)

Creates a new InternetDateFormat object initialized from a millisecond time value using the UTC (Z) time zone.

Parameters:

time - the millisecond time value

InternetDateFormat

public InternetDateFormat(long time,
                  TimeZone zone)

Creates a new InternetDateFormat object initialized from a millisecond time value using the specified time zone.

Parameters:

time - the millisecond time value

zone - the time zone to use

InternetDateFormat

public InternetDateFormat(String s)

Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.

Parameters:

s - the string to parse

Throws:

IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

InternetDateFormat

public InternetDateFormat(TimeZone zone)

Creates a new InternetDateFormat object set to the current time using the specified time zone.

Parameters:

zone - the time zone to use

Method Detail

now

public static String now()

Returns the current date and time as an RFC 3339 date/time string using the UTC (Z) time zone.

Returns:

an RFC 3339 date/time string (does not include milliseconds)

now

public static String now(TimeZone zone)

Returns the current date and time as an RFC 3339 date/time string using the specified time zone.

Parameters:

zone - the time zone to use

Returns:

an RFC 3339 date/time string (does not include milliseconds)

parseCalendar

public static Calendar parseCalendar(String s)

Parses an RFC 3339 date/time string to a Calendar object.

Parameters:

s - the string to parse

Returns:

the Calendar object

Throws:

IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

parseDate

public static Date parseDate(String s)

Parses an RFC 3339 date/time string to a Date object.

Parameters:

s - the string to parse

Returns:

the Date object

Throws:

IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

parseTime

public static long parseTime(String s)

Parses an RFC 3339 date/time string to a millisecond time value.

Parameters:

s - the string to parse

Returns:

the millisecond time value

Throws:

IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

toString

public static String toString(Calendar cal)

Converts the specified Calendar object to an RFC 3339 date/time string. Unlike the toString methods for Date and long, no additional variant of this method taking a time zone is provided since the time zone is built into the Calendar object.

Parameters:

cal - the Calendar object

Returns:

an RFC 3339 date/time string (does not include milliseconds)

toString

public static String toString(Date date)

Converts the specified Date object to an RFC 3339 date/time string using the UTC (Z) time zone.

Parameters:

date - the Date object

Returns:

an RFC 3339 date/time string (does not include milliseconds)

toString

public static String toString(Date date,
              TimeZone zone)

Converts the specified Date object to an RFC 3339 date/time string using the specified time zone.

Parameters:

date - the Date object

zone - the time zone to use

Returns:

an RFC 3339 date/time string (does not include milliseconds)

toString

public static String toString(long time)

Converts the specified millisecond time value to an RFC 3339 date/time string using the UTC (Z) time zone.

Parameters:

time - the millisecond time value

Returns:

an RFC 3339 date/time string (does not include milliseconds)

toString

public static String toString(long time,
              TimeZone zone)

Converts the specified millisecond time value to an RFC 3339 date/time string using the specified time zone.

Parameters:

time - the millisecond time value

zone - the time zone to use

Returns:

an RFC 3339 date/time string (does not include milliseconds)

valueOf

public static InternetDateFormat valueOf(Date date)

Creates a new InternetDateFormat object from the specified Date object using the UTC (Z) time zone.

Parameters:

date - the Date object

Returns:

the InternetDateFormat object

valueOf

public static InternetDateFormat valueOf(Date date,
                         TimeZone zone)

Creates a new InternetDateFormat object from the specified Date object using the specified time zone.

Parameters:

date - the Date object

zone - the time zone to use

Returns:

the InternetDateFormat object

valueOf

public static InternetDateFormat valueOf(long time)

Creates a new InternetDateFormat object from the specified millisecond time value using the UTC (Z) time zone.

Parameters:

time - the millisecond time value

Returns:

the InternetDateFormat object

valueOf

public static InternetDateFormat valueOf(long time,
                         TimeZone zone)

Creates a new InternetDateFormat object from the specified millisecond time value using the specified time zone.

Parameters:

time - the millisecond time value

zone - the time zone to use

Returns:

the InternetDateFormat object

valueOf

public static InternetDateFormat valueOf(String s)

Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.

Parameters:

s - the string to parse

Returns:

the InternetDateFormat object

Throws:

IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

format

public StringBuffer format(Date date,
                  StringBuffer toAppendTo,
                  FieldPosition fieldPosition)

Specified by:

format in class DateFormat

getCalendar

public Calendar getCalendar()

Gets the Calendar object wrapped by this InternetDateFormat object.

Overrides:

getCalendar in class DateFormat

Returns:

the cloned Calendar object

getDate

public Date getDate()

Gets the value of this InternetDateFormat object as a Date object.

Returns:

the Date object

getTime

public long getTime()

Gets the value of this InternetDateFormat object as millisecond time value.

Returns:

the millisecond time value

parse

public Date parse(String source)
           throws ParseException

Overrides:

parse in class DateFormat

Throws:

ParseException

parse

public Date parse(String source,
         ParsePosition pos)

Specified by:

parse in class DateFormat

toString

public String toString()

Converts this InternetDateFormat object to an RFC 3339 date/time string.

Overrides:

toString in class Object

Returns:

an RFC 3339 date/time string (does not include milliseconds)