Class StdDateFormat

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public class StdDateFormat
    extends java.text.DateFormat
    Jackson's internal DateFormat implementation used by standard Date serializers and deserializers to implement default behavior: does NOT fully implement all aspects expected by DateFormat and as a consequence SHOULD NOT to be used by code outside core Jackson databind functionality. In particular, ParsePosition argument of parse(String, ParsePosition) and format(Date, StringBuffer, FieldPosition) methods is fully ignored; Jackson itself never calls these methods.

    For serialization defaults to using an ISO-8601 compliant format (format String "yyyy-MM-dd'T'HH:mm:ss.SSSZ") and for deserialization, both ISO-8601 and RFC-1123.
    Note that `Z` in format String refers to ISO-8601 time offset notation which produces values like "-08:00" -- that is, full minute/hour combo without colon, and not using `Z` as alias for "+00:00". Inclusion of colon as separator, as default setting, started in Jackson 2.11: prior versions omitted it. Note that it is possible to enable/disable use of colon in time offset by using method withColonInTimeZone(boolean) for creating new differently configured format instance, and configuring ObjectMapper with it.

    TODO: in Jackson 2.14 or later, should change behavior to fail if ParsePosition is specified by caller (at least with non-0 offset).

    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.lang.String DATE_FORMAT_STR_ISO8601
      Defines a commonly used date format that conforms to ISO-8601 date formatting standard, when it includes basic undecorated timezone definition.
      static StdDateFormat instance
      A singleton instance can be used for cloning purposes, as a blueprint of sorts.
      • Fields inherited from class java.text.DateFormat

        AM_PM_FIELD, 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, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD
    • Constructor Summary

      Constructors 
      Constructor Description
      StdDateFormat()  
      StdDateFormat​(java.util.TimeZone tz, java.util.Locale loc)
      Deprecated.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      StdDateFormat clone()  
      boolean equals​(java.lang.Object o)  
      java.lang.StringBuffer format​(java.util.Date date, java.lang.StringBuffer toAppendTo, java.text.FieldPosition fieldPosition)  
      static java.util.TimeZone getDefaultTimeZone()  
      static java.text.DateFormat getISO8601Format​(java.util.TimeZone tz, java.util.Locale loc)
      Deprecated.
      Since 2.9
      static java.text.DateFormat getRFC1123Format​(java.util.TimeZone tz, java.util.Locale loc)
      Deprecated.
      Since 2.9
      java.util.TimeZone getTimeZone()  
      int hashCode()  
      boolean isColonIncludedInTimeZone()
      Accessor for checking whether this instance would include colon within timezone serialization or not: if {code true}, timezone offset is serialized like -06:00; if {code false} as -0600.
      boolean isLenient()  
      java.util.Date parse​(java.lang.String dateStr)  
      java.util.Date parse​(java.lang.String dateStr, java.text.ParsePosition pos)  
      void setLenient​(boolean enabled)
      Need to override since we need to keep track of leniency locally, and not via underlying Calendar instance like base class does.
      void setTimeZone​(java.util.TimeZone tz)  
      java.lang.String toPattern()  
      java.lang.String toString()  
      StdDateFormat withColonInTimeZone​(boolean b)
      "Mutant factory" method that will return an instance that has specified handling of colon when serializing timezone (timezone either written like +0500 or +05:00): either this instance (if setting would not change), or newly constructed instance with desired setting for colon inclusion.
      StdDateFormat withLenient​(java.lang.Boolean b)
      "Mutant factory" method that will return an instance that has specified leniency setting: either this instance (if setting would not change), or newly constructed instance.
      StdDateFormat withLocale​(java.util.Locale loc)
      "Mutant factory" method that will return an instance that uses specified Locale: either this instance (if setting would not change), or newly constructed instance with different Locale to use.
      StdDateFormat withTimeZone​(java.util.TimeZone tz)
      Method used for creating a new instance with specified timezone; if no timezone specified, defaults to the default timezone (UTC).
      • Methods inherited from class java.text.DateFormat

        format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, parseObject, setCalendar, setNumberFormat
      • Methods inherited from class java.text.Format

        format, formatToCharacterIterator, parseObject
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • DATE_FORMAT_STR_ISO8601

        public static final java.lang.String DATE_FORMAT_STR_ISO8601
        Defines a commonly used date format that conforms to ISO-8601 date formatting standard, when it includes basic undecorated timezone definition.
        See Also:
        Constant Field Values
      • instance

        public static final StdDateFormat instance
        A singleton instance can be used for cloning purposes, as a blueprint of sorts.
    • Constructor Detail

      • StdDateFormat

        public StdDateFormat()
      • StdDateFormat

        @Deprecated
        public StdDateFormat​(java.util.TimeZone tz,
                             java.util.Locale loc)
        Deprecated.
    • Method Detail

      • getDefaultTimeZone

        public static java.util.TimeZone getDefaultTimeZone()
      • withTimeZone

        public StdDateFormat withTimeZone​(java.util.TimeZone tz)
        Method used for creating a new instance with specified timezone; if no timezone specified, defaults to the default timezone (UTC).
      • withLocale

        public StdDateFormat withLocale​(java.util.Locale loc)
        "Mutant factory" method that will return an instance that uses specified Locale: either this instance (if setting would not change), or newly constructed instance with different Locale to use.
      • withLenient

        public StdDateFormat withLenient​(java.lang.Boolean b)
        "Mutant factory" method that will return an instance that has specified leniency setting: either this instance (if setting would not change), or newly constructed instance.
        Since:
        2.9
      • withColonInTimeZone

        public StdDateFormat withColonInTimeZone​(boolean b)
        "Mutant factory" method that will return an instance that has specified handling of colon when serializing timezone (timezone either written like +0500 or +05:00): either this instance (if setting would not change), or newly constructed instance with desired setting for colon inclusion.

        NOTE: does NOT affect deserialization as colon is optional accepted but not required -- put another way, either serialization is accepted by this class.

        Since:
        2.9.1
      • clone

        public StdDateFormat clone()
        Overrides:
        clone in class java.text.DateFormat
      • getISO8601Format

        @Deprecated
        public static java.text.DateFormat getISO8601Format​(java.util.TimeZone tz,
                                                            java.util.Locale loc)
        Deprecated.
        Since 2.9
        Method for getting a non-shared DateFormat instance that uses specified timezone and can handle simple ISO-8601 compliant date format.
        Since:
        2.4
      • getRFC1123Format

        @Deprecated
        public static java.text.DateFormat getRFC1123Format​(java.util.TimeZone tz,
                                                            java.util.Locale loc)
        Deprecated.
        Since 2.9
        Method for getting a non-shared DateFormat instance that uses specific timezone and can handle RFC-1123 compliant date format.
        Since:
        2.4
      • getTimeZone

        public java.util.TimeZone getTimeZone()
        Overrides:
        getTimeZone in class java.text.DateFormat
      • setTimeZone

        public void setTimeZone​(java.util.TimeZone tz)
        Overrides:
        setTimeZone in class java.text.DateFormat
      • setLenient

        public void setLenient​(boolean enabled)
        Need to override since we need to keep track of leniency locally, and not via underlying Calendar instance like base class does.
        Overrides:
        setLenient in class java.text.DateFormat
      • isLenient

        public boolean isLenient()
        Overrides:
        isLenient in class java.text.DateFormat
      • isColonIncludedInTimeZone

        public boolean isColonIncludedInTimeZone()
        Accessor for checking whether this instance would include colon within timezone serialization or not: if {code true}, timezone offset is serialized like -06:00; if {code false} as -0600.

        NOTE: only relevant for serialization (formatting), as deserialization (parsing) always accepts optional colon but does not require it, regardless of this setting.

        Returns:
        true if a colon is to be inserted between the hours and minutes of the TZ offset when serializing as String; otherwise false
        Since:
        2.9.1
      • parse

        public java.util.Date parse​(java.lang.String dateStr)
                             throws java.text.ParseException
        Overrides:
        parse in class java.text.DateFormat
        Throws:
        java.text.ParseException
      • parse

        public java.util.Date parse​(java.lang.String dateStr,
                                    java.text.ParsePosition pos)
        Specified by:
        parse in class java.text.DateFormat
      • 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
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • toPattern

        public java.lang.String toPattern()
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.text.DateFormat
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.text.DateFormat