0
# Jackson Core
1

2
Jackson Core provides the fundamental streaming JSON parsing and generation capabilities for the Jackson data processing toolkit. It offers low-level incremental processing through a streaming API with JsonParser for reading and JsonGenerator for writing JSON content, serving as the foundation for all Jackson-based JSON processing including data-binding and alternative data formats.
3

4
## Package Information
5

6
- **Package Name**: jackson-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.fasterxml.jackson.core</groupId>
13
      <artifactId>jackson-core</artifactId>
14
      <version>2.19.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.fasterxml.jackson.core.JsonFactory;
22
import com.fasterxml.jackson.core.JsonParser;
23
import com.fasterxml.jackson.core.JsonGenerator;
24
import com.fasterxml.jackson.core.JsonToken;
25
```
26

27
## Basic Usage
28

29
```java
30
import com.fasterxml.jackson.core.*;
31
import java.io.*;
32

33
public class BasicExample {
34
    public static void main(String[] args) throws Exception {
35
        // Create a reusable JsonFactory
36
        JsonFactory factory = JsonFactory.builder()
37
            .enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)
38
            .build();
39

40
        // Reading JSON
41
        String jsonInput = "{\"name\":\"John\",\"age\":30,\"active\":true}";
42
        JsonParser parser = factory.createParser(jsonInput);
43
        
44
        while (parser.nextToken() != JsonToken.END_OBJECT) {
45
            if (parser.getCurrentToken() == JsonToken.FIELD_NAME) {
46
                String fieldName = parser.getCurrentName();
47
                parser.nextToken();
48
                
49
                switch (fieldName) {
50
                    case "name":
51
                        String name = parser.getValueAsString();
52
                        System.out.println("Name: " + name);
53
                        break;
54
                    case "age":
55
                        int age = parser.getValueAsInt();
56
                        System.out.println("Age: " + age);
57
                        break;
58
                    case "active":
59
                        boolean active = parser.getValueAsBoolean();
60
                        System.out.println("Active: " + active);
61
                        break;
62
                }
63
            }
64
        }
65
        parser.close();
66

67
        // Writing JSON
68
        StringWriter stringWriter = new StringWriter();
69
        JsonGenerator generator = factory.createGenerator(stringWriter);
70
        
71
        generator.writeStartObject();
72
        generator.writeStringField("name", "Jane");
73
        generator.writeNumberField("age", 25);
74
        generator.writeBooleanField("active", false);
75
        generator.writeEndObject();
76
        generator.close();
77
        
78
        System.out.println("Generated JSON: " + stringWriter.toString());
79
    }
80
}
81
```
82

83
## Architecture
84

85
Jackson Core is built around several key components:
86

87
- **JsonFactory**: Thread-safe factory for creating parsers and generators with configurable features
88
- **Streaming API**: Token-based parsing (JsonParser) and generation (JsonGenerator) for memory-efficient processing
89
- **Feature System**: Comprehensive configuration through feature enums for reading and writing behavior
90
- **Constraint System**: Configurable limits for security and performance (StreamReadConstraints, StreamWriteConstraints)
91
- **Symbol Tables**: Efficient field name canonicalization for improved memory usage and performance
92
- **Non-blocking Support**: Async parsing capabilities for high-performance applications
93

94
## Capabilities
95

96
### Factory and Configuration
97

98
Central factory class for creating JSON processors with comprehensive configuration options including features, constraints, and buffer management.
99

100
```java { .api }
101
public class JsonFactory extends TokenStreamFactory implements java.io.Serializable {
102
    public JsonParser createParser(String content) throws IOException;
103
    public JsonParser createParser(InputStream in) throws IOException;
104
    public JsonParser createParser(Reader r) throws IOException;
105
    public JsonParser createParser(byte[] data) throws IOException;
106
    public JsonParser createParser(File f) throws IOException;
107
    
108
    public JsonGenerator createGenerator(OutputStream out) throws IOException;
109
    public JsonGenerator createGenerator(Writer w) throws IOException;
110
    public JsonGenerator createGenerator(File f, JsonEncoding enc) throws IOException;
111
}
112

113
public static class JsonFactoryBuilder extends TSFBuilder<JsonFactory, JsonFactoryBuilder> {
114
    public JsonFactoryBuilder enable(JsonFactory.Feature f);
115
    public JsonFactoryBuilder disable(JsonFactory.Feature f);
116
    public JsonFactoryBuilder streamReadConstraints(StreamReadConstraints src);
117
    public JsonFactoryBuilder streamWriteConstraints(StreamWriteConstraints swc);
118
    public JsonFactory build();
119
}
120
```
121

122
[Factory and Configuration](./factory-configuration.md)
123

124
### JSON Parsing
125

126
Streaming JSON parser for token-based processing with support for all JSON data types, numeric coercion, and configurable parsing features.
127

128
```java { .api }
129
public abstract class JsonParser implements Closeable, Versioned {
130
    public abstract JsonToken nextToken() throws IOException;
131
    public abstract JsonToken getCurrentToken();
132
    public abstract String getCurrentName() throws IOException;
133
    
134
    public abstract String getText() throws IOException;
135
    public abstract String getValueAsString() throws IOException;
136
    public abstract int getValueAsInt() throws IOException;
137
    public abstract long getValueAsLong() throws IOException;
138
    public abstract double getValueAsDouble() throws IOException;
139
    public abstract boolean getValueAsBoolean() throws IOException;
140
    
141
    public abstract BigInteger getBigIntegerValue() throws IOException;
142
    public abstract BigDecimal getDecimalValue() throws IOException;
143
    public abstract NumberType getNumberType() throws IOException;
144
}
145

146
public enum JsonToken {
147
    NOT_AVAILABLE, START_OBJECT, END_OBJECT, START_ARRAY, END_ARRAY,
148
    FIELD_NAME, VALUE_STRING, VALUE_NUMBER_INT, VALUE_NUMBER_FLOAT,
149
    VALUE_TRUE, VALUE_FALSE, VALUE_NULL
150
}
151
```
152

153
[JSON Parsing](./json-parsing.md)
154

155
### JSON Generation
156

157
Streaming JSON generator for writing JSON content with support for all JSON data types, pretty printing, and configurable output features.
158

159
```java { .api }
160
public abstract class JsonGenerator implements Closeable, Flushable, Versioned {
161
    public abstract void writeStartObject() throws IOException;
162
    public abstract void writeEndObject() throws IOException;
163
    public abstract void writeStartArray() throws IOException;
164
    public abstract void writeEndArray() throws IOException;
165
    
166
    public abstract void writeFieldName(String name) throws IOException;
167
    public abstract void writeString(String text) throws IOException;
168
    public abstract void writeNumber(int i) throws IOException;
169
    public abstract void writeNumber(long l) throws IOException;
170
    public abstract void writeNumber(double d) throws IOException;
171
    public abstract void writeNumber(BigDecimal dec) throws IOException;
172
    public abstract void writeBoolean(boolean state) throws IOException;
173
    public abstract void writeNull() throws IOException;
174
    
175
    public void writeStringField(String fieldName, String value) throws IOException;
176
    public void writeNumberField(String fieldName, int value) throws IOException;
177
    public void writeBooleanField(String fieldName, boolean value) throws IOException;
178
}
179
```
180

181
[JSON Generation](./json-generation.md)
182

183
### Features and Configuration
184

185
Comprehensive feature system for configuring parsing and generation behavior, including JSON-specific features and format-agnostic capabilities.
186

187
```java { .api }
188
public enum StreamReadFeature implements JacksonFeature {
189
    AUTO_CLOSE_SOURCE, STRICT_DUPLICATE_DETECTION, IGNORE_UNDEFINED,
190
    INCLUDE_SOURCE_IN_LOCATION, USE_FAST_DOUBLE_PARSER, USE_FAST_BIG_NUMBER_PARSER
191
}
192

193
public enum StreamWriteFeature implements JacksonFeature {
194
    AUTO_CLOSE_TARGET, AUTO_CLOSE_JSON_CONTENT, FLUSH_PASSED_TO_STREAM,
195
    WRITE_BIGDECIMAL_AS_PLAIN, STRICT_DUPLICATE_DETECTION, IGNORE_UNKNOWN
196
}
197

198
public final class StreamReadConstraints implements Serializable {
199
    public static Builder builder();
200
    public int getMaxStringLength();
201
    public int getMaxNumberLength();
202
    public int getMaxNestingDepth();
203
    public long getMaxDocumentLength();
204
    public int getMaxNameLength();
205
}
206
```
207

208
[Features and Configuration](./features-configuration.md)
209

210
### Exception Handling
211

212
Comprehensive exception hierarchy for JSON processing errors with detailed error reporting and location information.
213

214
```java { .api }
215
public abstract class JacksonException extends IOException {
216
    public abstract JsonLocation getLocation();
217
    public abstract String getOriginalMessage();
218
    public abstract Object getProcessor();
219
}
220

221
public abstract class JsonProcessingException extends JacksonException {
222
    protected JsonProcessingException(String msg);
223
    protected JsonProcessingException(String msg, JsonLocation loc);
224
    protected JsonProcessingException(String msg, Throwable rootCause);
225
}
226

227
public class JsonParseException extends JsonProcessingException {
228
    public JsonParseException(JsonParser p, String msg);
229
    public JsonParseException(JsonParser p, String msg, Throwable rootCause);
230
}
231
```
232

233
[Exception Handling](./exception-handling.md)
234

235
### Utilities and Advanced Features
236

237
Utility classes for buffer management, pretty printing, filtering, and advanced processing patterns including parser delegation and generator decoration.
238

239
```java { .api }
240
public class JsonParserDelegate extends JsonParser {
241
    protected JsonParser delegate;
242
    public JsonParserDelegate(JsonParser d);
243
    public JsonParser getDelegate();
244
}
245

246
public class JsonGeneratorDelegate extends JsonGenerator {
247
    protected JsonGenerator delegate;
248
    public JsonGeneratorDelegate(JsonGenerator d);
249
    public JsonGenerator getDelegate();
250
}
251

252
public interface PrettyPrinter {
253
    void writeRootValueSeparator(JsonGenerator gen) throws IOException;
254
    void writeStartObject(JsonGenerator gen) throws IOException;
255
    void writeObjectFieldValueSeparator(JsonGenerator gen) throws IOException;
256
    void writeEndObject(JsonGenerator gen, int nrOfEntries) throws IOException;
257
}
258
```
259

260
[Utilities and Advanced Features](./utilities-advanced.md)
261

262
## Types
263

264
### Core Types
265

266
```java { .api }
267
public class JsonLocation implements Serializable {
268
    public static final JsonLocation NA;
269
    public Object getSourceRef();
270
    public int getLineNr();
271
    public int getColumnNr();
272
    public long getCharOffset();
273
    public long getByteOffset();
274
}
275

276
public abstract class JsonStreamContext {
277
    public abstract JsonStreamContext getParent();
278
    public abstract String getCurrentName();
279
    public abstract boolean inObject();
280
    public abstract boolean inArray();
281
    public abstract boolean inRoot();
282
    public abstract int getCurrentIndex();
283
    public abstract int getEntryCount();
284
}
285

286
public enum JsonEncoding {
287
    UTF8("UTF-8"), UTF16_BE("UTF-16BE"), UTF16_LE("UTF-16LE"), UTF32_BE("UTF-32BE"), UTF32_LE("UTF-32LE");
288
    public String getJavaName();
289
    public boolean isBigEndian();
290
}
291
```
292

293
### Number Handling
294

295
```java { .api }
296
public enum NumberType {
297
    INT, LONG, BIG_INTEGER, FLOAT, DOUBLE, BIG_DECIMAL
298
}
299

300
public enum NumberTypeFP {
301
    UNKNOWN, FLOAT32, FLOAT64, BIG_DECIMAL
302
}
303
```
304

305
### Advanced Types
306

307
```java { .api }
308
public class JsonPointer implements Serializable {
309
    public static final JsonPointer empty();
310
    public static JsonPointer compile(String input) throws IllegalArgumentException;
311
    public static JsonPointer valueOf(String input);
312
    public JsonPointer append(JsonPointer tail);
313
    public String toString();
314
    public boolean matches();
315
}
316

317
public abstract class TypeReference<T> {
318
    protected TypeReference();
319
    public Type getType();
320
}
321
```