0
# Groovy JSON
1

2
The Groovy JSON library provides comprehensive JSON processing capabilities for the Apache Groovy programming language. It offers high-performance JSON parsing with multiple parser implementations, flexible JSON generation via builders with DSL support, customizable JSON serialization, and utilities for low-level JSON processing.
3

4
## Package Information
5

6
- **Package Name**: groovy-json
7
- **Package Type**: maven
8
- **Language**: Java/Groovy
9
- **Maven Coordinates**: `org.apache.groovy:groovy-json:5.0.0`
10
- **Installation**: Add dependency to your build.gradle or pom.xml
11

12
### Gradle
13
```groovy
14
implementation 'org.apache.groovy:groovy-json:5.0.0'
15
```
16

17
### Maven
18
```xml
19
<dependency>
20
    <groupId>org.apache.groovy</groupId>
21
    <artifactId>groovy-json</artifactId>
22
    <version>5.0.0</version>
23
</dependency>
24
```
25

26
## Core Imports
27

28
```java
29
import groovy.json.*;
30
```
31

32
Specific imports:
33
```java
34
import groovy.json.JsonSlurper;
35
import groovy.json.JsonSlurperClassic;
36
import groovy.json.JsonBuilder;
37
import groovy.json.StreamingJsonBuilder;
38
import groovy.json.JsonOutput;
39
import groovy.json.JsonGenerator;
40
import groovy.json.JsonLexer;
41
import groovy.json.JsonToken;
42
import groovy.json.JsonException;
43
import groovy.json.JsonParserType;
44
```
45

46
## Basic Usage
47

48
```java
49
import groovy.json.JsonSlurper;
50
import groovy.json.JsonBuilder;
51
import groovy.json.JsonOutput;
52
import java.nio.file.Path;
53
import java.nio.file.Paths;
54

55
// Parse JSON
56
JsonSlurper jsonSlurper = new JsonSlurper();
57
Object result = jsonSlurper.parseText('{"name":"John","age":30,"city":"New York"}');
58

59
// Parse from Path (Java NIO)
60
Path jsonPath = Paths.get("data.json");
61
Object pathResult = jsonSlurper.parse(jsonPath);
62

63
// Build JSON using DSL
64
JsonBuilder json = new JsonBuilder();
65
json.person {
66
    name "Alice"
67
    age 25
68
    location {
69
        city "San Francisco"
70
        state "CA"
71
    }
72
}
73
String jsonString = json.toString();
74

75
// Convert objects to JSON
76
Map<String, Object> data = new HashMap<>();
77
data.put("message", "Hello World");
78
data.put("timestamp", new Date());
79
String output = JsonOutput.toJson(data);
80
```
81

82
## Architecture
83

84
The Groovy JSON library is built around several key architectural components:
85

86
- **Parsing Engine**: Multiple parser implementations (INDEX_OVERLAY, CHARACTER_SOURCE, LAX, CHAR_BUFFER) optimized for different use cases and data sizes
87
- **Builder DSL**: Groovy's dynamic method invocation and closure support enables intuitive JSON construction syntax
88
- **Streaming Architecture**: Memory-efficient processing for large JSON documents through streaming builders and windowing parsers
89
- **Customization Layer**: Extensible JsonGenerator system with converters, field exclusion, and formatting options
90
- **Type System**: Full integration with Groovy's dynamic typing while maintaining Java interoperability
91

92
## Capabilities
93

94
### JSON Parsing
95

96
High-performance JSON parsing with multiple parser implementations optimized for different scenarios, from small payloads to large streaming documents.
97

98
```java { .api }
99
public class JsonSlurper {
100
    public JsonSlurper();
101
    public Object parseText(String text);
102
    public Object parse(Reader reader);
103
    public Object parse(File file);
104
    public Object parse(URL url);
105
    public JsonSlurper setType(JsonParserType type);
106
}
107

108
public enum JsonParserType {
109
    INDEX_OVERLAY,    // Fastest parser with pointers to original buffer
110
    CHARACTER_SOURCE, // Parser for large files using windowing
111
    LAX,             // Relaxed parser allowing comments and unquoted keys
112
    CHAR_BUFFER      // Fast basic parser without index overlay
113
}
114
```
115

