Package org.restlet.engine.util

Class InternetDateFormat

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class InternetDateFormat
extends java.text.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

        java.text.DateFormat.Field

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.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 Description
      InternetDateFormat()
      Creates a new InternetDateFormat object set to the current time using the UTC (Z) 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, java.util.TimeZone zone)
      Creates a new InternetDateFormat object initialized from a millisecond time value using the specified time zone.
      InternetDateFormat​(java.lang.String s)
      Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.
      InternetDateFormat​(java.util.Calendar cal)
      Creates a new InternetDateFormat object initialized from a Calendar object.
      InternetDateFormat​(java.util.Date date)
      Creates a new InternetDateFormat object initialized from a Date object using the UTC (Z) time zone.
      InternetDateFormat​(java.util.Date date, java.util.TimeZone zone)
      Creates a new InternetDateFormat object initialized from a Date object using the specified time zone.
      InternetDateFormat​(java.util.TimeZone zone)
      Creates a new InternetDateFormat object set to the current time using the specified time zone.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.StringBuffer format​(java.util.Date date, java.lang.StringBuffer toAppendTo, java.text.FieldPosition fieldPosition)  
      java.util.Calendar getCalendar()
      Gets the Calendar object wrapped by this InternetDateFormat object.
      java.util.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 java.lang.String now()
      Returns the current date and time as an RFC 3339 date/time string using the UTC (Z) time zone.
      static java.lang.String now​(java.util.TimeZone zone)
      Returns the current date and time as an RFC 3339 date/time string using the specified time zone.
      java.util.Date parse​(java.lang.String source)  
      java.util.Date parse​(java.lang.String source, java.text.ParsePosition pos)  
      static java.util.Calendar parseCalendar​(java.lang.String s)
      Parses an RFC 3339 date/time string to a Calendar object.
      static java.util.Date parseDate​(java.lang.String s)
      Parses an RFC 3339 date/time string to a Date object.
      static long parseTime​(java.lang.String s)
      Parses an RFC 3339 date/time string to a millisecond time value.
      java.lang.String toString()
      Converts this InternetDateFormat object to an RFC 3339 date/time string.
      static java.lang.String toString​(long time)
      Converts the specified millisecond time value to an RFC 3339 date/time string using the UTC (Z) time zone.
      static java.lang.String toString​(long time, java.util.TimeZone zone)
      Converts the specified millisecond time value to an RFC 3339 date/time string using the specified time zone.
      static java.lang.String toString​(java.util.Calendar cal)
      Converts the specified Calendar object to an RFC 3339 date/time string.
      static java.lang.String toString​(java.util.Date date)
      Converts the specified Date object to an RFC 3339 date/time string using the UTC (Z) time zone.
      static java.lang.String toString​(java.util.Date date, java.util.TimeZone zone)
      Converts the specified Date object to an RFC 3339 date/time string 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, java.util.TimeZone zone)
      Creates a new InternetDateFormat object from the specified millisecond time value using the specified time zone.
      static InternetDateFormat valueOf​(java.lang.String s)
      Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.
      static InternetDateFormat valueOf​(java.util.Date date)
      Creates a new InternetDateFormat object from the specified Date object using the UTC (Z) time zone.
      static InternetDateFormat valueOf​(java.util.Date date, java.util.TimeZone zone)
      Creates a new InternetDateFormat object from the specified Date object using the specified time zone.

      • 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 java.util.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​(java.util.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​(java.util.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​(java.util.Date date,
                          java.util.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,
                          java.util.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​(java.lang.String s)
        Creates a new InternetDateFormat object by parsing an RFC 3339 date/time string.
        Parameters:
        s - the string to parse
        Throws:
        java.lang.IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

      • InternetDateFormat

        public InternetDateFormat​(java.util.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 java.lang.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 java.lang.String now​(java.util.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 java.util.Calendar parseCalendar​(java.lang.String s)
        Parses an RFC 3339 date/time string to a Calendar object.
        Parameters:
        s - the string to parse
        Returns:
        the Calendar object
        Throws:
        java.lang.IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

      • parseDate

        public static java.util.Date parseDate​(java.lang.String s)
        Parses an RFC 3339 date/time string to a Date object.
        Parameters:
        s - the string to parse
        Returns:
        the Date object
        Throws:
        java.lang.IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

      • parseTime

        public static long parseTime​(java.lang.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:
        java.lang.IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

      • toString

        public static java.lang.String toString​(java.util.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 java.lang.String toString​(java.util.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 java.lang.String toString​(java.util.Date date,
                                        java.util.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 java.lang.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 java.lang.String toString​(long time,
                                        java.util.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​(java.util.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​(java.util.Date date,
                                         java.util.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,
                                         java.util.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​(java.lang.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:
        java.lang.IllegalArgumentException - if the string is not a valid RFC 3339 date/time string

      • format

        public java.lang.StringBuffer format​(java.util.Date date,
                                     java.lang.StringBuffer toAppendTo,
                                     java.text.FieldPosition fieldPosition)
        Specified by:
        format in class java.text.DateFormat

      • getCalendar

        public java.util.Calendar getCalendar()
        Gets the Calendar object wrapped by this InternetDateFormat object.
        Overrides:
        getCalendar in class java.text.DateFormat
        Returns:
        the cloned Calendar object

      • getDate

        public java.util.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 java.util.Date parse​(java.lang.String source)
                     throws java.text.ParseException
        Overrides:
        parse in class java.text.DateFormat
        Throws:
        java.text.ParseException

      • parse

        public java.util.Date parse​(java.lang.String source,
                            java.text.ParsePosition pos)
        Specified by:
        parse in class java.text.DateFormat

      • toString

        public java.lang.String toString()
        Converts this InternetDateFormat object to an RFC 3339 date/time string.
        Overrides:
        toString in class java.lang.Object
        Returns:
        an RFC 3339 date/time string (does not include milliseconds)