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

  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

      `DateFormat.Field`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Boolean` | `_lenient` Explicit override for leniency, if specified.
    `protected Locale` | `_locale`
    `protected TimeZone` | `_timezone` Caller may want to explicitly override timezone to use; if so, we will have non-null value here.
    `protected static String[]` | `ALL_FORMATS` For error messages we'll also need a list of all formats.
    `protected static Calendar` | `CALENDAR` Blueprint "Calendar" instance for use during formatting.
    `protected static DateFormat` | `DATE_FORMAT_RFC1123`
    `static 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 String` | `DATE_FORMAT_STR_PLAIN` ISO-8601 with just the Date part, no time: needed for error messages
    `protected static String` | `DATE_FORMAT_STR_RFC1123` This constant defines the date format specified by RFC 1123 / RFC 822.
    `protected static Locale` | `DEFAULT_LOCALE`
    `protected static 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 Pattern` | `PATTERN_ISO8601`
    `protected static Pattern` | `PATTERN_PLAIN`
    `protected static 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 and Description
    --- | ---
    `` | `StdDateFormat()`
    `` | `StdDateFormat(TimeZone tz, Locale loc)` Deprecated.
    `protected` | `StdDateFormat(TimeZone tz, Locale loc, Boolean lenient)`
    `protected` | `StdDateFormat(TimeZone tz, Locale loc, Boolean lenient, boolean formatTzOffsetWithColon)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `_clearFormats()`
    `protected static <T> boolean` | `_equals(T value1, T value2)`
    `protected void` | `_format(TimeZone tz, Locale loc, Date date, StringBuffer buffer)`
    `protected void` | `_formatBCEYear(StringBuffer buffer, int bceYearNoSign)`
    `protected Calendar` | `_getCalendar(TimeZone tz)`
    `protected Date` | `_parseAsISO8601(String dateStr, ParsePosition bogus)`
    `protected Date` | `_parseDate(String dateStr, ParsePosition pos)`
    `StdDateFormat` | `clone()`
    `boolean` | `equals(Object o)`
    `StringBuffer` | `format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition)`
    `static TimeZone` | `getDefaultTimeZone()`
    `static DateFormat` | `getISO8601Format(TimeZone tz, Locale loc)` Deprecated. Since 2.9
    `static DateFormat` | `getRFC1123Format(TimeZone tz, Locale loc)` Deprecated. Since 2.9
    `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(String dateStr)` Helper method used to figure out if input looks like valid ISO-8601 string.
    `Date` | `parse(String dateStr)`
    `Date` | `parse(String dateStr, ParsePosition pos)`
    `protected Date` | `parseAsISO8601(String dateStr, ParsePosition pos)`
    `protected Date` | `parseAsRFC1123(String dateStr, 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(TimeZone tz)`
    `String` | `toPattern()`
    `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(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(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(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 String PATTERN_PLAIN_STR

      See Also:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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 Detail

    - #### 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 Detail

    - #### 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)

Copyright © 2008–2020 FasterXML. All rights reserved.