tessl/maven-org-apache-groovy--groovy-json
JSON library for the Apache Groovy programming language providing JSON parsing, generation, and manipulation capabilities
—
Pending
json-parsing.mddocs/
JSON Parsing
High-performance JSON parsing with multiple parser implementations optimized for different scenarios, from small payloads to large streaming documents.
Capabilities
JsonSlurper
The primary JSON parsing class offering multiple parser implementations with configuration options for performance and feature trade-offs.
/**
* High-performance JSON parser with configurable parsing strategies
*/
public class JsonSlurper {
/** Default constructor using INDEX_OVERLAY parser */
public JsonSlurper();
/** Parse JSON from string text */
public Object parseText(String text);
/** Parse JSON from Reader */
public Object parse(Reader reader);
/** Parse JSON from InputStream */
public Object parse(InputStream inputStream);
public Object parse(InputStream inputStream, String charset);
/** Parse JSON from byte array */
public Object parse(byte[] bytes);
public Object parse(byte[] bytes, String charset);
/** Parse JSON from character array */
public Object parse(char[] chars);
/** Parse JSON from File */
public Object parse(Path path) throws IOException;
public Object parse(Path path, String charset) throws IOException;
public Object parse(File file);
public Object parse(File file, String charset);
/** Parse JSON from URL */
public Object parse(URL url);
public Object parse(URL url, Map params);
public Object parse(Map params, URL url);
public Object parse(URL url, String charset);
public Object parse(URL url, Map params, String charset);
public Object parse(Map params, URL url, String charset);
/** Configuration methods */
public JsonParserType getType();
public JsonSlurper setType(JsonParserType type);
public int getMaxSizeForInMemory();
public JsonSlurper setMaxSizeForInMemory(int maxSizeForInMemory);
public boolean isChop();
public JsonSlurper setChop(boolean chop);
public boolean isLazyChop();
public JsonSlurper setLazyChop(boolean lazyChop);
public boolean isCheckDates();
public JsonSlurper setCheckDates(boolean checkDates);
}Usage Examples:
import groovy.json.JsonSlurper;
import groovy.json.JsonParserType;
// Basic parsing
JsonSlurper jsonSlurper = new JsonSlurper();
Object result = jsonSlurper.parseText('{"name":"John","age":30}');
// Configure parser for large files
JsonSlurper largeFileSlurper = new JsonSlurper()
.setType(JsonParserType.CHARACTER_SOURCE)
.setMaxSizeForInMemory(1024 * 1024); // 1MB threshold
Object data = largeFileSlurper.parse(new File("large-data.json"));
// Parse from URL with connection parameters
Map<String, String> params = new HashMap<>();
params.put("connectTimeout", "5000");
params.put("readTimeout", "10000");
Object webData = jsonSlurper.parse(params, new URL("https://api.example.com/data"));
// Relaxed parsing with comments
JsonSlurper relaxedSlurper = new JsonSlurper().setType(JsonParserType.LAX);
Object result = relaxedSlurper.parseText("""
{
// This is a comment
"name": "John",
age: 30 // Unquoted keys allowed
}
""");JsonParserType
Enum defining different parser implementations with varying performance characteristics and feature sets.
/**
* Parser implementation types with different performance/feature trade-offs
*/
public enum JsonParserType {
/** Fastest parser using pointers to original character buffer */
INDEX_OVERLAY,
/** Parser for large files using windowing to manage memory */
CHARACTER_SOURCE,
/** Relaxed parser allowing JavaScript-style comments and unquoted keys */
LAX,
/** Fast basic parser without index overlay optimization */
CHAR_BUFFER
}Parser Selection Guide:
- INDEX_OVERLAY: Default choice for maximum performance with small to medium JSON documents
- CHARACTER_SOURCE: Use for large JSON files that exceed available memory
- LAX: Use when parsing JSON with JavaScript-style comments or unquoted property names
- CHAR_BUFFER: Alternative fast parser when INDEX_OVERLAY is not suitable
JsonSlurperClassic
Legacy JsonSlurper implementation maintained for compatibility with older Groovy versions. Provides the same parsing interface as JsonSlurper but uses the original implementation.
/**
* Original JsonSlurper implementation for compatibility with older Groovy versions
*/
public class JsonSlurperClassic {
/** Default constructor */
public JsonSlurperClassic();
/** Parse JSON from string text */
public Object parseText(String text);
/** Parse JSON from Reader */
public Object parse(Reader reader);
/** Parse JSON from InputStream */
public Object parse(InputStream inputStream);
public Object parse(InputStream inputStream, String charset);
/** Parse JSON from byte array */
public Object parse(byte[] bytes);
public Object parse(byte[] bytes, String charset);
/** Parse JSON from character array */
public Object parse(char[] chars);
/** Parse JSON from File */
public Object parse(File file);
public Object parse(File file, String charset);
/** Parse JSON from URL */
public Object parse(URL url);
public Object parse(URL url, String charset);
public Object parse(URL url, Map params);
public Object parse(URL url, Map params, String charset);
public Object parse(Map params, URL url);
public Object parse(Map params, URL url, String charset);
}Usage Examples:
import groovy.json.JsonSlurperClassic;
// Use for compatibility with legacy code
JsonSlurperClassic classicSlurper = new JsonSlurperClassic();
Object result = classicSlurper.parseText('{"legacy":"data"}');
// Same interface as JsonSlurper
Object fileData = classicSlurper.parse(new File("legacy-data.json"));
Object urlData = classicSlurper.parse(new URL("https://api.legacy.com/data"));JsonParser Interface
Core parser interface implemented by JsonSlurper and internal parser implementations for pluggable parsing strategies.
/**
* Core parsing interface for JSON processing implementations
*/
public interface JsonParser {
/** Parse JSON from string */
Object parse(String jsonString);
/** Parse JSON from byte array */
Object parse(byte[] bytes);
Object parse(byte[] bytes, String charset);
/** Parse JSON from character data */
Object parse(CharSequence charSequence);
Object parse(char[] chars);
/** Parse JSON from streams */
Object parse(Reader reader);
Object parse(InputStream input);
Object parse(InputStream input, String charset);
/** Parse JSON from file */
Object parse(File file, String charset);
}Usage Examples:
import groovy.json.JsonParser;
import groovy.json.JsonSlurper;
// JsonSlurper implements JsonParser interface
JsonParser parser = new JsonSlurper();
Object result = parser.parse('{"message":"Hello World"}');
// Use interface for pluggable parsing strategies
public class CustomJsonProcessor {
private final JsonParser parser;
public CustomJsonProcessor(JsonParser parser) {
this.parser = parser;
}
public Object processJsonFile(File file) {
return parser.parse(file, "UTF-8");
}
}Performance Considerations
Parser Selection
- Small JSON (< 1KB): INDEX_OVERLAY provides optimal performance
- Medium JSON (1KB - 10MB): INDEX_OVERLAY with default settings
- Large JSON (> 10MB): CHARACTER_SOURCE with appropriate
maxSizeForInMemory - JSON with comments: LAX parser type required
Memory Management
// Configure memory threshold for large file processing
JsonSlurper slurper = new JsonSlurper()
.setType(JsonParserType.CHARACTER_SOURCE)
.setMaxSizeForInMemory(2 * 1024 * 1024); // 2MB thresholdBuffer Optimization
// Enable buffer chopping for memory efficiency
JsonSlurper slurper = new JsonSlurper()
.setChop(true) // Enable immediate buffer chopping
.setLazyChop(false); // Disable lazy chopping for immediate memory releaseError Handling
All parsing methods throw JsonException for malformed JSON or I/O errors:
try {
JsonSlurper slurper = new JsonSlurper();
Object result = slurper.parseText("invalid json");
} catch (JsonException e) {
System.err.println("JSON parsing failed: " + e.getMessage());
}Install with Tessl CLI
npx tessl i tessl/maven-org-apache-groovy--groovy-json