Converting ISO 8601-compliant String to java.util.Date

Unfortunately, the time zone formats available to SimpleDateFormat (Java 6 and earlier) are not ISO 8601 compliant. SimpleDateFormat understands time zone strings like "GMT+01:00" or "+0100", the latter according to RFC # 822.

Even if Java 7 added support for time zone descriptors according to ISO 8601, SimpleDateFormat is still not able to properly parse a complete date string, as it has no support for optional parts.

Reformatting your input string using regexp is certainly one possibility, but the replacement rules are not as simple as in your question:

• Some time zones are not full hours off UTC, so the string does not necessarily end with ":00".
• ISO8601 allows only the number of hours to be included in the time zone, so "+01" is equivalent to "+01:00"
• ISO8601 allows the usage of "Z" to indicate UTC instead of "+00:00".

The easier solution is possibly to use the data type converter in JAXB, since JAXB must be able to parse ISO8601 date string according to the XML Schema specification. javax.xml.bind.DatatypeConverter.parseDateTime("2010-01-01T12:00:00Z") will give you a Calendar object and you can simply use getTime() on it, if you need a Date object.

You could probably use Joda-Time as well, but I don't know why you should bother with that (Update 2022; maybe because the entire javax.xml.bind section is missing from Android's javax.xml package).

Starting from Java 8, there is a completely new officially supported way to do this:

    String s = "2020-02-13T18:51:09.840Z";
    TemporalAccessor ta = DateTimeFormatter.ISO_INSTANT.parse(s);
    Instant i = Instant.from(ta);
    Date d = Date.from(i);

After I searched a lot to convert ISO8601 to date I suddenly found a java class that is ISO8601Util.java and this was part of com.google.gson.internal.bind.util. So you can use it to convert dates.

ISO8601Utils.parse("2010-01-01T12:00:00Z" , ParsePosition(0))

and you can simply use this kotlin extension function

fun String.getDateFromString() : Date? = ISO8601Utils.parse(this , 
ParsePosition(0))

Java 8+

Simple one liner that I didn't found in answers:

Date date = Date.from(ZonedDateTime.parse("2010-01-01T12:00:00+01:00").toInstant());

Date doesn't contain timezone, it will be stored in UTC, but will be properly converted to your JVM timezone even during simple output with System.out.println(date).

I am surprised that not even one java library supports all ISO 8601 date formats as per https://en.wikipedia.org/wiki/ISO_8601. Joda DateTime was supporting most of them, but not all and hence I added custom logic to handle all of them. Here is my implementation.

import java.text.ParseException;
import java.util.Date;

import org.apache.commons.lang3.time.DateUtils;
import org.joda.time.DateTime;

public class ISO8601DateUtils {
 
 /**
  * It parses all the date time formats from https://en.wikipedia.org/wiki/ISO_8601 and returns Joda DateTime.
  * Zoda DateTime does not support dates of format 20190531T160233Z, and hence added custom logic to handle this using SimpleDateFormat.
  * @param dateTimeString ISO 8601 date time string
  * @return
  */
 public static DateTime parse(String dateTimeString) {
  try {
   return new DateTime( dateTimeString );
  } catch(Exception e) {
   try {
    Date dateTime = DateUtils.parseDate(dateTimeString, JODA_NOT_SUPPORTED_ISO_DATES);
    return new DateTime(dateTime.getTime());
   } catch (ParseException e1) {
    throw new RuntimeException(String.format("Date %s could not be parsed to ISO date", dateTimeString));
   }
  }
 }
  
   private static String[] JODA_NOT_SUPPORTED_ISO_DATES = new String[] {
   // upto millis
   "yyyyMMdd'T'HHmmssSSS'Z'",
   "yyyyMMdd'T'HHmmssSSSZ",
   "yyyyMMdd'T'HHmmssSSSXXX",
   
   "yyyy-MM-dd'T'HHmmssSSS'Z'",
   "yyyy-MM-dd'T'HHmmssSSSZ",
   "yyyy-MM-dd'T'HHmmssSSSXXX",
   
   // upto seconds
   "yyyyMMdd'T'HHmmss'Z'",
   "yyyyMMdd'T'HHmmssZ",
   "yyyyMMdd'T'HHmmssXXX",
   
   "yyyy-MM-dd'T'HHmmss'Z'", 
   "yyyy-MM-dd'T'HHmmssZ",
   "yyyy-MM-dd'T'HHmmssXXX",
   
   // upto minutes
   "yyyyMMdd'T'HHmm'Z'",
   "yyyyMMdd'T'HHmmZ",
   "yyyyMMdd'T'HHmmXXX",

   "yyyy-MM-dd'T'HHmm'Z'",
   "yyyy-MM-dd'T'HHmmZ",
   "yyyy-MM-dd'T'HHmmXXX",
   
   //upto hours is already supported by Joda DateTime
 };
}

Do it like this:

