Sets the format used to convert
java.util.Date-s that are date-time (timestamp) values to string-s,
also the format that
someString?datetime will use to parse strings.
The possible setting values are (the quotation marks aren't part of the value itself):
Patterns accepted by Java's
SimpleDateFormat, for example
"dd.MM.yyyy HH:mm:ss" (where
HH means 24 hours format) or
"MM/dd/yyyy hh:mm:ss a" (where
a prints AM or PM, if
the current language is English).
"xs" for XML Schema format, or
"iso" for ISO 8601:2004 format.
These formats allow various additional options, separated with space, like in
"iso m nz" (or with
_, like in
"iso_m_nz"; this is useful in a case like
lastModified?string.iso_m_nz). The options and their meanings are:
Accuracy options:
ms = Milliseconds, always shown with all 3 digits, even if it's all 0-s.
Example:
13:45:05.800
s = Seconds (fraction seconds are dropped even if non-0), like
13:45:05
m = Minutes, like
13:45. This isn't allowed for "xs".
h = Hours, like
13. This isn't allowed for "xs".
Neither = Up to millisecond accuracy, but trailing millisecond 0-s are removed, also the whole
milliseconds part if it would be 0 otherwise. Example:
13:45:05.8
Time zone offset visibility options:
fz = "Force Zone", always show time zone offset (even for for
java.sql.Date and
java.sql.Time values).
But, because ISO 8601 doesn't allow for dates (means date without time of the day) to
show the zone offset, this option will have no effect in the case of
"iso" with
dates.
nz = "No Zone", never show time zone offset
Neither = always show time zone offset, except for
java.sql.Dateand
java.sql.Time, and for
"iso" date values.
Time zone options:
u = Use UTC instead of what the
time_zone setting suggests. However,
java.sql.Date and
java.sql.Time aren't affected
by this (see
#setSQLDateAndTimeTimeZone(TimeZone) to understand why)
fu = "Force UTC", that is, use UTC instead of what the
time_zone or the
sql_date_and_time_time_zone setting suggests. This also effects
java.sql.Date and
java.sql.Time values
Neither = Use the time zone suggested by the
time_zone or the
sql_date_and_time_time_zone configuration setting (
#setTimeZone(TimeZone) and
#setSQLDateAndTimeTimeZone(TimeZone)).
The options can be specified in any order.
Options from the same category are mutually exclusive, like using
m and
stogether is an error.
The accuracy and time zone offset visibility options don't influence parsing, only formatting.
For example, even if you use "iso m nz", "2012-01-01T15:30:05.125+01" will be parsed successfully and with
milliseconds accuracy.
The time zone options (like "u") influence what time zone is chosen only when parsing a string that doesn't
contain time zone offset.
Parsing with
"iso" understands both extend format and basic format, like
20141225T235018. It doesn't, however, support the parsing of all kind of ISO 8601 strings: if
there's a date part, it must use year, month and day of the month values (not week of the year), and the
day can't be omitted.
The output of
"iso" is deliberately so that it's also a good representation of the value with
XML Schema format, except for 0 and negative years, where it's impossible. Also note that the time zone
offset is omitted for date values in the
"iso" format, while it's preserved for the
"xs"format.
"short",
"medium",
"long", or
"full", which that has locale-dependent
meaning defined by the Java platform (see in the documentation of
java.text.DateFormat).
For date-time values, you can specify the length of the date and time part independently, be separating
them with
_, like
"short_medium". (
"medium" means
"medium_medium" for date-time values.)
Anything that starts with
"@" followed by a letter is interpreted as a custom
date/time/dateTime format, but only if either
Configuration#getIncompatibleImprovements()is at least 2.3.24, or there's any custom formats defined (even if custom number format). The format of
such string is "@name"
or "@name parameters"
, where
name
is the key in the
Map set by
#setCustomDateFormats(Map), and
parameters
is parsed by the custom number format.
Defaults to
"", which is equivalent to
"medium_medium".