Formatting dates in Java using DateTimeFormatter

Introduction

Formatting dates – and numbers for that matter – can be a complex matter. The DateTimeFormatter class provides pre-defined formats that adhere to ISO and RCF specifications.

DateTimeFormatter

The following date related classes we’ve seen on this blog, i.e.

• LocalDate
• LocalTime
• LocalDateTime
• ZonedDateTime

…have a method called “format” which accepts a DateTimeFormatter class. This class has a number of pre-defined formats that you can readily use in your application. Note that not all such formats will be available. The availability depends on the exact object type of the date class. E.g. ISO_ZONED_DATE_TIME won’t work with LocalDateTime as it is meant to format zoned dates. Also, ISO_DATE_TIME won’t be available for the LocalDate class as it has no concept of time units below the level of days.

Let’s test all the predefined values with the above date types.

LocalDate

We run the following code and check the output:

System.out.println("Running example with LocalDate class.");
LocalDate now = LocalDate.now();
        try
        {
            System.out.println("ISO_DATE: " + now.format(DateTimeFormatter.ISO_DATE));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_DATE is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("BASIC_ISO_DATE: " + now.format(DateTimeFormatter.BASIC_ISO_DATE));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("BASIC_ISO_DATE is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_DATE_TIME: " + now.format(DateTimeFormatter.ISO_DATE_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_DATE_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_INSTANT: " + now.format(DateTimeFormatter.ISO_INSTANT));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_INSTANT is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_LOCAL_DATE: " + now.format(DateTimeFormatter.ISO_LOCAL_DATE));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_LOCAL_DATE is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_LOCAL_DATE_TIME: " + now.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_LOCAL_DATE_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_LOCAL_TIME: " + now.format(DateTimeFormatter.ISO_LOCAL_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_LOCAL_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_OFFSET_DATE: " + now.format(DateTimeFormatter.ISO_OFFSET_DATE));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_OFFSET_DATE is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_OFFSET_DATE_TIME: " + now.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_OFFSET_DATE_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_OFFSET_TIME: " + now.format(DateTimeFormatter.ISO_OFFSET_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_OFFSET_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_ORDINAL_DATE: " + now.format(DateTimeFormatter.ISO_ORDINAL_DATE));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_ORDINAL_DATE is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_TIME: " + now.format(DateTimeFormatter.ISO_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_WEEK_DATE: " + now.format(DateTimeFormatter.ISO_WEEK_DATE));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_WEEK_DATE is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("ISO_ZONED_DATE_TIME: " + now.format(DateTimeFormatter.ISO_ZONED_DATE_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("ISO_ZONED_DATE_TIME is not supported: " + e.getMessage());
        }
        try
        {
            System.out.println("RFC_1123_DATE_TIME: " + now.format(DateTimeFormatter.RFC_1123_DATE_TIME));
        } catch (UnsupportedTemporalTypeException e)
        {
            System.out.println("RFC_1123_DATE_TIME is not supported: " + e.getMessage());
        }

We get the following output:

Running example with LocalDate class.
ISO_DATE: 2014-11-01
BASIC_ISO_DATE: 20141101
ISO_DATE_TIME is not supported: Unsupported field: HourOfDay
ISO_INSTANT is not supported: Unsupported field: InstantSeconds
ISO_LOCAL_DATE: 2014-11-01
ISO_LOCAL_DATE_TIME is not supported: Unsupported field: HourOfDay
ISO_LOCAL_TIME is not supported: Unsupported field: HourOfDay
ISO_OFFSET_DATE is not supported: Unsupported field: OffsetSeconds
ISO_OFFSET_DATE_TIME is not supported: Unsupported field: HourOfDay
ISO_OFFSET_TIME is not supported: Unsupported field: HourOfDay
ISO_ORDINAL_DATE: 2014-305
ISO_TIME is not supported: Unsupported field: HourOfDay
ISO_WEEK_DATE: 2014-W44-6
ISO_ZONED_DATE_TIME is not supported: Unsupported field: HourOfDay
RFC_1123_DATE_TIME is not supported: Unsupported field: HourOfDay

LocalTime

We run the same code as above but change the class type:

System.out.println("Running example with LocalTime class.");
LocalTime now = LocalTime.now();

…and here’s the output, again with Locale set to Sweden:

Running example with LocalTime class.
ISO_DATE is not supported: Unsupported field: Year
BASIC_ISO_DATE is not supported: Unsupported field: Year
ISO_DATE_TIME is not supported: Unsupported field: Year
ISO_INSTANT is not supported: Unsupported field: InstantSeconds
ISO_LOCAL_DATE is not supported: Unsupported field: Year
ISO_LOCAL_DATE_TIME is not supported: Unsupported field: Year
ISO_LOCAL_TIME: 22:02:52.932
ISO_OFFSET_DATE is not supported: Unsupported field: Year
ISO_OFFSET_DATE_TIME is not supported: Unsupported field: Year
ISO_OFFSET_TIME is not supported: Unsupported field: OffsetSeconds
ISO_ORDINAL_DATE is not supported: Unsupported field: Year
ISO_TIME: 22:02:52.932
ISO_WEEK_DATE is not supported: Unsupported field: WeekBasedYear
ISO_ZONED_DATE_TIME is not supported: Unsupported field: Year
RFC_1123_DATE_TIME is not supported: Unsupported field: DayOfMonth

Most formats are not supported by LocalTime as there’s no notion of days, months etc. in that object.

LocalDateTime

Run the same code with “now” set as follows:

System.out.println("Running example with LocalDateTime class.");
LocalDateTime now = LocalDateTime.now();

…and I got the following output:

Running example with LocalTime class.
ISO_DATE: 2014-11-01
BASIC_ISO_DATE: 20141101
ISO_DATE_TIME: 2014-11-01T22:07:24.329
ISO_INSTANT is not supported: Unsupported field: InstantSeconds
ISO_LOCAL_DATE: 2014-11-01
ISO_LOCAL_DATE_TIME: 2014-11-01T22:07:24.329
ISO_LOCAL_TIME: 22:07:24.329
ISO_OFFSET_DATE is not supported: Unsupported field: OffsetSeconds
ISO_OFFSET_DATE_TIME is not supported: Unsupported field: OffsetSeconds
ISO_OFFSET_TIME is not supported: Unsupported field: OffsetSeconds
ISO_ORDINAL_DATE: 2014-305
ISO_TIME: 22:07:24.329
ISO_WEEK_DATE: 2014-W44-6
ISO_ZONED_DATE_TIME is not supported: Unsupported field: OffsetSeconds
RFC_1123_DATE_TIME is not supported: Unsupported field: OffsetSeconds

ZonedDateTime

This is probably the most interesting case as it supports all the predefined formats in DateTimeFormatter. Let’s look at an example with Australia/Adelaide:

System.out.println("Running example with ZonedDateTime class.");
ZoneId brisbane = ZoneId.of("Australia/Adelaide");
ZonedDateTime now = ZonedDateTime.of(LocalDateTime.now(), brisbane);

Running example with ZonedDateTime class.
ISO_DATE: 2014-11-01+10:30
BASIC_ISO_DATE: 20141101+1030
ISO_DATE_TIME: 2014-11-01T22:13:48.87+10:30[Australia/Adelaide]
ISO_INSTANT: 2014-11-01T11:43:48.870Z
ISO_LOCAL_DATE: 2014-11-01
ISO_LOCAL_DATE_TIME: 2014-11-01T22:13:48.87
ISO_LOCAL_TIME: 22:13:48.87
ISO_OFFSET_DATE: 2014-11-01+10:30
ISO_OFFSET_DATE_TIME: 2014-11-01T22:13:48.87+10:30
ISO_OFFSET_TIME: 22:13:48.87+10:30
ISO_ORDINAL_DATE: 2014-305+10:30
ISO_TIME: 22:13:48.87+10:30
ISO_WEEK_DATE: 2014-W44-6+10:30
ISO_ZONED_DATE_TIME: 2014-11-01T22:13:48.87+10:30[Australia/Adelaide]
RFC_1123_DATE_TIME: Sat, 1 Nov 2014 22:13:48 +1030

So you see that these predefined formatters follow the accepted ISO and RFC specifications and won’t actually show the localised date format the way dates are formatted in e.g. Japan or the US.

We’ll take a look at date localisation using the DateTimeFormatter in the next post in this series.

View all posts related to Java here.