In REST services, the standard format for dates is the ISO 8601 format, which formats the time offset against UTC. So 24th September 2016 12:00:00 British Summer Time would be a string in the format “2016-09-24T12:00:00+01:00”. However, when you want to use that in your application, you need to convert the text string to something your application can use, which when doing a JAX-RS REST service means some flavour of Java date. java.util.Date doesn’t actually include any timezone information, so in a pre-Java 8 world that means java.util.Calendar. Once we get Java 8 in Domino (there is no further information at this time of when that is likely to occur), we can use java.util.LocalDateTime.
Those who have used JAX-RS in Domino will have utilised some of the built-in packages IBM offers. The main one of those is JsonJavaObject. The uninitiated might be tempted to use JsonJavaObject.getJavaDate(). That uses JsonGenerator.stringToDate(). That uses the parse() method of a SimpleDateFormat variable called ISO8601.
Fortunately before finding that method, I had already searched for how to convert a ISO 8601 date format to Java and had come across a question on StackOverflow that confirmed the issues with using SimpleDateFormat. Unfortunately Joda-Time doesn’t come packaged with Domino, so that’s not an easy option to use. Instead I came across this useful snippet in particular the parse() method. This correctly handles the timezone from the JSON ISO 8601 string, whether it’s an offset to UTC or a timezone, so it’s eminently more preferable to the JsonJavaObject.getJavaDate() method.
