jackson-core
Core part of Jackson that defines Streaming API as well as basic shared abstractions
Top Related Projects
General data-binding package for Jackson (2.x): works on streaming API (core) implementation(s)
A Java serialization/deserialization library to convert Java Objects into JSON and back
FASTJSON 2.0.x has been released, faster and more secure, recommend you upgrade.
jsoniter (json-iterator) is fast and flexible JSON parser available in Java and Go
A modern JSON library for Kotlin and Java.
A reference implementation of a JSON package in Java.
Quick Overview
Jackson-core is the core part of the Jackson JSON processor, providing low-level streaming APIs for parsing and generating JSON content. It's a lightweight, fast, and flexible library that serves as the foundation for other Jackson modules, offering efficient processing of JSON data in Java applications.
Pros
- High performance and efficiency in JSON processing
- Flexible and extensible architecture
- Supports both streaming and tree-based processing
- Well-maintained and actively developed
Cons
- Lower-level API compared to jackson-databind, requiring more manual work
- Limited to JSON processing only (other formats require additional modules)
- Steeper learning curve for beginners compared to simpler JSON libraries
Code Examples
- Reading JSON using JsonParser:
JsonFactory factory = new JsonFactory();
try (JsonParser parser = factory.createParser(new File("data.json"))) {
while (parser.nextToken() != JsonToken.END_OBJECT) {
String fieldName = parser.getCurrentName();
if ("name".equals(fieldName)) {
parser.nextToken();
System.out.println(parser.getText());
}
}
}
- Writing JSON using JsonGenerator:
JsonFactory factory = new JsonFactory();
try (JsonGenerator generator = factory.createGenerator(new File("output.json"), JsonEncoding.UTF8)) {
generator.writeStartObject();
generator.writeStringField("name", "John Doe");
generator.writeNumberField("age", 30);
generator.writeEndObject();
}
- Working with JsonNode:
ObjectMapper mapper = new ObjectMapper();
JsonNode rootNode = mapper.readTree(new File("data.json"));
String name = rootNode.get("name").asText();
int age = rootNode.get("age").asInt();
Getting Started
To use jackson-core in your project, add the following dependency to your Maven pom.xml:
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.14.2</version>
</dependency>
For Gradle, add this to your build.gradle:
implementation 'com.fasterxml.jackson.core:jackson-core:2.14.2'
After adding the dependency, you can start using the library by importing the necessary classes:
import com.fasterxml.jackson.core.*;
Competitor Comparisons
General data-binding package for Jackson (2.x): works on streaming API (core) implementation(s)
Pros of jackson-databind
- Higher-level API for data binding and object mapping
- Supports automatic serialization and deserialization of POJOs
- Offers advanced features like custom serializers/deserializers and annotations
Cons of jackson-databind
- Larger library size and potentially higher memory footprint
- Slightly slower performance due to additional abstraction layers
- More complex configuration for advanced use cases
Code Comparison
jackson-core (low-level streaming API):
JsonFactory factory = new JsonFactory();
JsonGenerator generator = factory.createGenerator(new File("output.json"));
generator.writeStartObject();
generator.writeStringField("name", "John");
generator.writeNumberField("age", 30);
generator.writeEndObject();
generator.close();
jackson-databind (high-level object mapping):
ObjectMapper mapper = new ObjectMapper();
Person person = new Person("John", 30);
mapper.writeValue(new File("output.json"), person);
jackson-databind builds upon jackson-core, providing a more convenient API for working with Java objects. While jackson-core offers fine-grained control over JSON parsing and generation, jackson-databind simplifies the process by automatically handling object serialization and deserialization. The trade-off is a larger library size and slightly reduced performance compared to the low-level API. Developers should choose based on their specific requirements for flexibility, ease of use, and performance.
A Java serialization/deserialization library to convert Java Objects into JSON and back
Pros of gson
- Simpler API and easier to use for basic JSON operations
- Better performance for small JSON payloads
- More straightforward object mapping with less configuration
Cons of gson
- Less flexible for complex JSON structures
- Fewer features and customization options
- Limited support for streaming large JSON data
Code Comparison
jackson-core:
ObjectMapper mapper = new ObjectMapper();
MyObject obj = mapper.readValue(jsonString, MyObject.class);
String json = mapper.writeValueAsString(obj);
gson:
Gson gson = new Gson();
MyObject obj = gson.fromJson(jsonString, MyObject.class);
String json = gson.toJson(obj);
Both jackson-core and gson are popular Java libraries for JSON processing. jackson-core offers more advanced features and flexibility, making it suitable for complex JSON handling and high-performance scenarios. gson, on the other hand, provides a simpler API that's easier to use for basic JSON operations, making it a good choice for smaller projects or when simplicity is preferred over extensive customization options.
jackson-core excels in handling large JSON datasets and offers better streaming capabilities, while gson performs well with smaller payloads. The choice between the two often depends on the specific requirements of the project and the developer's familiarity with each library.
FASTJSON 2.0.x has been released, faster and more secure, recommend you upgrade.
Pros of fastjson
- Generally faster parsing and serialization performance
- Supports more data types out of the box
- Simpler API for common use cases
Cons of fastjson
- Less mature and stable compared to jackson-core
- Fewer configuration options and customization features
- Limited support for advanced JSON features
Code Comparison
fastjson:
String jsonString = JSON.toJSONString(object);
MyObject obj = JSON.parseObject(jsonString, MyObject.class);
jackson-core:
ObjectMapper mapper = new ObjectMapper();
String jsonString = mapper.writeValueAsString(object);
MyObject obj = mapper.readValue(jsonString, MyObject.class);
Both libraries offer straightforward APIs for JSON serialization and deserialization. fastjson's API is slightly more concise, while jackson-core provides more flexibility through the ObjectMapper class.
fastjson is known for its high performance and ease of use, making it popular in scenarios where speed is crucial. However, jackson-core offers more robust features, better documentation, and wider community support, making it a more suitable choice for complex applications or those requiring extensive customization.
The choice between these libraries depends on specific project requirements, such as performance needs, feature set, and long-term maintainability.
jsoniter (json-iterator) is fast and flexible JSON parser available in Java and Go
Pros of json-iterator/java
- Faster parsing and serialization performance in many scenarios
- More memory-efficient, with lower allocation rates
- Supports non-blocking parsing for improved concurrency
Cons of json-iterator/java
- Less mature and widely adopted compared to jackson-core
- Smaller ecosystem and fewer third-party extensions
- May lack some advanced features present in jackson-core
Code Comparison
jackson-core:
ObjectMapper mapper = new ObjectMapper();
MyObject obj = mapper.readValue(jsonString, MyObject.class);
String json = mapper.writeValueAsString(obj);
json-iterator/java:
JsonIterator iter = JsonIterator.parse(jsonString);
MyObject obj = iter.read(MyObject.class);
String json = JsonStream.serialize(obj);
Both libraries offer similar functionality for parsing and serializing JSON, but json-iterator/java aims to provide better performance through its optimized parsing and serialization algorithms. However, jackson-core has a larger ecosystem and more extensive feature set, making it a more versatile choice for complex use cases. The choice between the two depends on specific project requirements, performance needs, and ecosystem considerations.
A modern JSON library for Kotlin and Java.
Pros of Moshi
- Designed specifically for Kotlin, offering better integration with Kotlin features
- Smaller library size and faster compilation times
- More straightforward API, making it easier to use for simpler projects
Cons of Moshi
- Less feature-rich compared to Jackson, with fewer data format supports
- Smaller community and ecosystem, potentially leading to fewer third-party extensions
- May require more manual configuration for complex serialization scenarios
Code Comparison
Jackson:
ObjectMapper mapper = new ObjectMapper();
MyObject obj = mapper.readValue(jsonString, MyObject.class);
String json = mapper.writeValueAsString(obj);
Moshi:
val moshi = Moshi.Builder().build()
val adapter = moshi.adapter(MyObject::class.java)
val obj = adapter.fromJson(jsonString)
val json = adapter.toJson(obj)
Both libraries offer similar functionality for JSON serialization and deserialization, but Moshi's API is more Kotlin-friendly. Jackson provides more extensive features and customization options, while Moshi focuses on simplicity and Kotlin integration. The choice between the two often depends on project requirements, existing ecosystem, and developer preferences.
A reference implementation of a JSON package in Java.
Pros of JSON-java
- Simpler API with fewer dependencies, making it easier to use for small projects
- Lightweight and self-contained, suitable for environments with limited resources
- More straightforward parsing and generation of JSON data
Cons of JSON-java
- Less feature-rich compared to jackson-core, lacking advanced functionalities
- Lower performance for large-scale JSON processing tasks
- Limited support for custom serialization and deserialization
Code Comparison
JSON-java:
JSONObject obj = new JSONObject();
obj.put("name", "John");
obj.put("age", 30);
String jsonString = obj.toString();
jackson-core:
ObjectMapper mapper = new ObjectMapper();
ObjectNode obj = mapper.createObjectNode();
obj.put("name", "John");
obj.put("age", 30);
String jsonString = mapper.writeValueAsString(obj);
Both libraries allow for creating and manipulating JSON objects, but jackson-core offers more flexibility and advanced features through its ObjectMapper class. JSON-java provides a more straightforward approach with its JSONObject class, which may be preferable for simpler use cases.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Overview
This project contains core low-level incremental ("streaming") parser and generator abstractions used by Jackson Data Processor. It also includes the default implementation of handler types (parser, generator) that handle JSON format. The core abstractions are not JSON specific, although naming does contain 'JSON' in many places, due to historical reasons. Only packages that specifically contain word 'json' are JSON-specific.
This package is the base on which Jackson data-binding package builds on. It is licensed under Apache License 2.0.
Alternate data format implementations (like Smile (binary JSON), XML, CSV, Protobuf, and CBOR) also build on this base package, implementing the core interfaces, making it possible to use standard data-binding package regardless of underlying data format.
Project contains versions 2.0 and above: source code for earlier (1.x) versions can be found from Jackson-1 github repo.
Status
Type | Status |
---|---|
Build (CI) | |
Artifact | |
OSS Sponsorship | |
Javadocs | |
Code coverage (2.18) | |
CodeQ (ClusterFuzz) | |
OpenSSF Score |
Get it!
Maven
Functionality of this package is contained in
Java package com.fasterxml.jackson.core
.
To use the package, you need to use following Maven dependency:
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${jackson.version.core}</version>
</dependency>
or download jars from Maven repository or links on Wiki. Core jar is a functional OSGi bundle, with proper import/export declarations.
Package has no external dependencies, except for testing (which uses JUnit
).
Non-Maven
For non-Maven use cases, you download jars from Central Maven repository.
Core 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.
Use it!
General
Usage typically starts with creation of a reusable (and thread-safe, once configured) JsonFactory
instance:
// Builder-style since 2.10:
JsonFactory factory = JsonFactory.builder()
// configure, if necessary:
.enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)
.build();
// older 2.x mechanism, still supported for 2.x
JsonFactory factory = new JsonFactory();
// configure, if necessary:
factory.enable(JsonReadFeature.ALLOW_JAVA_COMMENTS);
Alternatively, you have an ObjectMapper
(from Jackson Databind package) handy; if so, you can do:
JsonFactory factory = objectMapper.getFactory();
Usage, simple reading
All reading is by using JsonParser
(or its sub-classes, in case of data formats other than JSON),
instance of which is constructed by JsonFactory
.
An example can be found from Reading and Writing Event Streams
Usage, simple writing
All writing is by using JsonGenerator
(or its sub-classes, in case of data formats other than JSON),
instance of which is constructed by JsonFactory
:
An example can be found from Reading and Writing Event Streams
Processing limits
Starting with Jackson 2.15, Jackson has configurable limits for some aspects of input decoding and output generation.
Implemented limits are:
- Length are expressed in input/output units --
byte
s orchar
s -- depending on input source - Defined as longest allowed length, but not necessarily imposed at 100% accuracy: that is, if maximum allowed length is specified as 1000 units, something with length of, say 1003 may not cause exception (but 1500 would typically do)
- Defined using new
StreamReadConstraints
/StreamWriteConstraints
classes, configurable on per-JsonFactory
basis - Main focus is to reduce likelihood of excessive memory usage/retention and/or processing costs; not validation
Input parsing limits
- Maximum Number token length (2.15+): (see https://github.com/FasterXML/jackson-core/issues/815)
- Default: Maximum 1000 for both integral and floating-point numbers.
- Maximum String value length (2.15+): (see https://github.com/FasterXML/jackson-core/issues/863)
- Default: 20_000_000 (20 million) (since 2.15.1; 2.15.0 had lower limit, 5 million)
- Maximum Input nesting depth (2.15+): (see https://github.com/FasterXML/jackson-core/pull/943)
- Default: 1000 levels
- Maximum Property name length (2.16+): (see https://github.com/FasterXML/jackson-core/issues/1047)
- Default: 50,000
- Maximum Document length (2.16+): (see https://github.com/FasterXML/jackson-core/issues/1046)
- Default: Unlimited (-1)
Output generation limits
- Maximum Output nesting depth (2.16+): (see https://github.com/FasterXML/jackson-core/pull/1055)
- Default: 1000 levels
Re-configuring limits
You can change per-factory limits as follows:
JsonFactory f = JsonFactory.builder()
.streamReadConstraints(StreamReadConstraints.builder().maxDocumentLength(10_000_000L).build())
.streamReadConstraints(StreamReadConstraints.builder().maxNumberLength(250).build())
.streamWriteConstraints(StreamWriteConstraints.builder().maxNestingDepth(2000).build())
.build();
Error Report Configuration
Starting with Jackson 2.16, Jackson offers configurable behavior around error-reporting.
Currently supported configuration options are:
maxErrorTokenLength
: Maximum length of token to include in error messages (2.16+): (see #1066)maxRawContentLength
: Maximum length of raw content to include in error messages (2.16+): (see #1066)
... see Example section below.
Example
JsonFactory f = JsonFactory.builder()
.errorReportConfiguration(ErrorReportConfiguration.builder()
.maxErrorTokenLength(1004)
.maxRawContentLength(2008)
.build()
).build();
Compatibility
JDK
Jackson-core package baseline JDK requirement:
- Versions 2.0 - 2.13 require JDK 6
- Versions 2.14 and above require JDK 8
Android
List is incomplete due to recent addition of compatibility checker.
- 2.13: Android SDK 19+
- 2.14 and above: Android SDK 26+
for information on Android SDK versions to Android Release names see Android version history
Release Process
Starting with Jackson 2.15, releases of this module will be SLSA compliant: see issue #844 for details.
Release process is triggered by
./release.sh
script which uses Maven Release plug-in under the hood (earlier release plug-in was directly invoked).
Support
Community support
Jackson components are supported by the Jackson community through mailing lists, Gitter forum, Github issues. See Participation, Contributing for full details.
Enterprise support
Available as part of the Tidelift Subscription.
The maintainers of jackson-core
and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.
Further reading
Differences from Jackson 1.x
Project contains versions 2.0 and above: source code for the latest 1.x version (1.9.13) is available from FasterXML/jackson-1 repo (unmaintained).
Note that the main differences compared to 1.0 core jar are:
- Maven build instead of Ant
- Annotations carved out to a separate package (that this package depends on)
- Java package is now
com.fasterxml.jackson.core
(instead oforg.codehaus.jackson
)
Links
- Project Wiki has JavaDocs and links to downloadable artifacts
- Jackson (portal) has links to all FasterXML-maintained "official" Jackson components
- Jackson Docs is the portal/hub for all kinds of Jackson documentation
Top Related Projects
General data-binding package for Jackson (2.x): works on streaming API (core) implementation(s)
A Java serialization/deserialization library to convert Java Objects into JSON and back
FASTJSON 2.0.x has been released, faster and more secure, recommend you upgrade.
jsoniter (json-iterator) is fast and flexible JSON parser available in Java and Go
A modern JSON library for Kotlin and Java.
A reference implementation of a JSON package in Java.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot