== JSON

To manipulate JSON object, Vert.x proposes its own implementation of `link:../../apidocs/io/vertx/core/json/JsonObject.html[JsonObject]` and
`link:../../apidocs/io/vertx/core/json/JsonArray.html[JsonArray]`. This is because, unlike some other languages, Java does not have first class
support for http://json.org/[JSON].

When developping a vert.x application with Groovy, you can rely on these two classes, or use the
(http://www.groovy-lang.org/json.html)[JSON support from Groovy]. This section explains how to use the Vert.x
classes.

NOTE: Most vert.x methods taking a JSON object as argument in their Java version, take a map instead.


=== JSON objects

The `link:../../apidocs/io/vertx/core/json/JsonObject.html[JsonObject]` class represents JSON objects.

A JSON object is basically just a map which has string keys and values can be of one of the JSON supported types
(string, number, boolean).

JSON objects also support `null` values.

==== Creating JSON objects

Empty JSON objects can be created with the default constructor.

You can create a JSON object from a string or g-string JSON representation as follows:

[source,groovy]
----
def object = new JsonObject("{\"foo\":\"bar\"}")
def object2 = new JsonObject("""
{
"foo": "bar"
}
""")
----

In Groovy it's also convenient to create a JSON object from a map:

[source, groovy]
----
def map = [ "foo" : "bar" ]
def json = new JsonObject(map)
----

Nested maps are transformed to nested JSON objects.

It can be achieved using a Groovy cast as well:

[source, groovy]
----
def map = [ "foo" : "bar" ]
def json = map as JsonObject
----

==== Putting entries into a JSON object

Use the `link:../../apidocs/io/vertx/core/json/JsonObject.html#put-java.lang.String-java.lang.Object-[put]` methods to put values into the JSON object.

The method invocations can be chained because of the fluent API:

[source,groovy]
----
def object = new JsonObject()
object.put("foo", "bar").put("num", 123).put("mybool", true)
----

The Groovy subscript operator works too:

[source,groovy]
----
def object = new JsonObject()
object["foo"] = "bar"
object["num"] = 123
object["mybool"] = true
----

==== Getting values from a JSON object

You get values from a JSON object using the `getXXX` methods, for example:

[source,java]
----
dev val1 = jsonObject.getString("some-key")
def val2 = jsonObject.getInteger("some-other-key")
----

The Groovy subscript operator works too:

[source,groovy]
----
dev val1 = jsonObject["some-key"]
def val2 = jsonObject["some-other-key"]
----

==== Encoding the JSON object to a String

You use `link:../../apidocs/io/vertx/core/json/JsonObject.html#encode--[encode]` to encode the object to a String form. There is also a
`link:../../apidocs/io/vertx/core/json/JsonObject.html#encodePrettily--[encodePrettily]` that makes the output pretty (understand multi-line and
indented).

=== JSON arrays

The `link:../../apidocs/io/vertx/core/json/JsonArray.html[JsonArray]` class represents JSON arrays.

A JSON array is a sequence of values (string, number, boolean).

JSON arrays can also contain `null` values.

==== Creating JSON arrays

Empty JSON arrays can be created with the default constructor.

You can create a JSON array from a string JSON representation or a list as follows:

[source,groovy]
----
def object = new JsonArray("[\"foo\", \"bar\"]")
def object2 = new JsonObject("""
[
"foo", "bar"
]
""")
----

In Groovy it's also convenient to create a JSON array from a list:

[source, groovy]
----
def list = [ "foo", "bar" ]
def json = new JsonArray(list)
----

Nested maps are transformed to nested JSON objects.

It can be achieved using a Groovy cast as well:

[source, groovy]
----
def list = [ "foo", "bar" ]
def json = map as JsonArray
----

==== Adding entries into a JSON array

You add entries to a JSON array using the `link:../../apidocs/io/vertx/core/json/JsonArray.html#add-java.lang.Object-[add]` methods.

[source,groovy]
----
def array = new JsonArray()
array.add("foo").add(123).add(false)
----

The left shift operator can be used as well:

[source,groovy]
----
def array = new JsonArray()
array << "foo"
array << 123
array << false
----

==== Getting values from a JSON array

You get values from a JSON array using the `getXXX` methods, for example:

[source,groovy]
----
def val = array.getString(0)
def intVal = array.getInteger(1)
def boolVal = array.getBoolean(2)
----

The Groovy subscript operator works too:

[source,groovy]
----
def val = array[0]
def intVal = array[1]
def boolVal = array[2]
----

==== Encoding the JSON array to a String

You use `link:../../apidocs/io/vertx/core/json/JsonArray.html#encode--[encode]` to encode the array to a String form. There is also a
`link:../../apidocs/io/vertx/core/json/JsonObject.html#encodePrettily--[encodePrettily]` that makes the output pretty (understand multi-line and
indented).