A Guide to SimpleDateFormat

1. Introduction

In this tutorial, we’ll be taking an in-depth tour of the SimpleDateFormat class.

We’ll take a look at simple instantiation and formatting styles as well as useful methods the class exposes for handling locales and time zones.

Now, before getting started, let’s keep in mind SimpleDateFormat is not thread-safe. So taking appropriate precautions in concurrent environments is left to developers.

2. Simple Instantiation

First, let’s look at how to instantiate a new SimpleDateFormat object.

There are 4 possible constructors – but in keeping with the name, let’s keep things simple. All we need to get started is a String representation of a date pattern we want.

Let’s start with a dash-separated date pattern like so:

"dd-MM-yyyy"

This will correctly format a date starting with the current day of the month, current month of the year, and finally the current year. We can test our new formatter with a simple unit test. We’ll instantiate a new SimpleDateFormat object, and pass in a known date:

SimpleDateFormat formatter = new SimpleDateFormat("dd-MM-yyyy");
assertEquals("24-05-1977", formatter.format(new Date(233345223232L)));

In the above code, the formatter converts milliseconds as long into a human readable date – the 24th of May, 1977.

2.1. Factory Methods

Although SimpleDateFormat is a handy class to quickly build a date formatter, we’re encouraged to use the factory methods on the DateFormat class getDateFormat(), getDateTimeFormat(), getTimeFormat().

The above example looks a little different when using these factory methods:

DateFormat formatter = DateFormat.getDateInstance(DateFormat.SHORT);
assertEquals("5/24/77", formatter.format(new Date(233345223232L)));

As we can tell from above, the number of formatting options is pre-determined by the fields on the DateFormat class. This largely restricts our available options for formatting which is why we’ll be sticking to SimpleDateFormat in this article.

3. Parsing Dates

SimpleDateFormat and DateFormat not only allow us to format dates – but we can also reverse the operation. Using the parse method, we can input the String representation of a date and return the Date object equivalent:

SimpleDateFormat formatter = new SimpleDateFormat("dd-MM-yyyy");
Date myDate = new Date(233276400000L);
Date parsedDate = formatter.parse("24-05-1977");
assertEquals(myDate.getTime(), parsedDate.getTime());

It’s important to note here that the pattern supplied in the constructor should be in the same format as the date parsed using the parse method.

4. Date-Time Patterns

SimpleDateFormat supplies a vast array of different options when formatting dates. While the full list is available in the JavaDocs, let’s explore some of the more commonly used options:

The output returned by the date component also depends heavily on the number of characters used within the String. For example, let’s take the month of June. If we define the date string as:

"MM"

Then our result will appear as the number code – 06. However, if we add another M to our date string:

"MMM"

Then our resulting formatted date appears as the word Jun.

5. Applying Locales

The SimpleDateFormat class also supports a wide range of locales which is set when the constructor is called.

Let’s put this into practice by formatting a date in French. We’ll instantiate a SimpleDateFormat object whilst supplying Locale.FRANCE to the constructor.

SimpleDateFormat franceDateFormatter = new SimpleDateFormat("EEEEE dd-MMMMMMM-yyyy", Locale.FRANCE);
Date myWednesday = new Date(1539341312904L);
assertTrue(franceDateFormatter.format(myWednesday).startsWith("vendredi"));

By supplying a given date, a Wednesday afternoon, we can assert that our franceDateFormatter has correctly formatted the date. The new date correctly starts with Vendredi -French for Wednesday!

It’s worth noting a little gotcha in the Locale version of the constructor – whilst many locales are supported, full coverage is not guaranteed. Oracle recommends using the factory methods on DateFormat class to ensure locale coverage.

6. Changing Time Zones

Since SimpleDateFormat extends the DateFormat class, we can also manipulate the time zone using the setTimeZone method. Let’s take a look at this in action:

Date now = new Date();

SimpleDateFormat simpleDateFormat = new SimpleDateFormat("EEEE dd-MMM-yy HH:mm:ssZ");

simpleDateFormat.setTimeZone(TimeZone.getTimeZone("Europe/London"));
logger.info(simpleDateFormat.format(now));

simpleDateFormat.setTimeZone(TimeZone.getTimeZone("America/New_York"));
logger.info(simpleDateFormat.format(now));

In the above example, we supply the same Date to two different time zones on the same SimpleDateFormat object. We’ve also added the ‘Z’ character to the end of the pattern String to indicate the time zone differences. The output from the format method is then logged for the user.

Hitting run, we can see the current times relative to the two time zones:

INFO: Friday 12-Oct-18 12:46:14+0100
INFO: Friday 12-Oct-18 07:46:14-0400

7. Summary

In this tutorial, we’ve taken a deep dive into the intricacies of SimpleDateFormat.

We’ve looked at how to instantiate SimpleDateFormat as well as how the pattern String impacts how the date is formatted.

We played around with changing the locales of the output String before finally experimenting with using time zones.

As always the complete source code can be found over on Github.