JsonSlurper (Groovy 6.0.0-alpha-2)

groovy.json.JsonSlurper

```
public class JsonSlurper
extends Object
```
This has the same interface as the original JsonSlurper written for version 1.8.0, but its implementation has completely changed. It is now up to 20x faster than before, and its speed competes and often substantially exceeds popular common JSON parsers circa Jan, 2014.
JSON slurper parses text or reader content into a data structure of lists and maps.
Example usage:
```
 def slurper = new groovy.json.JsonSlurper()
 def result = slurper.parseText('{"person":{"name":"Guillaume","age":33,"pets":["dog","cat"]}}')

 assert result.person.name == "Guillaume"
 assert result.person.age == 33
 assert result.person.pets.size() == 2
 assert result.person.pets[0] == "dog"
 assert result.person.pets[1] == "cat"
 
```
JsonSlurper can use several types of JSON parsers. Please read the documentation for JsonParserType. There are relaxed mode parsers, large file parser, and index overlay parsers. Don't worry, it is all groovy. JsonSlurper will just work, but understanding the different parser types may allow you to drastically improve the performance of your JSON parsing.
Index overlay parsers (INDEX_OVERLAY and LAX) are the fastest JSON parsers. However they are not the default for a good reason. Index overlay parsers has pointers (indexes really) to original char buffer. Care must be used if putting parsed maps into a long term cache as members of map maybe index overlay objects pointing to original buffer. You can mitigate these risks by using chop and lazy chop properties.
Chop eagerly dices up the buffer so each Value element points to a small copy of the original buffer.
Lazy Chop dices up the buffer when a list get or map get is called so if an GPath expression or such is applied.
You do not need chop or lazy chop if you are NOT putting the map into a long term cache. You do not need chop or lazy chop if you are doing object de-serialization. Recommendation is to use INDEX_OVERLAY for JSON buffers under 2MB. The maxSizeForInMemory is set to 2MB and any file over 2MB will use a parser designed for large files, which is slower than the INDEX_OVERLAY, LAX, and CHAR_BUFFER parsers, but faster than most commonly used JSON parsers on the JVM for most use cases circa January 2014.
To enable the INDEX_OVERLAY parser do this:
```
             parser = new JsonSlurper().setType(JsonParserType.INDEX_OVERLAY);
 
```
See Also:
JsonParserType
Since:
1.8.0

Methods Summary

