Class StdDateFormat

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

    public class StdDateFormat
    extends java.text.DateFormat
    Default DateFormat implementation used by standard Date serializers and deserializers. 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.
    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
      protected java.lang.Boolean _lenient
      Explicit override for leniency, if specified.
      protected java.util.Locale _locale  
      protected java.util.TimeZone _timezone
      Caller may want to explicitly override timezone to use; if so, we will have non-null value here.
      protected static java.lang.String[] ALL_FORMATS
      For error messages we'll also need a list of all formats.
      protected static java.util.Calendar CALENDAR
      Blueprint "Calendar" instance for use during formatting.
      protected static java.text.DateFormat DATE_FORMAT_RFC1123  
      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.
      protected static java.lang.String DATE_FORMAT_STR_PLAIN
      ISO-8601 with just the Date part, no time: needed for error messages
      protected static java.lang.String DATE_FORMAT_STR_RFC1123
      This constant defines the date format specified by RFC 1123 / RFC 822.
      protected static java.util.Locale DEFAULT_LOCALE  
      protected static java.util.TimeZone DEFAULT_TIMEZONE
      By default we use UTC for everything, with Jackson 2.7 and later (2.6 and earlier relied on GMT)
      static StdDateFormat instance
      A singleton instance can be used for cloning purposes, as a blueprint of sorts.
      protected static java.util.regex.Pattern PATTERN_ISO8601  
      protected static java.util.regex.Pattern PATTERN_PLAIN  
      protected static java.lang.String PATTERN_PLAIN_STR  
      • 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 
      Modifier Constructor Description
        StdDateFormat()  
        StdDateFormat​(java.util.TimeZone tz, java.util.Locale loc)
      Deprecated.
      protected StdDateFormat​(java.util.TimeZone tz, java.util.Locale loc, java.lang.Boolean lenient)  
      protected StdDateFormat​(java.util.TimeZone tz, java.util.Locale loc, java.lang.Boolean lenient, boolean formatTzOffsetWithColon)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected void _clearFormats()  
      protected static <T> boolean _equals​(T value1, T value2)  
      protected void _format​(java.util.TimeZone tz, java.util.Locale loc, java.util.Date date, java.lang.StringBuffer buffer)  
      protected void _formatBCEYear​(java.lang.StringBuffer buffer, int bceYearNoSign)  
      protected java.util.Calendar _getCalendar​(java.util.TimeZone tz)  
      protected java.util.Date _parseAsISO8601​(java.lang.String dateStr, java.text.ParsePosition bogus)  
      protected java.util.Date _parseDate​(java.lang.String dateStr, java.text.ParsePosition pos)  
      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()  
      protected boolean looksLikeISO8601​(java.lang.String dateStr)
      Helper method used to figure out if input looks like valid ISO-8601 string.
      java.util.Date parse​(java.lang.String dateStr)  
      java.util.Date parse​(java.lang.String dateStr, java.text.ParsePosition pos)  
      protected java.util.Date parseAsISO8601​(java.lang.String dateStr, java.text.ParsePosition pos)  
      protected java.util.Date parseAsRFC1123​(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

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

      • PATTERN_PLAIN_STR

        protected static final java.lang.String PATTERN_PLAIN_STR
        See Also:
        Constant Field Values
      • PATTERN_PLAIN

        protected static final java.util.regex.Pattern PATTERN_PLAIN
      • PATTERN_ISO8601

        protected static final java.util.regex.Pattern PATTERN_ISO8601
      • 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
      • DATE_FORMAT_STR_PLAIN

        protected static final java.lang.String DATE_FORMAT_STR_PLAIN
        ISO-8601 with just the Date part, no time: needed for error messages
        See Also:
        Constant Field Values
      • DATE_FORMAT_STR_RFC1123

        protected static final java.lang.String DATE_FORMAT_STR_RFC1123
        This constant defines the date format specified by RFC 1123 / RFC 822. Used for parsing via `SimpleDateFormat` as well as error messages.
        See Also:
        Constant Field Values
      • ALL_FORMATS

        protected static final java.lang.String[] ALL_FORMATS
        For error messages we'll also need a list of all formats.
      • DEFAULT_TIMEZONE

        protected static final java.util.TimeZone DEFAULT_TIMEZONE
        By default we use UTC for everything, with Jackson 2.7 and later (2.6 and earlier relied on GMT)
      • DEFAULT_LOCALE

        protected static final java.util.Locale DEFAULT_LOCALE
      • DATE_FORMAT_RFC1123

        protected static final java.text.DateFormat DATE_FORMAT_RFC1123
      • instance

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

        protected static final java.util.Calendar CALENDAR
        Blueprint "Calendar" instance for use during formatting. Cannot be used as is, due to thread-safety issues, but can be used for constructing actual instances more cheaply by cloning.
        Since:
        2.9.1
      • _timezone

        protected transient java.util.TimeZone _timezone
        Caller may want to explicitly override timezone to use; if so, we will have non-null value here.
      • _locale

        protected final java.util.Locale _locale
      • _lenient

        protected java.lang.Boolean _lenient
        Explicit override for leniency, if specified.

        Cannot be `final` because setLenient(boolean) returns `void`.

        Since:
        2.7
    • Constructor Detail

      • StdDateFormat

        public StdDateFormat()
      • StdDateFormat

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

        protected StdDateFormat​(java.util.TimeZone tz,
                                java.util.Locale loc,
                                java.lang.Boolean lenient)
      • StdDateFormat

        protected StdDateFormat​(java.util.TimeZone tz,
                                java.util.Locale loc,
                                java.lang.Boolean lenient,
                                boolean formatTzOffsetWithColon)
        Since:
        2.9.1
    • 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
      • _parseDate

        protected java.util.Date _parseDate​(java.lang.String dateStr,
                                            java.text.ParsePosition pos)
                                     throws java.text.ParseException
        Throws:
        java.text.ParseException
      • 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
      • _format

        protected void _format​(java.util.TimeZone tz,
                               java.util.Locale loc,
                               java.util.Date date,
                               java.lang.StringBuffer buffer)
      • _formatBCEYear

        protected void _formatBCEYear​(java.lang.StringBuffer buffer,
                                      int bceYearNoSign)
      • 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
      • looksLikeISO8601

        protected boolean looksLikeISO8601​(java.lang.String dateStr)
        Helper method used to figure out if input looks like valid ISO-8601 string.
      • parseAsISO8601

        protected java.util.Date parseAsISO8601​(java.lang.String dateStr,
                                                java.text.ParsePosition pos)
                                         throws java.text.ParseException
        Throws:
        java.text.ParseException
      • _parseAsISO8601

        protected java.util.Date _parseAsISO8601​(java.lang.String dateStr,
                                                 java.text.ParsePosition bogus)
                                          throws java.lang.IllegalArgumentException,
                                                 java.text.ParseException
        Throws:
        java.lang.IllegalArgumentException
        java.text.ParseException
      • parseAsRFC1123

        protected java.util.Date parseAsRFC1123​(java.lang.String dateStr,
                                                java.text.ParsePosition pos)
      • _clearFormats

        protected void _clearFormats()
      • _getCalendar

        protected java.util.Calendar _getCalendar​(java.util.TimeZone tz)
      • _equals

        protected static <T> boolean _equals​(T value1,
                                             T value2)