StreamingJsonBuilder (Grails 3.1.1)
Date: 2016-02-04

Package: org.grails.web.json

## [Java] Class StreamingJsonBuilder

- org.grails.web.json.StreamingJsonBuilder

- Temporary fork of Groovy's JsonBuilder until Groovy 2.4.6 is released. DO NOT USE, this class will be deleted when Groovy 2.4.6 is released!

  Authors:
    Tim Yates
    Andrey Bloschetsov
    Graeme Rocher

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `static class` | `StreamingJsonBuilder.StreamingJsonDelegate` | The delegate used when invoking closures

  - ### Constructor Summary

    Constructors
    Constructor and description
    `StreamingJsonBuilder (java.io.Writer writer)` Instantiates a JSON builder.
    `StreamingJsonBuilder (java.io.Writer writer, java.lang.Object content)` Instantiates a JSON builder, possibly with some existing data structure.

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `java.lang.Object` | `call(java.util.Map m)` Named arguments can be passed to the JSON builder instance to create a root JSON object
    `void` | `call(java.lang.String name)` The empty args call will create a key whose value will be an empty JSON object:
         new StringWriter().with { w ->
             def json = new groovy.json.StreamingJsonBuilder(w)
             json.person()
    `java.lang.Object` | `call(java.util.List l)` A list of elements as arguments to the JSON builder creates a root JSON array
    `java.lang.Object` | `call(java.lang.Object... args)` Varargs elements as arguments to the JSON builder create a root JSON array
    `java.lang.Object` | `call(java.lang.Iterable coll, groovy.lang.Closure c)` A collection and closure passed to a JSON builder will create a root JSON array applying the closure to each object in the collection
    `java.lang.Object` | `call(java.util.Collection coll, groovy.lang.Closure c)` Delegates to call(Iterable, Closure)
    `java.lang.Object` | `call(groovy.lang.Closure c)` A closure passed to a JSON builder will create a root JSON object
    `void` | `call(java.lang.String name, groovy.lang.Closure c)` A name and a closure passed to a JSON builder will create a key with a JSON object
    `void` | `call(java.lang.String name, java.lang.Iterable coll, groovy.lang.Closure c)` A name, a collection and closure passed to a JSON builder will create a root JSON array applying the closure to each object in the collection
    `void` | `call(java.lang.String name, java.util.Collection coll, groovy.lang.Closure c)` Delegates to call(String, Iterable, Closure)
    `void` | `call(java.lang.String name, java.util.Map map, groovy.lang.Closure callable)` If you use named arguments and a closure as last argument, the key/value pairs of the map (as named arguments) and the key/value pairs represented in the closure will be merged together — the closure properties overriding the map key/values in case the same key is used.
    `java.lang.Object` | `invokeMethod(java.lang.String name, java.lang.Object args)` A method call on the JSON builder instance will create a root object with only one key whose name is the name of the method being called.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class groovy.lang.GroovyObjectSupport` | `groovy.lang.GroovyObjectSupport#invokeMethod(java.lang.String, java.lang.Object), groovy.lang.GroovyObjectSupport#setMetaClass(groovy.lang.MetaClass), groovy.lang.GroovyObjectSupport#getMetaClass(), groovy.lang.GroovyObjectSupport#setProperty(java.lang.String, java.lang.Object), groovy.lang.GroovyObjectSupport#getProperty(java.lang.String), groovy.lang.GroovyObjectSupport#wait(long, int), groovy.lang.GroovyObjectSupport#wait(long), groovy.lang.GroovyObjectSupport#wait(), groovy.lang.GroovyObjectSupport#equals(java.lang.Object), groovy.lang.GroovyObjectSupport#toString(), groovy.lang.GroovyObjectSupport#hashCode(), groovy.lang.GroovyObjectSupport#getClass(), groovy.lang.GroovyObjectSupport#notify(), groovy.lang.GroovyObjectSupport#notifyAll()`
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Constructor Detail

    - #### public StreamingJsonBuilder(java.io.Writer writer)

      Instantiates a JSON builder.

      Parameters:
        `writer` - A writer to which Json will be written

    - #### public StreamingJsonBuilder(java.io.Writer writer, java.lang.Object content)

      Instantiates a JSON builder, possibly with some existing data structure.

      Parameters:
        `writer` - A writer to which Json will be written
        `content` - a pre-existing data structure, default to null

  - ### Method Detail

    - #### public java.lang.Object call(java.util.Map m)

      Named arguments can be passed to the JSON builder instance to create a root JSON object

      Example:

           new StringWriter().with { w ->
             def json = new groovy.json.StreamingJsonBuilder(w)
             json name: "Tim", age: 31

             assert w.toString() == '{"name":"Tim","age":31}'
           }

      Parameters:
        `m` - a map of key / value pairs
      Returns:
        a map of key / value pairs

    - #### public void call(java.lang.String name)

      The empty args call will create a key whose value will be an empty JSON object:

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.person()

               assert w.toString() == '{"person":{}}'
           }

      throws:
        IOException
      Parameters:
        `name` - The name of the empty object to create

    - #### public java.lang.Object call(java.util.List l)

      A list of elements as arguments to the JSON builder creates a root JSON array

      Example:

           new StringWriter().with { w ->
             def json = new groovy.json.StreamingJsonBuilder(w)
             def result = json([1, 2, 3])

             assert result == [ 1, 2, 3 ]
             assert w.toString() == "[1,2,3]"
           }

      Parameters:
        `l` - a list of values
      Returns:
        a list of values

    - #### public java.lang.Object call(java.lang.Object... args)

      Varargs elements as arguments to the JSON builder create a root JSON array

      Example:

           new StringWriter().with { w ->
             def json = new groovy.json.StreamingJsonBuilder(w)
             def result = json 1, 2, 3

             assert result instanceof List
             assert w.toString() == "[1,2,3]"
           }

      Parameters:
        `args` - an array of values
      Returns:
        a list of values

    - #### public java.lang.Object call(java.lang.Iterable coll, @groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure c)

      A collection and closure passed to a JSON builder will create a root JSON array applying the closure to each object in the collection

      Example:

           class Author {
                String name
           }
           def authors = [new Author (name: "Guillaume"), new Author (name: "Jochen"), new Author (name: "Paul")]

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json authors, { Author author ->
                   name author.name
               }

               assert w.toString() == '[{"name":"Guillaume"},{"name":"Jochen"},{"name":"Paul"}]'
           }

      Parameters:
        `coll` - a collection
        `c` - a closure used to convert the objects of coll

    - #### public java.lang.Object call(java.util.Collection coll, @groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure c)

      Delegates to call(Iterable, Closure)

    - #### public java.lang.Object call(@groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure c)

      A closure passed to a JSON builder will create a root JSON object

      Example:

           new StringWriter().with { w ->
             def json = new groovy.json.StreamingJsonBuilder(w)
             json {
                name "Tim"
                age 39
             }

             assert w.toString() == '{"name":"Tim","age":39}'
           }

      Parameters:
        `c` - a closure whose method call statements represent key / values of a JSON object

    - #### public void call(java.lang.String name, @groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure c)

      A name and a closure passed to a JSON builder will create a key with a JSON object

      Example:

           new StringWriter().with { w ->
             def json = new groovy.json.StreamingJsonBuilder(w)
             json.person {
                name "Tim"
                age 39
             }

             assert w.toString() == '{"person":{"name":"Tim","age":39}}'
           }

      Parameters:
        `name` - The key for the JSON object
        `c` - a closure whose method call statements represent key / values of a JSON object

    - #### public void call(java.lang.String name, java.lang.Iterable coll, @groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure c)

      A name, a collection and closure passed to a JSON builder will create a root JSON array applying the closure to each object in the collection

      Example:

           class Author {
                String name
           }
           def authors = [new Author (name: "Guillaume"), new Author (name: "Jochen"), new Author (name: "Paul")]

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.people authors, { Author author ->
                   name author.name
               }

               assert w.toString() == '{"people":[{"name":"Guillaume"},{"name":"Jochen"},{"name":"Paul"}]}'
           }

      Parameters:
        `coll` - a collection
        `c` - a closure used to convert the objects of coll

    - #### public void call(java.lang.String name, java.util.Collection coll, @groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure c)

      Delegates to call(String, Iterable, Closure)

    - #### public void call(java.lang.String name, java.util.Map map, @groovy.lang.DelegatesTo(StreamingJsonDelegate.class) groovy.lang.Closure callable)

      If you use named arguments and a closure as last argument, the key/value pairs of the map (as named arguments) and the key/value pairs represented in the closure will be merged together — the closure properties overriding the map key/values in case the same key is used.

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.person(name: "Tim", age: 35) { town "Manchester" }

               assert w.toString() == '{"person":{"name":"Tim","age":35,"town":"Manchester"}}'
           }

      throws:
        IOException
      Parameters:
        `name` - The name of the JSON object
        `map` - The attributes of the JSON object
        `callable` - Additional attributes of the JSON object represented by the closure

    - #### public java.lang.Object invokeMethod(java.lang.String name, java.lang.Object args)

      A method call on the JSON builder instance will create a root object with only one key whose name is the name of the method being called. This method takes as arguments:

      - a closure
      - a map (ie. named arguments)
      - a map and a closure
      - or no argument at all

      Example with a classical builder-style:

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.person {
                   name "Tim"
                    age 28
               }

               assert w.toString() == '{"person":{"name":"Tim","age":28}}'
           }

      Or alternatively with a method call taking named arguments:

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.person name: "Tim", age: 32

               assert w.toString() == '{"person":{"name":"Tim","age":32}}'
           }

      If you use named arguments and a closure as last argument, the key/value pairs of the map (as named arguments) and the key/value pairs represented in the closure will be merged together — the closure properties overriding the map key/values in case the same key is used.

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.person(name: "Tim", age: 35) { town "Manchester" }

               assert w.toString() == '{"person":{"name":"Tim","age":35,"town":"Manchester"}}'
           }

      The empty args call will create a key whose value will be an empty JSON object:

           new StringWriter().with { w ->
               def json = new groovy.json.StreamingJsonBuilder(w)
               json.person()

               assert w.toString() == '{"person":{}}'
           }

      Parameters:
        `name` - the single key
        `args` - the value associated with the key