0
# JSON Parsing
1

2
JsonParser provides streaming, token-based JSON parsing with efficient memory usage and support for all JSON data types. It processes JSON content incrementally, making it suitable for large documents and memory-constrained environments.
3

4
## Core Parsing API
5

6
### Token Navigation
7

8
```java { .api }
9
public abstract JsonToken nextToken() throws IOException;
10
public abstract JsonToken getCurrentToken();
11
public abstract String getCurrentName() throws IOException;
12
public JsonToken nextValue() throws IOException;
13
public boolean hasCurrentToken();
14
public boolean hasToken(JsonToken t);
15
public boolean hasTokenId(int id);
16
public void clearCurrentToken();
17
public JsonToken getLastClearedToken();
18
```
19

20
### Location Information
21

22
```java { .api }
23
public abstract JsonLocation getTokenLocation();
24
public abstract JsonLocation getCurrentLocation();
25
public JsonStreamContext getParsingContext();
26
```
27

28
## Token Types
29

30
```java { .api }
31
public enum JsonToken {
32
    NOT_AVAILABLE(null, JsonTokenId.ID_NOT_AVAILABLE),
33
    START_OBJECT("{", JsonTokenId.ID_START_OBJECT),
34
    END_OBJECT("}", JsonTokenId.ID_END_OBJECT),
35
    START_ARRAY("[", JsonTokenId.ID_START_ARRAY),
36
    END_ARRAY("]", JsonTokenId.ID_END_ARRAY),
37
    FIELD_NAME(null, JsonTokenId.ID_FIELD_NAME),
38
    VALUE_STRING(null, JsonTokenId.ID_STRING),
39
    VALUE_NUMBER_INT(null, JsonTokenId.ID_NUMBER_INT),
40
    VALUE_NUMBER_FLOAT(null, JsonTokenId.ID_NUMBER_FLOAT),
41
    VALUE_TRUE("true", JsonTokenId.ID_TRUE),
42
    VALUE_FALSE("false", JsonTokenId.ID_FALSE),
43
    VALUE_NULL("null", JsonTokenId.ID_NULL);
44
    
45
    public String asString();
46
    public boolean isNumeric();
47
    public boolean isBoolean();
48
    public boolean isScalarValue();
49
    public boolean isStructStart();
50
    public boolean isStructEnd();
51
}
52
```
53

54
## Value Access Methods
55

56
### String Values
57

58
```java { .api }
59
public abstract String getText() throws IOException;
60
public abstract char[] getTextCharacters() throws IOException;
61
public abstract int getTextLength() throws IOException;
62
public abstract int getTextOffset() throws IOException;
63
public abstract String getValueAsString() throws IOException;
64
public abstract String getValueAsString(String def) throws IOException;
65
```
66

67
### Numeric Values
68

69
```java { .api }
70
public abstract Number getNumberValue() throws IOException;
71
public abstract NumberType getNumberType() throws IOException;
72
public NumberTypeFP getNumberTypeFP() throws IOException;
73

74
public abstract int getIntValue() throws IOException;
75
public abstract long getLongValue() throws IOException;
76
public abstract BigInteger getBigIntegerValue() throws IOException;
77
public abstract float getFloatValue() throws IOException;
78
public abstract double getDoubleValue() throws IOException;
79
public abstract BigDecimal getDecimalValue() throws IOException;
80

81
public int getValueAsInt() throws IOException;
82
public int getValueAsInt(int def) throws IOException;
83
public long getValueAsLong() throws IOException;
84
public long getValueAsLong(long def) throws IOException;
85
public double getValueAsDouble() throws IOException;
86
public double getValueAsDouble(double def) throws IOException;
87
```
88

89
### Boolean and Other Values
90

91
```java { .api }
92
public boolean getBooleanValue() throws IOException;
93
public boolean getValueAsBoolean() throws IOException;
94
public boolean getValueAsBoolean(boolean def) throws IOException;
95
public byte[] getBinaryValue() throws IOException;
96
public byte[] getBinaryValue(Base64Variant variant) throws IOException;
97
```
98

99
## Number Types
100

101
```java { .api }
102
public enum NumberType {
103
    INT, LONG, BIG_INTEGER, FLOAT, DOUBLE, BIG_DECIMAL;
104
    
105
    public String toString();
106
}
107

108
public enum NumberTypeFP {
109
    UNKNOWN("?"), FLOAT32("32-bit"), FLOAT64("64-bit"), BIG_DECIMAL("BigDecimal");
110
    
111
    public String toString();
112
}
113
```
114

115
## Parsing Features
116

117
### JSON Read Features
118

119
```java { .api }
120
public enum JsonReadFeature implements FormatFeature {
121
    ALLOW_JAVA_COMMENTS(false),
122
    ALLOW_YAML_COMMENTS(false),
123
    ALLOW_SINGLE_QUOTES(false),
124
    ALLOW_UNQUOTED_FIELD_NAMES(false),
125
    ALLOW_UNESCAPED_CONTROL_CHARS(false),
126
    ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER(false),
127
    ALLOW_NUMERIC_LEADING_ZEROS(false),
128
    ALLOW_NON_NUMERIC_NUMBERS(false),
129
    ALLOW_MISSING_VALUES(false),
130
    ALLOW_TRAILING_COMMA(false),
131
    ALLOW_TRAILING_DECIMAL_POINT_FOR_NUMBERS(false),
132
    ALLOW_LEADING_DECIMAL_POINT_FOR_NUMBERS(false),
133
    ALLOW_LEADING_PLUS_SIGN_FOR_NUMBERS(false);
134
    
135
    public boolean enabledByDefault();
136
    public boolean enabledIn(int flags);
137
    public int getMask();
138
}
139
```
140

