Overview

This project contains the general-purpose data-binding functionality and tree-model for Jackson Data Processor. It builds on Streaming API (stream parser/generator) package, and uses Jackson Annotations for configuration. Project is licensed under Apache License 2.0.

While the original use case for Jackson was JSON data-binding, it can now be used to read content encoded in 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.

Status

Type	Status
Build (CI)
Artifact
OSS Sponsorship
Javadocs
Code coverage (3.x)
OpenSSF Score

Get it!

Maven

Functionality of this package is contained in Java package tools.jackson.databind (for Jackson 3.x), and can be used using following Maven dependency:

<properties>
  ...
  <!-- Use the latest version whenever possible. -->
  <jackson.version>3.0.0</jackson.version>
  ...
</properties>

<dependencies>
  ...
  <dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>${jackson.version}</version>
  </dependency>
  ...
</dependencies>

Package also depends on jackson-core and jackson-annotations packages, but when using build tools like Maven or Gradle, dependencies are automatically included. You may, however, want to use jackson-bom to ensure compatible versions of dependencies. If not using build tool that can handle dependencies using project's pom.xml, you will need to download and include these 2 jars explicitly.

Non-Maven dependency resolution

For use cases that do not automatically resolve dependencies from Maven repositories, you can still download jars from Central Maven repository.

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

Jackson 2.10 and above include module-info.class definitions so the jar is also a proper Java Module (JPMS).

Jackson 2.12 and above include additional Gradle 6 Module Metadata for version alignment with Gradle.

---

Compatibility

JDK

Jackson-databind package baseline JDK requirements are as follows:

• Versions 2.x require JDK 8
• Versions 3.x require JDK 17

Android

List is incomplete due to compatibility checker addition being done for Jackson 2.13.

• 2.14 - 2.19: Android SDK 26+
• 3.0: Android SDK 34+

for information on Android SDK versions to Android Release names see [https://en.wikipedia.org/wiki/Android_version_history]

---

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:
public class MyValue {
  public String name;
  public int age;
  // NOTE: if using getters/setters, can keep fields `protected` or `private`
}

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

// With default settings can use
ObjectMapper mapper = new ObjectMapper(); // create once, reuse

// But if configuration needed, use builder pattern:
ObjectMapper mapper = JsonMapper.builder()
    // configuration
    .build();

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

MyValue value = mapper.readValue(new File("data.json"), MyValue.class);
// or:
value = mapper.readValue(new URL("http://some.com/api/entry.json"), MyValue.class);
// or:
value = mapper.readValue("{\"name\":\"Bob\", \"age\":13}", MyValue.class);

And if we want to write JSON, we do the reverse:

mapper.writeValue(new File("result.json"), myResultObject);
// or:
byte[] jsonBytes = mapper.writeValueAsBytes(myResultObject);
// or:
String jsonString = mapper.writeValueAsString(myResultObject);

So far so good?

3 minute tutorial: Generic collections, Tree Model

Beyond dealing with simple Bean-style POJOs, you can also handle JDK Lists, Maps:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