Package groovy.json

Class JsonSlurper

java.lang.Object
groovy.json.JsonSlurper

public class JsonSlurper
extends java.lang.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);
 
Since:
1.8.0
See Also:
JsonParserType
  • Constructor Summary

    Constructors
    Constructor Description
    JsonSlurper()  
  • Method Summary

    Modifier and Type Method Description
    int getMaxSizeForInMemory()
    Max size before Slurper starts to use windowing buffer parser.
    JsonParserType getType()
    Parser type.
    boolean isCheckDates()
    Determine if slurper will automatically parse strings it recognizes as dates.
    boolean isChop()
    Turns on buffer chopping for index overlay.
    boolean isLazyChop()
    Turns on buffer lazy chopping for index overlay.
    java.lang.Object parse​(byte[] bytes)
    Parse a JSON data structure from content from a byte array.
    java.lang.Object parse​(byte[] bytes, java.lang.String charset)
    Parse a JSON data structure from content from a byte array.
    java.lang.Object parse​(char[] chars)
    Parse a JSON data structure from content from a char array.
    java.lang.Object parse​(java.io.File file)
    Parse a JSON data structure from content within a given File.
    java.lang.Object parse​(java.io.File file, java.lang.String charset)
    Parse a JSON data structure from content within a given File.
    java.lang.Object parse​(java.io.InputStream inputStream)
    Parse a JSON data structure from content from an inputStream
    java.lang.Object parse​(java.io.InputStream inputStream, java.lang.String charset)
    Parse a JSON data structure from content from an inputStream
    java.lang.Object parse​(java.io.Reader reader)
    Parse a JSON data structure from content from a reader
    java.lang.Object parse​(java.net.URL url)
    Parse a JSON data structure from content at a given URL.
    java.lang.Object parse​(java.net.URL url, java.lang.String charset)
    Parse a JSON data structure from content at a given URL.
    java.lang.Object parse​(java.net.URL url, java.util.Map params)
    Parse a JSON data structure from content at a given URL.
    java.lang.Object parse​(java.net.URL url, java.util.Map params, java.lang.String charset)
    Parse a JSON data structure from content at a given URL.
    java.lang.Object parse​(java.nio.file.Path path)
    Parse a JSON data structure from content within a given Path.
    java.lang.Object parse​(java.nio.file.Path path, java.lang.String charset)
    Parse a JSON data structure from content within a given Path.
    java.lang.Object parse​(java.util.Map params, java.net.URL url)
    Parse a JSON data structure from content at a given URL.
    java.lang.Object parse​(java.util.Map params, java.net.URL url, java.lang.String charset)
    Parse a JSON data structure from content at a given URL.
    java.lang.Object parseText​(java.lang.String text)
    Parse a text representation of a JSON data structure
    JsonSlurper setCheckDates​(boolean checkDates)
    Determine if slurper will automatically parse strings it recognizes as dates.
    JsonSlurper setChop​(boolean chop)
    Turns on buffer chopping for index overlay.
    JsonSlurper setLazyChop​(boolean lazyChop)
    Turns on buffer lazy chopping for index overlay.
    JsonSlurper setMaxSizeForInMemory​(int maxSizeForInMemory)
    Max size before Slurper starts to use windowing buffer parser.
    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()
      Max size before Slurper starts to use windowing buffer parser.
      Returns:
      size of file/buffer
      Since:
      2.3
    • setMaxSizeForInMemory

      public JsonSlurper setMaxSizeForInMemory​(int maxSizeForInMemory)
      Max size before Slurper starts to use windowing buffer parser.
      Returns:
      JsonSlurper
      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

      public boolean isCheckDates()
      Determine if slurper will automatically parse strings it recognizes as dates. Index overlay only.
      Returns:
      on or off
      Since:
      2.3
    • setCheckDates

      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
    • parseText

      public java.lang.Object parseText​(java.lang.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 java.lang.Object parse​(java.io.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 java.lang.Object parse​(java.io.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 java.lang.Object parse​(java.io.InputStream inputStream, java.lang.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 java.lang.Object parse​(byte[] bytes, java.lang.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 java.lang.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 java.lang.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 java.lang.Object parse​(java.nio.file.Path path) throws java.io.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:
      java.io.IOException
    • parse

      public java.lang.Object parse​(java.nio.file.Path path, java.lang.String charset) throws java.io.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:
      java.io.IOException
    • parse

      public java.lang.Object parse​(java.io.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 java.lang.Object parse​(java.io.File file, java.lang.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 java.lang.Object parse​(java.net.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 java.lang.Object parse​(java.net.URL url, java.util.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 java.lang.Object parse​(java.util.Map params, java.net.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 java.lang.Object parse​(java.net.URL url, java.lang.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 java.lang.Object parse​(java.net.URL url, java.util.Map params, java.lang.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 java.lang.Object parse​(java.util.Map params, java.net.URL url, java.lang.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