116
[JSON Parsing](./json-parsing.md)
117

118
### JSON Building
119

120
DSL-based JSON building with Groovy's closure syntax, supporting both in-memory and streaming approaches for flexible JSON construction.
121

122
```java { .api }
123
public class JsonBuilder extends GroovyObjectSupport implements Writable {
124
    public JsonBuilder();
125
    public JsonBuilder(Object content);
126
    public Object call(Map m);
127
    public Object call(Closure c);
128
    public String toString();
129
    public String toPrettyString();
130
}
131

132
public class StreamingJsonBuilder extends GroovyObjectSupport {
133
    public StreamingJsonBuilder(Writer writer);
134
    public Object call(Map m) throws IOException;
135
    public Object call(Closure c) throws IOException;
136
}
137
```
138

139
[JSON Building](./json-building.md)
140

141
### JSON Output & Serialization
142

143
Comprehensive JSON serialization utilities with customizable generation, type conversion, and formatting options.
144

145
```java { .api }
146
public class JsonOutput {
147
    public static String toJson(Object object);
148
    public static String toJson(Map m);
149
    public static String toJson(Date date);
150
    public static String prettyPrint(String jsonPayload);
151
    public static JsonUnescaped unescaped(CharSequence text);
152
}
153

154
public interface JsonGenerator {
155
    public String toJson(Object object);
156
    public boolean isExcludingFieldsNamed(String name);
157
    public boolean isExcludingValues(Object value);
158
}
159
```
160

161
[JSON Output & Serialization](./json-output.md)
162

163
### Low-level Processing
164

165
Token-based JSON processing for fine-grained control over parsing and custom JSON processing workflows.
166

167
```java { .api }
168
public class JsonLexer implements Iterator<JsonToken> {
169
    public JsonLexer(Reader reader);
170
    public JsonToken nextToken();
171
    public boolean hasNext();
172
    public JsonToken next();
173
}
174

175
public class JsonToken {
176
    public Object getValue();
177
    public JsonTokenType getType();
178
    public long getStartLine();
179
    public long getStartColumn();
180
}
181

182
public enum JsonTokenType {
183
    OPEN_CURLY, CLOSE_CURLY, OPEN_BRACKET, CLOSE_BRACKET,
184
    COLON, COMMA, NULL, TRUE, FALSE, NUMBER, STRING
185
}
186
```
187

188
[Low-level Processing](./low-level-processing.md)
189

190
### Utilities & Extensions
191

192
Utility classes for string escaping, performance optimization, and error handling in JSON processing workflows.
193

194
```java { .api }
195
public class StringEscapeUtils {
196
    public static String escapeJava(String str);
197
    public static String unescapeJava(String str);
198
    public static String escapeJavaScript(String str);
199
    public static String unescapeJavaScript(String str);
200
}
201

202
public class JsonException extends RuntimeException {
203
    public JsonException();
204
    public JsonException(String message);
205
    public JsonException(String message, Throwable cause);
206
}
207
```
208

209
[Utilities & Extensions](./utilities.md)
210

211
## Common Types
212

213
```java { .api }
214
// Core parsing interface
215
public interface JsonParser {
216
    Object parse(String jsonString);
217
    Object parse(Reader reader);
218
    Object parse(File file, String charset);
219
    Object parse(InputStream input);
220
    Object parse(byte[] bytes);
221
}
222

223
// JSON generation options builder
224
public static class JsonGenerator.Options {
225
    public Options excludeNulls();
226
    public Options disableUnicodeEscaping();
227
    public Options dateFormat(String format);
228
    public Options timezone(String timezone);
229
    public Options addConverter(Converter converter);
230
    public Options excludeFieldsByName(CharSequence... fieldNames);
231
    public Options excludeFieldsByType(Class<?>... types);
232
    public JsonGenerator build();
233
}
234

235
// Custom type conversion
236
interface JsonGenerator.Converter {
237
    boolean handles(Class<?> type);
238
    Object convert(Object value, String key);
239
}
240
```