Introduction :

DateTimeFormatter class belongs to java.time.format package. You can use it to format or parse the date or time or a datetime object. Remember for the sake of exam, it defines rules for both parsing and formatting.

To instantiate a DateTimeFormatter, use any of the below ways :

1. Calling the static ofLocalizedXXX() method, passing it the FormatStyle value.
2. By using the public static fields defined in DateTimeFormatter.
3. By invoking static method ofPattern(), passing it a string value describing the object pattern.

ofLocalizedXXX() Methods :

When using ofLocalizedXXX() methods, use below tables for identifying valid FormatStyle values and their output. For any invalid FormatStyle, for instance passing a FormatStyle.LONG for a time based value will throw a DateTimeException.

FormatStyle	Example
FormatStyle.FULL	Sunday, February 4, 2018
FormatStyle.LONG	February 4, 2018
FormatStyle.MEDIUM	Feb 4, 2018
FormatStyle.SHORT	4/2/18

Table 1 : Valid FormatStyle for date-based values

 

FormatStyle	Example
FormatStyle.MEDIUM	3:45:45 PM
FormatStyle.SHORT	3:45 PM

Table 2 : Valid FormatStyle for time-based values

 

Below are few examples of instantiating the formatter using ofLocalizedXXX() method.It is important to note that it formats the date and time objects according to the default locale of the system on which the code executes. So the output might vary slightly across systems.

DateTimeFormatter formatter1 = DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM);
DateTimeFormatter formatter2 = DateTimeFormatter.ofLocalizedTime(FormatStyle.FULL);
DateTimeFormatter formatter3 = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.LONG);
DateTimeFormatter formatter4 = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT,FormatStyle.MEDIUM);

Using class-level fields :

The other way to instantiate a DateTimeFormatter is to use the available class level fields(public and static) . Below are the available formatters, you need to know.

Sample usage :

DateTimeFormatter formatter1 = DateTimeFormatter.ISO_LOCAL_DATE;

Using ofPattern() method :

You can chose to pass in the expected pattern as a string argument to this method to instantiate the DateTimeFormatter.

DateTimeFormatter formatter1 = DateTimeFormatter.ofPattern("yyyy MM dd");

You can use letters from the below table to define a pattern.

Component Description	Pattern Symbol	Examples
Year Proleptic year: 'u' symbol is used. Year of Era(AD/BC) : use 'y'	u uu uuu uuuu uuuuu	2018 18(2 right-most digits) 2018 2018 02018(left-padding)
Era(AD or BC)indicator Use it when using 'Year of Era'(y) Symbol for representing the year	G	AD
Month in year	M MM MMM MMMM	9 09 Sep September
Day in month	d dd	5 05
Day name in a week	E EE EEE EEEE	Wed Wed Wed Wednesday
Hour in a day(Range is 0-23) Hour in a day(in range -0-12) Note: Must use AM/PM marker in this case, needed for parsing	H HH h hh	3 03 3 03
Minute in an hour(Range : 0-59)	m mm	8 08
Second in a minute(Range : 0-59)	s ss	9 09
Fraction of a second(Milliseconds)	SSS SSSSSS SSSSSSSSS	234 142431 152453222
AM/PM	a	PM

Table : DateTimeFormatter Pattern Symbols

Using DateTimeFormatter for Formatting :

Once we have learnt how to instantiate a DateTimeFormatter, let’s see how can we use it to format the temporal objects. To do so, you can either use the format() method from that temporal class(say LocalDate, LocalTime, LocalDateTime) or use the format() method from DateTimeFormatter class.

// available in class - LocalDate, LocalTime, LocalDateTime
String format(DateTimeFormatter formatter)


//available in DateTimeFormatter class
String format(TemporalAccessor temporalObject)

TemporalAccessor, referred above, is an interface, implemented by the temporal classes – LocalDate, LocalTime and LocalDateTime.Refer some example usages.

DateTimeFormatter formatter1 = DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM);
LocalDate date1 = LocalDate.of(2012,3,5);
System.out.println(date1.format(formatter1));//Mar 5, 2012
System.out.println(formatter1.format(date1));//Mar 5, 2012

LocalTime time1 = LocalTime.of(11,23);
String val = formatter1.format(time1);//throws UnSupportedTemporalTypeException

Make sure that you are using a valid formatter over a temporal object, an attempt to violate this law will produce a UnSupportedTemporalTypeException. For instance, if I am trying to use a DateTimeFormatter designed to handle date objects over the LocalTime instance, my code will throw a runtime exception.

Parsing Using DateTimeFormatter :

The below available methods can be used for parsing a temporal object.

/*methods available in temporal classes - LocalDate, LocalTime, LocalDateTime
*TemporalType is either LocalDate/LocalTime/LocalDateTime based on
*which class the methods belongs to
*/
I. static TemporalType parse(CharSequence charSeq)
//formatting using given DateTimeFormatter
II. static TemporalType parse(CharSequence charSeq, DateTimeFormatter formatter)

//method available in DateTimeFormatter class
III. TemporalAccessor parse(CharSequence charSeq)

When using the parse(charSeq) method from temporal classes(denoted by I. in the above snippet) , the parsing is achieved using the default DateTimeFormatter instance i.e. DateTimeFormatter.ISO_LOCAL_DATE for LocalDate, DateTimeFormatter.ISO_LOCAL_TIME for LocalTime, and DateTimeFormatter.ISO_LOCAL_DATE_TIME for LocalDateTime.

Below are some example usages of these methods :

DateTimeFormatter f = DateTimeFormatter.ofPattern("yyyy-MM-dd");
//LocalDate.from() method return LocalDate from a TemporalAccessor instance
LocalDate d1 = LocalDate.from(f.parse("2018-03-01"));
LocalDate d2 = LocalDate.parse("2018-03-01", f);

Conclusion :

In this post, we covered DateTimeFormatter class, the ways of instantiating it and how to parse and format temporal objects using the instance of DateTimeFormatter.

Note : We have already covered LocalDate, LocalTime, LocalDateTime and Period classes of Java Date Time API in our previous posts. Please feel free to check them out.