Package com.fasterxml.jackson.databind.util

Class StdDateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
com.fasterxml.jackson.databind.util.StdDateFormat
All Implemented Interfaces:
Serializable, Cloneable
public class StdDateFormat extends 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:

  • Field Details

    • PATTERN_PLAIN_STR

      protected static final String PATTERN_PLAIN_STR
      See Also:

    • PATTERN_PLAIN

      protected static final Pattern PATTERN_PLAIN

    • PATTERN_ISO8601

      protected static final Pattern PATTERN_ISO8601

    • DATE_FORMAT_STR_ISO8601

      public static final 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:

    • DATE_FORMAT_STR_PLAIN

      protected static final String DATE_FORMAT_STR_PLAIN
      ISO-8601 with just the Date part, no time: needed for error messages
      See Also:

    • DATE_FORMAT_STR_RFC1123

      protected static final 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:

    • ALL_FORMATS

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

    • DEFAULT_TIMEZONE

      protected static final 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 Locale DEFAULT_LOCALE

    • DATE_FORMAT_RFC1123

      protected static final 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 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 TimeZone _timezone
      Caller may want to explicitly override timezone to use; if so, we will have non-null value here.

    • _locale

      protected final Locale _locale

    • _lenient

      protected Boolean _lenient
      Explicit override for leniency, if specified.

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

      Since:
      2.7

  • Constructor Details

    • StdDateFormat

      public StdDateFormat()

    • StdDateFormat

      @Deprecated public StdDateFormat(TimeZone tz, Locale loc)
      Deprecated.

    • StdDateFormat

      protected StdDateFormat(TimeZone tz, Locale loc, Boolean lenient)

    • StdDateFormat

      protected StdDateFormat(TimeZone tz, Locale loc, Boolean lenient, boolean formatTzOffsetWithColon)
      Since:
      2.9.1

  • Method Details

    • getDefaultTimeZone

      public static TimeZone getDefaultTimeZone()

    • withTimeZone

      public StdDateFormat withTimeZone(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(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(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 DateFormat

    • getISO8601Format

      @Deprecated public static DateFormat getISO8601Format(TimeZone tz, 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 DateFormat getRFC1123Format(TimeZone tz, 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 TimeZone getTimeZone()
      Overrides:
      getTimeZone in class DateFormat

    • setTimeZone

      public void setTimeZone(TimeZone tz)
      Overrides:
      setTimeZone in class 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 DateFormat

    • isLenient

      public boolean isLenient()
      Overrides:
      isLenient in class 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 Date parse(String dateStr) throws ParseException
      Overrides:
      parse in class DateFormat
      Throws:
      ParseException

    • parse

      public Date parse(String dateStr, ParsePosition pos)
      Specified by:
      parse in class DateFormat

    • _parseDate

      protected Date _parseDate(String dateStr, ParsePosition pos) throws ParseException
      Throws:
      ParseException

    • format

      public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition)
      Specified by:
      format in class DateFormat

    • _format

      protected void _format(TimeZone tz, Locale loc, Date date, StringBuffer buffer)

    • _formatBCEYear

      protected void _formatBCEYear(StringBuffer buffer, int bceYearNoSign)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toPattern

      public String toPattern()

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class DateFormat

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class DateFormat

    • looksLikeISO8601

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

    • parseAsISO8601

      protected Date parseAsISO8601(String dateStr, ParsePosition pos) throws ParseException
      Throws:
      ParseException

    • _parseAsISO8601

      protected Date _parseAsISO8601(String dateStr, ParsePosition bogus) throws IllegalArgumentException, ParseException
      Throws:
      IllegalArgumentException
      ParseException

    • parseAsRFC1123

      protected Date parseAsRFC1123(String dateStr, ParsePosition pos)

    • _clearFormats

      protected void _clearFormats()

    • _getCalendar

      protected Calendar _getCalendar(TimeZone tz)

    • _equals

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