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

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

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)