public static void main(String[] args) throws ParseException {

    String dateStr = "2016-10-19T14:15:36+08:00";
    Date date = javax.xml.bind.DatatypeConverter.parseDateTime(dateStr).getTime();

    System.out.println(date);

}

Here is the output:

Wed Oct 19 15:15:36 CST 2016

A little test that shows how to parse a date in ISO8601 and that LocalDateTime does not handle DSTs.

 @Test
    public void shouldHandleDaylightSavingTimes() throws ParseException {

        //ISO8601 UTC date format
        SimpleDateFormat utcFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSXXX");

        // 1 hour of difference between 2 dates in UTC happening at the Daylight Saving Time
        Date d1 = utcFormat.parse("2019-10-27T00:30:00.000Z");
        Date d2 = utcFormat.parse("2019-10-27T01:30:00.000Z");

        //Date 2 is before date 2
        Assert.assertTrue(d1.getTime() < d2.getTime());
        // And there is 1 hour difference between the 2 dates
        Assert.assertEquals(1000*60*60, d2.getTime() - d1.getTime());

        //Print the dates in local time
        SimpleDateFormat localFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm z Z", Locale.forLanguageTag("fr_CH"));
        localFormat.setTimeZone(TimeZone.getTimeZone("Europe/Zurich"));

        //Both dates are at 02h30 local time (because of DST), but one is CEST +0200 and the other CET +0100 (clock goes backwards)
        Assert.assertEquals("2019-10-27 02:30 CEST +0200", localFormat.format(d1));
        Assert.assertEquals("2019-10-27 02:30 CET +0100", localFormat.format(d2));

        //Small test that shows that LocalDateTime does not handle DST (and should not be used for storing timeseries data)
        LocalDateTime ld1 = LocalDateTime.ofInstant(d1.toInstant(), ZoneId.of("Europe/Zurich"));
        LocalDateTime ld2 = LocalDateTime.ofInstant(d2.toInstant(), ZoneId.of("Europe/Zurich"));

        //Note that a localdatetime does not handle DST, therefore the 2 dates are the same
        Assert.assertEquals(ld1, ld2);

        //They both have the following local values
        Assert.assertEquals(2019, ld1.getYear());
        Assert.assertEquals(27, ld1.getDayOfMonth());
        Assert.assertEquals(10, ld1.getMonthValue());
        Assert.assertEquals(2, ld1.getHour());
        Assert.assertEquals(30, ld1.getMinute());
        Assert.assertEquals(0, ld1.getSecond());

    }

When want to convert from UTC to format that we want. It will change depend on the zone/location we stay

//utcDate = "2021-06-05T02:46:29Z"
fun converterUtcToReadableDateTime(utcDate: String): String {
    val offsetDateTime = OffsetDateTime.ofInstant(Instant.parse(utcDate), ZoneId.systemDefault())
    val patternDate = "dd MMM yyyy h:mm a"
    return DateTimeFormatter.ofPattern(patternDate).format(offsetDateTime)
}

fun converterUtcToReadableDate(utcDate: String): String {
    val offsetDateTime = OffsetDateTime.ofInstant(Instant.parse(utcDate), ZoneId.systemDefault())
    val patternDate = "d MMM yyyy"
    return DateTimeFormatter.ofPattern(patternDate).format(offsetDateTime)
}

fun converterUtcToReadableTime(utcDate: String): String {
    val offsetDateTime = OffsetDateTime.ofInstant(Instant.parse(utcDate), ZoneId.systemDefault())
    val patternDate = "h:mm a"
    return DateTimeFormatter.ofPattern(patternDate).format(offsetDateTime)
}

To just format a date like this the following worked for me in a Java 6 based application. There is a DateFormat class JacksonThymeleafISO8601DateFormat in the thymeleaf project which inserts the missing colon:

https://github.com/thymeleaf/thymeleaf/blob/40d27f44df7b52eda47d1bc6f1b3012add6098b3/src/main/java/org/thymeleaf/standard/serializer/StandardJavaScriptSerializer.java

I used it for ECMAScript date format compatibilty.

I couldn't use Java 8 features, so only java.util.Date was available. I already had a dependency on gson library but didn't want to use ISO8601Utils directly. ISO8601Utils is an internal API, gson's authors warns not to use it.

I parsed a ISO8601 date using gson's public API:

fun parseISO8601DateToLocalTimeOrNull(date: String): Date? {
    return try {
        GsonBuilder()
            .create()
            .getAdapter(Date::class.java)
            .fromJson("\"$date\"")
     } catch (t: Throwable) {
        null
     }
}

Under the hood, the adapter still uses ISO8601Utils. But if you're using the adapter you can be sure that a different compatible version of gson won't break your project.

I worried that creation of adapter may be slow so I measured execution time on Pixel 3a with debuggable=false.parseISO8601DateToLocalTimeOrNull took ~0.5 milliseconds to parse a date.