141
### Stream Read Features
142

143
```java { .api }
144
public enum StreamReadFeature implements JacksonFeature {
145
    AUTO_CLOSE_SOURCE(true),
146
    STRICT_DUPLICATE_DETECTION(false),
147
    IGNORE_UNDEFINED(false),
148
    INCLUDE_SOURCE_IN_LOCATION(true),
149
    USE_FAST_DOUBLE_PARSER(true),
150
    USE_FAST_BIG_NUMBER_PARSER(true);
151
    
152
    public boolean enabledByDefault();
153
    public boolean enabledIn(int flags);
154
    public int getMask();
155
}
156
```
157

158
## Advanced Parsing
159

160
### Skip Methods
161

162
```java { .api }
163
public JsonParser skipChildren() throws IOException;
164
public void finishToken() throws IOException;
165
```
166

167
### Configuration and Status
168

169
```java { .api }
170
public abstract boolean isClosed();
171
public JsonParser enable(StreamReadFeature f);
172
public JsonParser disable(StreamReadFeature f);
173
public boolean isEnabled(StreamReadFeature f);
174
public int getFeatureMask();
175
public JsonParser setFeatureMask(int mask);
176
```
177

178
### Object Codec Integration
179

180
```java { .api }
181
public ObjectCodec getCodec();
182
public void setCodec(ObjectCodec c);
183
public <T> T readValueAs(Class<T> valueType) throws IOException;
184
public <T> T readValueAs(TypeReference<T> valueTypeRef) throws IOException;
185
public <T> Iterator<T> readValuesAs(Class<T> valueType) throws IOException;
186
public <T> Iterator<T> readValuesAs(TypeReference<T> valueTypeRef) throws IOException;
187
```
188

189
## Usage Examples
190

191
### Basic Parsing Loop
192

193
```java
194
JsonParser parser = factory.createParser(jsonString);
195
while (parser.nextToken() != null) {
196
    JsonToken token = parser.getCurrentToken();
197
    switch (token) {
198
        case START_OBJECT:
199
            // Handle object start
200
            break;
201
        case FIELD_NAME:
202
            String fieldName = parser.getCurrentName();
203
            // Handle field name
204
            break;
205
        case VALUE_STRING:
206
            String stringValue = parser.getText();
207
            // Handle string value
208
            break;
209
        case VALUE_NUMBER_INT:
210
            int intValue = parser.getIntValue();
211
            // Handle integer value
212
            break;
213
        // ... handle other token types
214
    }
215
}
216
parser.close();
217
```
218

219
### Processing Specific Object Structure
220

221
```java
222
// Expecting: {"users": [{"name": "John", "age": 30}, ...]}
223
JsonParser parser = factory.createParser(jsonInput);
224

225
parser.nextToken(); // START_OBJECT
226
parser.nextToken(); // FIELD_NAME "users"
227
parser.nextToken(); // START_ARRAY
228

229
while (parser.nextToken() == JsonToken.START_OBJECT) {
230
    String name = null;
231
    int age = 0;
232
    
233
    while (parser.nextToken() != JsonToken.END_OBJECT) {
234
        String fieldName = parser.getCurrentName();
235
        parser.nextToken();
236
        
237
        switch (fieldName) {
238
            case "name":
239
                name = parser.getValueAsString();
240
                break;
241
            case "age":
242
                age = parser.getValueAsInt();
243
                break;
244
        }
245
    }
246
    
247
    System.out.println("User: " + name + ", Age: " + age);
248
}
249

250
parser.close();
251
```
252

253
### Error Handling
254

255
```java
256
try {
257
    JsonParser parser = factory.createParser(jsonInput);
258
    // ... parsing logic
259
    parser.close();
260
} catch (JsonParseException e) {
261
    System.err.println("Parse error at " + e.getLocation() + ": " + e.getMessage());
262
} catch (IOException e) {
263
    System.err.println("IO error: " + e.getMessage());
264
}
265
```
266

267
### With Features
268

269
```java
270
JsonFactory factory = JsonFactory.builder()
271
    .enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)
272
    .enable(JsonReadFeature.ALLOW_SINGLE_QUOTES)
273
    .build();
274

275
JsonParser parser = factory.createParser(jsonWithComments);
276
// Parser will now accept Java-style comments and single quotes
277
```
278

279
## Binary Data Handling
280

281
```java { .api }
282
public byte[] getBinaryValue() throws IOException;
283
public byte[] getBinaryValue(Base64Variant b64variant) throws IOException;
284
public int readBinaryValue(Base64Variant b64variant, OutputStream out) throws IOException;
285
```
286

287
Example:
288
```java
289
// JSON: {"data": "SGVsbG8gV29ybGQ="}
290
if (parser.getCurrentToken() == JsonToken.VALUE_STRING) {
291
    byte[] data = parser.getBinaryValue(); // Decodes base64 automatically
292
    String decoded = new String(data, StandardCharsets.UTF_8); // "Hello World"
293
}
294
```