Methods
Type Params	Return Type	Name and description
	`public int`	`getMaxNestingDepth()` The maximum nesting depth of arrays/objects the parser will accept before throwing a JsonException.
	`public int`	`getMaxSizeForInMemory()` The threshold (in characters) that selects which parser strategy the `File`-based parse methods use: documents smaller than this are parsed in memory, larger ones use a windowing buffer parser.
	`public JsonParserType`	`getType()` Parser type.
	`public boolean`	`isCheckDates()` Determine if slurper will automatically parse strings it recognizes as dates.
	`public boolean`	`isChop()` Turns on buffer chopping for index overlay.
	`public boolean`	`isLazyChop()` Turns on buffer lazy chopping for index overlay.
	`public Object`	`parse(Reader reader)` Parse a JSON data structure from content from a reader
	`public Object`	`parse(InputStream inputStream)` Parse a JSON data structure from content from an inputStream
	`public Object`	`parse(InputStream inputStream, String charset)` Parse a JSON data structure from content from an inputStream
	`public Object`	`parse(byte[] bytes, String charset)` Parse a JSON data structure from content from a byte array.
	`public Object`	`parse(byte[] bytes)` Parse a JSON data structure from content from a byte array.
	`public Object`	`parse(char[] chars)` Parse a JSON data structure from content from a char array.
	`public Object`	`parse(Path path)` Parse a JSON data structure from content within a given Path.
	`public Object`	`parse(Path path, String charset)` Parse a JSON data structure from content within a given Path.
	`public Object`	`parse(File file)` Parse a JSON data structure from content within a given File.
	`public Object`	`parse(File file, String charset)` Parse a JSON data structure from content within a given File.
	`public Object`	`parse(URL url)` Parse a JSON data structure from content at a given URL.
	`public Object`	`parse(URL url, Map params)` Parse a JSON data structure from content at a given URL.
	`public Object`	`parse(Map<String, ?> params, URL url)` Parse a JSON data structure from content at a given URL.
	`public Object`	`parse(URL url, String charset)` Parse a JSON data structure from content at a given URL.
	`public Object`	`parse(URL url, Map params, String charset)` Parse a JSON data structure from content at a given URL.
	`public Object`	`parse(Map params, URL url, String charset)` Parse a JSON data structure from content at a given URL.
	`public Object`	`parseText(String text)` Parse a text representation of a JSON data structure
	`public JsonSlurper`	`setCheckDates(boolean checkDates)` Determine if slurper will automatically parse strings it recognizes as dates.
	`public JsonSlurper`	`setChop(boolean chop)` Turns on buffer chopping for index overlay.
	`public JsonSlurper`	`setLazyChop(boolean lazyChop)` Turns on buffer lazy chopping for index overlay.
	`public JsonSlurper`	`setMaxNestingDepth(int maxNestingDepth)` Sets the maximum nesting depth of arrays/objects the parser will accept before throwing a JsonException.
	`public JsonSlurper`	`setMaxSizeForInMemory(int maxSizeForInMemory)` Sets the threshold that selects which parser strategy the `File`-based parse methods use (see getMaxSizeForInMemory()).
	`public JsonSlurper`	`setType(JsonParserType type)` Parser type.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- Method Detail
  - public int getMaxNestingDepth()
    
    The maximum nesting depth of arrays/objects the parser will accept before throwing a JsonException. This guards the recursive-descent parsers against a small but deeply-nested document driving a StackOverflowError. A value of 0 or less disables the check (restoring the previous, unbounded behaviour). Defaults to BaseJsonParser.DEFAULT_MAX_NESTING_DEPTH, and can be overridden globally with the groovy.json.maxNestingDepth system property.
    Returns:
    the maximum nesting depth
    Since:
    6.0.0
  - public int getMaxSizeForInMemory()
    
    The threshold (in characters) that selects which parser strategy the File-based parse methods use: documents smaller than this are parsed in memory, larger ones use a windowing buffer parser.
    This is a parser-strategy selector, not a size limit. It does not reject or cap input — an oversized document is still parsed in full (by the windowing parser). It is consulted only by the File-based parse methods; the parse(Reader), parse(InputStream) and parse(URL) entry points ignore it and buffer their entire input into memory regardless of this value. To bound untrusted input, limit its size yourself before parsing (and cap nesting via setMaxNestingDepth(int) or the groovy.json.maxNestingDepth system property).
    Returns:
    the in-memory vs windowing-parser selection threshold
    Since:
    2.3
  - public JsonParserType getType()
    
    Parser type.
    Since:
    2.3
    See Also:
    JsonParserType
    Returns:
    type
  - public boolean isCheckDates()
    
    Determine if slurper will automatically parse strings it recognizes as dates. Index overlay only.
    Returns:
    on or off
    Since:
    2.3
  - public boolean isChop()
    
    Turns on buffer chopping for index overlay.
    Since:
    2.3
    See Also:
    JsonParserType
    Returns:
    chop on or off
  - public boolean isLazyChop()
    
    Turns on buffer lazy chopping for index overlay.
    See Also:
    JsonParserType
    Returns:
    on or off
    Since:
    2.3
  - public Object parse(Reader reader)
    
    Parse a JSON data structure from content from a reader
    Parameters:
    reader - reader over a JSON content
    Returns:
    a data structure of lists and maps
  - public Object parse(InputStream inputStream)
    
    Parse a JSON data structure from content from an inputStream
    Parameters:
    inputStream - stream over a JSON content
    Returns:
    a data structure of lists and maps
    Since:
    2.3
  - public Object parse(InputStream inputStream, String charset)
    
    Parse a JSON data structure from content from an inputStream
    Parameters:
    inputStream - stream over a JSON content
    charset - charset
    Returns:
    a data structure of lists and maps
    Since:
    2.3
  - public Object parse(byte[] bytes, String charset)
    
    Parse a JSON data structure from content from a byte array.
    Parameters:
    bytes - buffer of JSON content
    charset - charset
    Returns:
    a data structure of lists and maps
    Since:
    2.3
  - public Object parse(byte[] bytes)
    
    Parse a JSON data structure from content from a byte array.
    Parameters:
    bytes - buffer of JSON content
    Returns:
    a data structure of lists and maps
    Since:
    2.3
  - public Object parse(char[] chars)
    
    Parse a JSON data structure from content from a char array.
    Parameters:
    chars - buffer of JSON content
    Returns:
    a data structure of lists and maps
    Since:
    2.3
  - public Object parse(Path path)
    
    Parse a JSON data structure from content within a given Path.
    Parameters:
    path - Path containing JSON content
    Returns:
    a data structure of lists and maps
  - public Object parse(Path path, String charset)
    
    Parse a JSON data structure from content within a given Path.
    Parameters:
    path - Path containing JSON content
    charset - the charset for this File
    Returns:
    a data structure of lists and maps
  - public Object parse(File file)
    
    Parse a JSON data structure from content within a given File.
    Parameters:
    file - File containing JSON content
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(File file, String charset)
    
    Parse a JSON data structure from content within a given File.
    Parameters:
    file - File containing JSON content
    charset - the charset for this File
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(URL url)
    
    Parse a JSON data structure from content at a given URL.
    Parameters:
    url - URL containing JSON content
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(URL url, Map params)
    
    Parse a JSON data structure from content at a given URL.
    Parameters:
    url - URL containing JSON content
    params - connection parameters
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(@NamedParam(value = "connectTimeout", type = Integer.class)
    @NamedParam(value = "readTimeout", type = Integer.class)
    @NamedParam(value = "useCaches", type = Boolean.class)
    @NamedParam(value = "allowUserInteraction", type = Boolean.class)
    @NamedParam(value = "requestProperties", type = Map.class)
    Map<String, ?> params, URL url)
    
    Parse a JSON data structure from content at a given URL. Convenience variant when using Groovy named parameters for the connection params.
    Parameters:
    params - connection parameters
    url - URL containing JSON content
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(URL url, String charset)
    
    Parse a JSON data structure from content at a given URL.
    Parameters:
    url - URL containing JSON content
    charset - the charset for this File
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(URL url, Map params, String charset)
    
    Parse a JSON data structure from content at a given URL.
    Parameters:
    url - URL containing JSON content
    params - connection parameters
    charset - the charset for this File
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parse(Map params, URL url, String charset)
    
    Parse a JSON data structure from content at a given URL. Convenience variant when using Groovy named parameters for the connection params.
    Parameters:
    params - connection parameters
    url - URL containing JSON content
    charset - the charset for this File
    Returns:
    a data structure of lists and maps
    Since:
    2.2.0
  - public Object parseText(String text)
    
    Parse a text representation of a JSON data structure
    Parameters:
    text - JSON text to parse
    Returns:
    a data structure of lists and maps
  - public JsonSlurper setCheckDates(boolean checkDates)
    
    Determine if slurper will automatically parse strings it recognizes as dates. Index overlay only.
    Returns:
    on or off
    Since:
    2.3
  - public JsonSlurper setChop(boolean chop)
    
    Turns on buffer chopping for index overlay.
    Since:
    2.3
    See Also:
    JsonParserType
    Returns:
    JsonSlurper
  - public JsonSlurper setLazyChop(boolean lazyChop)
    
    Turns on buffer lazy chopping for index overlay.
    See Also:
    JsonParserType
    Returns:
    JsonSlurper
    Since:
    2.3
  - public JsonSlurper setMaxNestingDepth(int maxNestingDepth)
    
    Sets the maximum nesting depth of arrays/objects the parser will accept before throwing a JsonException. A value of 0 or less disables the check.
    Parameters:
    maxNestingDepth - maximum number of nested arrays/objects to allow
    Returns:
    this JsonSlurper
    Since:
    6.0.0
  - public JsonSlurper setMaxSizeForInMemory(int maxSizeForInMemory)
    
    Sets the threshold that selects which parser strategy the File-based parse methods use (see getMaxSizeForInMemory()).
    This selects a parser strategy; it does not limit or reject input. Setting it gives no DoS protection: it is not consulted by parse(Reader), parse(InputStream) or parse(URL), and even the File-based methods still parse documents larger than the threshold. Bound untrusted input by its size before parsing, and cap nesting via setMaxNestingDepth(int) or groovy.json.maxNestingDepth.
    Parameters:
    maxSizeForInMemory - the in-memory vs windowing-parser selection threshold
    Returns:
    this JsonSlurper instance
    Since:
    2.3
  - public JsonSlurper setType(JsonParserType type)
    
    Parser type.
    Since:
    2.3
    See Also:
    JsonParserType
    Returns:
    JsonSlurper

Summary:
Method

| Detail:
Method

[Java] Class JsonSlurper

Methods Summary

Inherited Methods Summary

Method Detail

public int getMaxNestingDepth()

public int getMaxSizeForInMemory()

public JsonParserType getType()

public boolean isCheckDates()

public boolean isChop()

public boolean isLazyChop()

public Object parse(Reader reader)

public Object parse(InputStream inputStream)

public Object parse(InputStream inputStream, String charset)

public Object parse(byte[] bytes, String charset)

public Object parse(byte[] bytes)

public Object parse(char[] chars)

public Object parse(Path path)

public Object parse(Path path, String charset)

public Object parse(File file)

public Object parse(File file, String charset)

public Object parse(URL url)

public Object parse(URL url, Map params)

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)

public Object parseText(String text)

public JsonSlurper setCheckDates(boolean checkDates)

public JsonSlurper setChop(boolean chop)

public JsonSlurper setLazyChop(boolean lazyChop)

public JsonSlurper setMaxNestingDepth(int maxNestingDepth)

public JsonSlurper setMaxSizeForInMemory(int maxSizeForInMemory)

public JsonSlurper setType(JsonParserType type)