Jackson - Date Handling

Handling dates on Java platform is complex business. Jackson tries not to make it any harder than it has to be. Here's how.

All time objects that have associated TimeZone (java.util.Calendar etc) that Jackson constructs use the standard timezone (GMT), not the local time zone (whatever that might be). That is: Jackson defaults to using GMT for all processing unless specifically told otherwise.

Date Serialization

Why do Dates get written as numbers?

Default serializer for java.util.Date (and related, such as java.util.Calendar) serialize them using the most efficient accurate representation, so-called epoch timestamp (number of milliseconds since January 1st, 1970, UTC). Assumption is that if user does not care, we should use efficient and accurate representation to get job bdone.

One exception is java.sql.Date, which will always be represent in textual form (but note: use of java.sql.Date is strongly discouraged due to multiple issues, see below for more details)

But I don't like that, I prefer more readable notation

No problem. The simplest way to produce textual serialization is to use:

objectMapper.configure(SerializationConfig.Feature.WRITE_DATES_AS_TIMESTAMPS, false);

which disable use of timestamps (numbers), and instead use a [ISO-8601]-compliant notation, which gets output as something like: "1970-01-01T00:00:00.000+0000".

That format sucks, can I use my own?

If you must. You can configure formatting by passing a java.text.DateFormat instance like so:

objectMapper.setDateFormat(myDateFormat); // 1.8 and above
objectMapper.getSerializationConfig().setDateFormat(myDateFormat); // for earlier versions (deprecated for 1.8+)

How come this time is off by 9 hours? (5 hours, 3 hours etc)

You may be thinking in terms of your local time zone. Remember that Jackson defaults to using GMT (Greenwich time, one hour behind central European timezone; multiple hours ahead of US time zones).

Can I configure it on per-property basis?

Yes, with Jackson 2.0 you can use the new @JsonFormat annotation:

public class DateStuff {
    @JsonFormat(shape=JsonFormat.Shape.STRING, pattern="yyyy-MM-dd,HH:00", timezone="CET")
    public Date creationTime;
}

Notes on java.sql.Date

(aka "Please do NOT use java.sql.Date, ever!")

Although Jackson supports java.sql.Date, there are known issues with respect to timezone handling, partly due to design of this class. It is recommended that this type is avoided, if possible, and regular java.util.Date (or java.util.Calendar) used instead. If this is not possible, it may be necessary for applications to convert these dates using java.util.Calendar and explicit timezone definition.

Date Deserialization

Which date formats are supported by default?

RFC-1123, ISO-8601 (or rather, commonly used subset). Also, numeric (integer) serializations are recognized, assumed to be in Unix timestamp notation (milliseconds since epoch, Jan 1st 1970 GMT)

Can this be configured?

Yes: similar to serialization configuration, you can call:

objectMapper.getDeserializationConfig().setDateFormat(myDateFormat);

Interoperability

Joda Time

Starting with version 1.4, Jackson offers some support for Joda Time data types: basically, its DateTime can be automatically serialized/deserialized similar to how java.util.Date is handled. More support can be added based on user requests.

With version 2.0, support for Joda date/time types was moved to a new module, Jackson-datatype-Joda, to reduce dependencies core databind has, as well as to make it easier to update Joda-specific functionality. To use the module, you will need to add the dependency (via Maven, or by including module jar), and register module; this will add full support similar to how Jackson 1.x works.