Package groovy.json

# Class JsonSlurper

java.lang.Object
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);

`

`JsonSlurper` reads the whole document into memory and does not bound total input size (only nesting depth, via `setMaxNestingDepth(int)`). For very large documents, bound the input size before parsing, or use a streaming / Jackson-based parser instead; Groovy interoperates cleanly with Jackson (the `groovy-yaml`/`groovy-toml`/`groovy-csv` slurpers are already Jackson-backed).

Since:
  1.8.0
See Also:
  - `JsonParserType`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JsonSlurper()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JsonDateHandling`
  `getDateHandling()`
  What a string in a full ISO-8601 or JSON-date form is turned into.
  `int`
  `getMaxNestingDepth()`
  The maximum nesting depth of arrays/objects the parser will accept before throwing a `JsonException`.
  `int`
  `getMaxNumberLength()`
  The maximum length, in characters, of a single number token the parser will accept before throwing a `JsonException`.
  `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.
  `JsonParserType`
  `getType()`
  Parser type.
  `boolean`
  `isCheckDates()`
  Deprecated.
  a boolean cannot say which type is wanted; use `getDateHandling()`
  `boolean`
  `isChop()`
  Turns on buffer chopping for index overlay.
  `boolean`
  `isLazyChop()`
  Turns on buffer lazy chopping for index overlay.
  `Object`
  `parse(byte[] bytes)`
  Parse a JSON data structure from content from a byte array.
  `Object`
  `parse(byte[] bytes, String charset)`
  Parse a JSON data structure from content from a byte array.
  `Object`
  `parse(char[] chars)`
  Parse a JSON data structure from content from a char array.
  `Object`
  `parse(File file)`
  Parse a JSON data structure from content within a given File.
  `Object`
  `parse(File file, String charset)`
  Parse a JSON data structure from content within a given File.
  `Object`
  `parse(InputStream inputStream)`
  Parse a JSON data structure from content from an inputStream
  `Object`
  `parse(InputStream inputStream, String charset)`
  Parse a JSON data structure from content from an inputStream
  `Object`
  `parse(Reader reader)`
  Parse a JSON data structure from content from a reader
  `Object`
  `parse(URL url)`
  Parse a JSON data structure from content at a given URL.
  `Object`
  `parse(URL url, String charset)`
  Parse a JSON data structure from content at a given URL.
  `Object`
  `parse(URL url, Map params)`
  Parse a JSON data structure from content at a given URL.
  `Object`
  `parse(URL url, Map params, String charset)`
  Parse a JSON data structure from content at a given URL.
  `Object`
  `parse(Path path)`
  Parse a JSON data structure from content within a given Path.
  `Object`
  `parse(Path path, String charset)`
  Parse a JSON data structure from content within a given Path.
  `Object`
  `parse(Map<String,?> params, URL url)`
  Parse a JSON data structure from content at a given URL.
  `Object`
  `parse(Map params, URL url, String charset)`
  Parse a JSON data structure from content at a given URL.
  `Object`
  `parseText(String text)`
  Parse a text representation of a JSON data structure
  `JsonSlurper`
  `setCheckDates(boolean checkDates)`
  Deprecated.
  a boolean cannot say which type is wanted; use `setDateHandling(JsonDateHandling)`
  `JsonSlurper`
  `setChop(boolean chop)`
  Turns on buffer chopping for index overlay.
  `JsonSlurper`
  `setDateHandling(JsonDateHandling dateHandling)`
  Sets what a string in a full ISO-8601 or JSON-date form is turned into.
  `JsonSlurper`
  `setLazyChop(boolean lazyChop)`
  Turns on buffer lazy chopping for index overlay.
  `JsonSlurper`
  `setMaxNestingDepth(int maxNestingDepth)`
  Sets the maximum nesting depth of arrays/objects the parser will accept before throwing a `JsonException`.
  `JsonSlurper`
  `setMaxNumberLength(int maxNumberLength)`
  Sets the maximum length, in characters, of a single number token the parser will accept before throwing a `JsonException`.
  `JsonSlurper`
  `setMaxSizeForInMemory(int maxSizeForInMemory)`
  Sets the threshold that selects which parser strategy the `File`-based parse methods use (see `getMaxSizeForInMemory()`).
  `JsonSlurper`
  `setType(JsonParserType type)`
  Parser type.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### JsonSlurper

    public JsonSlurper()

- ## Method Details

  - ### getMaxSizeForInMemory

    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

  - ### setMaxSizeForInMemory

    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

  - ### getType

    public JsonParserType getType()
    Parser type.
    Returns:
      type
    Since:
      2.3
    See Also:
      - `JsonParserType`

  - ### setType

    public JsonSlurper setType(JsonParserType type)
    Parser type.
    Returns:
      JsonSlurper
    Since:
      2.3
    See Also:
      - `JsonParserType`

  - ### isChop

    public boolean isChop()
    Turns on buffer chopping for index overlay.
    Returns:
      chop on or off
    Since:
      2.3
    See Also:
      - `JsonParserType`

  - ### setChop

    public JsonSlurper setChop(boolean chop)
    Turns on buffer chopping for index overlay.
    Returns:
      JsonSlurper
    Since:
      2.3
    See Also:
      - `JsonParserType`

  - ### isLazyChop

    public boolean isLazyChop()
    Turns on buffer lazy chopping for index overlay.
    Returns:
      on or off
    Since:
      2.3
    See Also:
      - `JsonParserType`

  - ### setLazyChop

    public JsonSlurper setLazyChop(boolean lazyChop)
    Turns on buffer lazy chopping for index overlay.
    Returns:
      JsonSlurper
    Since:
      2.3
    See Also:
      - `JsonParserType`

  - ### isCheckDates

    @Deprecated public boolean isCheckDates()
    Deprecated.
    a boolean cannot say which type is wanted; use `getDateHandling()`
    Whether a string in a full ISO-8601 or JSON-date form is returned as a `Date` rather than as a `String`. On by default.

    This applies to `JsonParserType.INDEX_OVERLAY` and `JsonParserType.LAX`; the other two parser types return the string either way, so setting this has no effect on them. A date without a time, such as `"2026-09-04"`, is left as a `String` by all four.

    Returns:
      whether date-like strings are converted
    Since:
      2.3

  - ### setCheckDates

    @Deprecated public JsonSlurper setCheckDates(boolean checkDates)
    Deprecated.
    a boolean cannot say which type is wanted; use `setDateHandling(JsonDateHandling)`
    Sets whether a string in a full ISO-8601 or JSON-date form is returned as a `Date` rather than as a `String`. On by default.

    This applies to `JsonParserType.INDEX_OVERLAY` and `JsonParserType.LAX`; the other two parser types return the string either way, so setting this has no effect on them. Note that a `Date` is an instant, so an offset in the source is not preserved by the conversion. Has no effect once `setDateHandling(JsonDateHandling)` has been called on this slurper, so that a choice made through the wider option is not undone by this one.

    Parameters:
      `checkDates` - whether date-like strings should be converted
    Returns:
      this slurper, for chaining
    Since:
      2.3

  - ### getDateHandling

    public JsonDateHandling getDateHandling()
    What a string in a full ISO-8601 or JSON-date form is turned into.
    Returns:
      the handling in effect
    Since:
      6.0.0

  - ### setDateHandling

    public JsonSlurper setDateHandling(JsonDateHandling dateHandling)
    Sets what a string in a full ISO-8601 or JSON-date form is turned into. Defaults to `JsonDateHandling.UTIL_DATE`, which is what a slurper has always produced.

    This applies to `JsonParserType.INDEX_OVERLAY` and `JsonParserType.LAX`; the other two parser types return the string whatever is set here. A date carrying no time, such as `"2026-09-04"`, is left as a `String` by all four. Calling this also makes `setCheckDates(boolean)` a no-op on this slurper, whichever order the two are called in.

    Parameters:
      `dateHandling` - what a date-like string should become
    Returns:
      this slurper, for chaining
    Since:
      6.0.0

  - ### getMaxNestingDepth

    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

  - ### setMaxNestingDepth

    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

  - ### getMaxNumberLength

    public int getMaxNumberLength()
    The maximum length, in characters, of a single number token the parser will accept before throwing a `JsonException`. Converting a digit run past the `long` range builds a `BigInteger` or `BigDecimal`, and decimal conversion is superlinear in the digit count, so an uncapped token lets a small document cost quadratic CPU. A value of `0` or less disables the check (restoring the previous, unbounded behaviour). Defaults to `BaseJsonParser.DEFAULT_MAX_NUMBER_LENGTH`, and can be overridden globally with the `groovy.json.maxNumberLength` system property.
    Returns:
      the maximum number token length
    Since:
      6.0.0

  - ### setMaxNumberLength

    public JsonSlurper setMaxNumberLength(int maxNumberLength)
    Sets the maximum length, in characters, of a single number token the parser will accept before throwing a `JsonException`. A value of `0` or less disables the check.
    Parameters:
      `maxNumberLength` - maximum number of characters in a number token
    Returns:
      this `JsonSlurper`
    Since:
      6.0.0

  - ### parseText

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    public Object parse(Path path) throws IOException
    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
    Throws:
      `IOException`

  - ### parse

    public Object parse(Path path, String charset) throws IOException
    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
    Throws:
      `IOException`

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    public Object parse(@NamedParam(value="connectTimeout",type=java.lang.Integer.class) @NamedParam(value="readTimeout",type=java.lang.Integer.class) @NamedParam(value="useCaches",type=java.lang.Boolean.class) @NamedParam(value="allowUserInteraction",type=java.lang.Boolean.class) @NamedParam(value="requestProperties",type=java.util.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

  - ### parse

    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

  - ### parse

    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

  - ### parse

    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