FAQ

1. General

1.1 Which mappings (Badgerfish, natural, ...) does Jackson implement?

None. Jackson is "100% JSON" and does not try to imitate or emulate XML.

2. Processing Models

Which processing models (streaming, tree, objects) does Jackson implement?

Three main methods (one with 2 alternatives) are implemented:

Streaming/incremental parsing (reading) and generation (writing) of JSON content
Tree model (based on JsonNodes)
Data binding to/from Java objects (POJOs, Beans, primitives, lists/arrays/maps)
- alternative "untyped" binding to only use Lists/Maps/String/Boolean/Number/null (bind to Object.class)

Most other Java JSON packages only implement one or two of modes: for example, Json.org's reference implementation implements tree model.

3. Data Binding, general

What mechanism does Jackson use for binding?

Jackson 1.0 supports Bean method - based binding, where serialization requires "getter" methods, and deserialization "setters" (with optional "creator" methods). Version 1.1 will additionally support optional direct access of member fields (public instance fields, annotated instance fields).

How does Jackson map JSON properties to Java methods/fields?

The default mechanism is to use implied name as per Bean convention – for getters and setters leave out "get" or "set", lower case first char – but this can be overridden by annotations (@JsonSetter/JsonGetter for Jackson 1.0, alternatively @JsonProperty for Jackson 1.1).

4. Data Binding, writing (serialization)

4.1 Custom Serializers

How can I create custom serializers?

There are two general mechanisms for doing this:

Implementing interface ''org.codehaus.jackson.map.JsonSerializable'' is similar to implementing ''java.lang.Serializable'' in that a method (serialize()) of value class is called to handle serialization.
Implementing ''org.codehaus.jackson.map.JsonSerializer'' creates an external serializer that can be registered to handle values of certain type, or values returned by a getter method.

For latter use case there are multiple ways to do registration:

Using annotations:
- Classes and methods can be annotated using @JsonUseSerializer (that takes serializer class as argument) to indicate type of serializer to use
Using custom serializer factory (''org.codehaus.jackson.map.SerializerFactory'')
1. Either use or extend existing implementation, ''org.codehaus.jackson.map.se.CustomSerializerFactory'' (or even implement one from scratch if it doesn't work for you)
2. Add mappings (from serialized Class to JsonSerializer instance) by calling ''addSpecificMapping'' or ''addGenericMapping'' (check out Javadocs for explanation on difference)
3. Custom serializer factory needs to be registered with ''ObjectMapper.setSerializerFactory'' to be used by ObjectMapper

4.2 Serializing Dates

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).

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.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.getSerializationConfig().setDateFormat(myDateFormat);

4.3 Serializing, other

Can I omit writing of Bean properties with null value?

Yes. Fortunately someone requested such a feature, so that you can configure mapper:

objectMapper.configure(SerializationConfig.WRITE_NULL_PROPERTIES, false);

and voila, no more null values. Note that you MUST configure mapper before beans are serialized, since this setting may be cached along with serializers. So setting it too late might prevent change from taking effect.

5. Data Binding, reading (de-serialization)

5.1 Deserializing dates

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);

6 Using Jackson with JAX-RS (Jersey)

6.1 Can I use Jackson to do JSON serialization with JAX-RS?

Yes. Starting with Jackson 1.0, there is jar (jackson-jaxrs-VERSION.jar) that implements JAX-RS MessageBodyReader and MessageBodyWriter , needed for converting Java beans to/from JSON.

In addition to adding jackson-jaxrs jar (and jackson core and mapper jars it depends on, if not bundled by the JAX-RS implementation), you will also need to register provider. There are 2 ways to do this:

Add root provider with JAX-RS registration mechanism; for example, by returning provider class/instance from Rest Application class.
Add 'META-INF/services/javax.ws.rs.ext.MessageBodyReader' file with one entry , provider class name, 'org.codehaus.jackson.jaxrs.JacksonJsonProvider' (and similarly for MessageBodyWriter) to a jar that gets loaded by JAX-RS implementation (this can be done by post-processing jackson-jaxrs jar, for example).

FAQ