Jackson FAQ: 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.
Basics
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) 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).
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.
Known Issues
Handling of date types when used as java.util.Map keys does not follow above guidelines: rather, a simple call is made to toString() method of Key value on serialization; and on deserialization side, set of types supported out-of-box is limited and does not include any Date types. This should be fixed in future Jackson versions (in 1.9 or later)