While the original use case for Jackson was JSON data-binding, it can now be used for other data formats as well, as long as parser and generator implementations exist.
Naming of classes uses word 'JSON' in many places even though there is no actual hard dependency to JSON format.

Get it!

Maven

Functionality of this package is contained in Java package com.fasterxml.jackson.databind, and can be used using following Maven dependency:

Since package also depends on jackson-core and jackson-annotations packages, you will need to download these if not using Maven; and you may also want to add them as Maven dependency to ensure that compatible versions are used.
If so, also add:

Non-Maven

Databind jar is also a functional OSGi bundle, with proper import/export declarations, so it can be use on OSGi container as is.

Use It!

More comprehensive documentation can be found from Jackson-docs repository; as well as from Wiki of this project.
But here are brief introductionary tutorials, in recommended order of reading.

1 minute tutorial: POJOs to JSON and back

The most common usage is to take piece of JSON, and construct a Plain Old Java Object ("POJO") out of it. So let's start there. With simple 2-property POJO like this:

// Note: can use getters/setters as well; here we just use public fields directly:publicclassMyValue {
publicString name;
publicint age;
// NOTE: if using getters/setters, can keep fields `protected` or `private`
}

we will need a com.fasterxml.jackson.databind.ObjectMapper instance, used for all data-binding, so let's construct one:

ObjectMapper mapper =newObjectMapper(); // create once, reuse

The default instance is fine for our use -- we will learn later on how to configure mapper instance if necessary. Usage is simple:

While dealing with Maps, Lists and other "simple" Object types (Strings, Numbers, Booleans) can be simple, Object traversal can be cumbersome.
This is where Jackson's Tree model can come in handy:

// can be read as generic JsonNode, if it can be Object or Array; or,// if known to be Object, as ObjectNode, if array, ArrayNode etc:ObjectNode root = mapper.readTree("stuff.json");
String name = root.get("name").asText();
int age = root.get("age").asInt();
// can modify as well: this adds child Object as property 'other', set property 'type'
root.with("other").put("type", "student");
String json = mapper.writeValueAsString(root);
// with above, we end up with something like as 'json' String:// {// "name" : "Bob", "age" : 13,// "other" : {// "type" : "student"// }// }

Tree Model can be more convenient than data-binding, especially in cases where structure is highly dynamic, or does not map nicely to Java classes.

5 minute tutorial: Streaming parser, generator

As convenient as data-binding (to/from POJOs) can be; and as flexible as Tree model can be, there is one more canonical processing model available: incremental (aka "streaming") model.
It is the underlying processing model that data-binding and Tree Model both build upon, but it is also exposed to users who want ultimate performance and/or control over parsing or generation details.

For in-depth explanation, look at Jackson Core component.
But let's look at a simple teaser to whet your appetite:

(TO BE COMPLETED)

10 minute tutorial: configuration

There are two entry-level configuration mechanisms you are likely to use:
Features and Annotations.

Commonly used Features

Here are examples of configuration features that you are most likely to need to know about.

Let's start with higher-level data-binding configuration.

// SerializationFeature for changing how JSON is written// to enable standard indentation ("pretty-printing"):
mapper.enable(SerializationFeature.INDENT_OUTPUT);
// to allow serialization of "empty" POJOs (no properties to serialize)// (without this setting, an exception is thrown in those cases)
mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);
// to write java.util.Date, Calendar as number (timestamp):
mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
// DeserializationFeature for changing how JSON is read as POJOs:// to prevent exception when encountering unknown property:
mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
// to allow coercion of JSON empty String ("") to null Object value:
mapper.enable(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT);

In addition, you may need to change some of low-level JSON parsing, generation details:

Annotations: Ignoring properties

There are two main annotations that can be used to to ignore properties: @JsonIgnore for individual properties; and @JsonIgnoreProperties for per-class definition

// means that if we see "foo" or "bar" in JSON, they will be quietly skipped// regardless of whether POJO has such properties
@JsonIgnoreProperties({ "foo", "bar" })
publicclassMyBean
{
// will not be written as JSON; nor assigned from JSON:@JsonIgnorepublicString internal;
// no annotation, public field is read/written normallypublicString external;
@JsonIgnorepublicvoidsetCode(intc) { _code = c; }
// note: will also be ignored because setter has annotation!publicintgetCode() { return _code; }
}

As with renaming, note that annotations are "shared" between matching fields, getters and setters: if only one has @JsonIgnore, it affects others.
But it is also possible to use "split" annotations, to for example:

in this case, no "name" property would be written out (since 'getter' is ignored); but if "name" property was found from JSON, it would be assigned to POJO property!

For a more complete explanation of all possible ways of ignoring properties when writing out JSON, check "Filtering properties" article.

Annotations: using custom constructor

Unlike many other data-binding packages, Jackson does not require you to define "default constructor" (constructor that does not take arguments).
While it will use one if nothing else is available, you can easily define that an argument-taking constructor is used:

Note that use of a "creator method" (@JsonCreator with @JsonProperty annotated arguments) does not preclude use of setters: you
can mix and match properties from constructor/factory method with ones that
are set via setters or directly using fields.

Tutorial: fancier stuff, conversions

One useful (but not very widely known) feature of Jackson is its ability
to do arbitrary POJO-to-POJO conversions. Conceptually you can think of conversions as sequence of 2 steps: first, writing a POJO as JSON, and second, binding that JSON into another kind of POJO. Implementation just skips actual generation of JSON, and uses more efficient intermediate representation.

Conversations work between any compatible types, and invocation is as simple as:

Basically, Jackson can work as a replacement for many Apache Commons components, for tasks like base64 encoding/decoding, and handling of "dyna beans" (Maps to/from POJOs).

Contribute!

We would love to get your contribution, whether it's in form of bug reports, Requests for Enhancement (RFE), documentation, or code patches.
The primary mechanism for all of above is GitHub Issues system.

Basic rules for Code Contributions

There is really just one main rule, which is that to accept any code contribution, we need to get a filled Contributor License Agreement (CLA) from the author. One CLA is enough for any number of contributions, but we need one. Or, rather, companies that use our code want it. It keeps their lawyers less unhappy about Open Source usage.