Formatting and Parsing Date and Time – Localization
By Gigi Rosen / June 24, 2022 / No Comments / Conditional Formatting, Oracle Certifications
18.6 Formatting and Parsing Date and Time
The class java.time.format.DateTimeFormatter provides the support for locale-sensitive formatting and parsing of date and time values.
In this section we take a closer look at formatting temporal objects and parsing character sequences for temporal objects. In particular, we consider the following formatters, which provide increasing flexibility in customizing formatting and parsing:
- Default formatters are implicitly used by such methods as the toString() method of the temporal classes.
- Predefined formatters are ready-made formatters provided as constants by the java.time.format.DateTimeFormatter class, such as those that adhere to the ISO standard (Table 18.11, p. 1130).
Table 18.11 Selected ISO-Based Predefined Formatters for Date and Time
| DateTimeFormatter | Examples | Formatting | Parsing |
| ISO_LOCAL_TIME | 12:30:15 | LocalTime Time part of: LocalDateTime ZonedDateTime | LocalTime |
| BASIC_ISO_DATE | 20210428 | LocalDate Date part of: LocalDateTime ZonedDateTime | LocalDate |
| ISO_LOCAL_DATE | 2021-04-28 | LocalDate Date part of: LocalDateTime ZonedDateTime | LocalDate |
| ISO_LOCAL_DATE_TIME | 2021-04- 28T12:30:15 | LocalDateTime Date-time part of: ZonedDateTime | LocalTime LocalDate LocalDateTime |
| ISO_ZONED_DATE_TIME | 2021-04- 28T12:30:15+01:00 [Europe/Paris] | ZonedDateTime | LocalTime LocalDate LocalDateTime ZonedDateTime |
| ISO_INSTANT | 2021-04- 28T12:30:15.00000 0500Z | Instant | Instant |
- Style-based formatters are formatters that use the format styles defined by the constants of the java.time.format.FormatStyle enum type (Table 18.12, p. 1132). These formatters are created by the static factory methods ofLocalizedType() of the DateTimeFormatter class, where Type is either Time, Date, or DateTime (Table 18.13, p. 1132).
Table 18.12 Format Styles for Date and Time
| Styles for date/time | Verbosity | Example formatting a date (default locale: United States) |
| FormatStyle.SHORT | Short-style pattern | 1/11/14 |
| FormatStyle.MEDIUM | Medium-style pattern | Jan 11, 2014 |
| FormatStyle.LONG | Long-style pattern | January 11, 2014 |
| FormatStyle.FULL | Full-style pattern | Saturday, January 11, 2014 |
- Pattern-based formatters use customized format styles defined by pattern letters (Table 18.15, p. 1135). These formatters are created by the static factory method ofPattern() of the DateTimeFormatter class.
The DateTimeFormatter class provides static factory methods for obtaining a formatter. The idiom for using a formatter is to obtain a formatter first, localize it if necessary, and then pass it to the methods responsible for formatting and parsing temporal objects. Each of the temporal classes LocalTime, LocalDate, LocalDateTime, and ZonedDateTime provides the following methods: an instance method format() and a static method parse(). These two methods do the formatting and the parsing according to the rules of the formatter that is passed as an argument, respectively.
Analogous methods for formatting and parsing temporal objects passed as an arguments are also provided by the DateTimeFormatter class (see below). For example, the following code lines give the same result string, where date and df refer to a LocalDate object and a DateTimeFormatter object for formatting dates, respectively:
String resultStr1 = date.format(df);
String resultStr2 = df.format(date);
boolean eqStr = resultStr1.equals(resultStr2); // true
From the method headers of the format() and the parse() methods of the temporal classes, we can see that these methods will readily compile with any DateTime-Formatter. The validity of the formatter for a given temporal object is resolved at runtime, resulting in a resounding exception if it is not valid.
// Defined by LocalTime, LocalDate, LocalDateTime, and ZonedDateTime
String format(DateTimeFormatter formatter)
Formats this temporal object using the specified formatter, and returns the resulting string. Each temporal class provides this method. The temporal object is formatted according to the rules of the formatter. The method throws a java.time.DateTimeException if formatting is not successful.
static
TemporalType
parse(CharSequence text)
static
TemporalType
parse(CharSequence text, DateTimeFormatter formatter)
Each temporal class provides these two static methods, where TemporalType can be any of the temporal classes LocalTime, LocalDate, LocalDateTime, or Zoned-DateTime.
The first method returns an instance of the TemporalType from a character sequence, using the default parsing rules for the TemporalType.
The second method obtains an instance of the TemporalType from a character sequence using the specified formatter.
Both methods return an object of a specific temporal class, and both throw a java.time.format.DateTimeParseException if parsing is not successful.
Formatters supplied by the DateTimeFormatter class are immutable and thread-safe. All formatters created using static methods provided by the DateTimeFormatter class can be localized by the localizedBy() method in this class. The DateTimeFormatter class provides methods that can be used to format and parse temporal objects.
// Defined by DateTimeFormatter
DateTimeFormatter localizedBy(Locale locale)
Returns a copy of this formatter that will use the specified locale (§18.1, p. 1096). Although the formatters in the examples presented in this section use the default locale (the US locale in this case), we encourage the reader to experiment with changing the locale of a formatter with this method in the examples.
String format(TemporalAccessor temporal)
Formats a temporal object using this formatter. The main temporal classes implement the TemporalAccessor interface.
This method throws an unchecked java.time.DateTimeException if an error occurs during formatting.
TemporalAccessor parse(CharSequence text)
This method fully parses the text to produce a temporal object. It throws an unchecked java.time.DateTimeException if an error occurs during parsing.
DateTimeFormatter withZone(ZoneId zone)
Returns a copy of this formatter with a new override zone—that is, a formatter with similar state to this formatter but with the override zone set.