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:
  Serialized Form

### Nested Class Summary

### Nested classes/interfaces inherited from class java.text.DateFormat

`DateFormat.Field`

### Field Summary

Fields
`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
`` `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
`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)