== JSON
:toc: left

Unlike some other languages, Java does not have first class support for http://json.org/[JSON] so we provide
two classes to make handling JSON in your Vert.x applications a bit easier.

=== 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 JSON representation as follows:

[source,java]
----
String jsonString = "{\"foo\":\"bar\"}";
JsonObject object = new JsonObject(jsonString);
----

You can create a JSON object from a map as follows:

[source,java]
----
Map<String, Object> map = new HashMap<>();
map.put("foo", "bar");
map.put("xyz", 3);
JsonObject object = new JsonObject(map);
----

==== Putting entries into a JSON object

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

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

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

==== Getting values from a JSON object

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

[source,java]
----
String val = jsonObject.getString("some-key");
int intVal = jsonObject.getInteger("some-other-key");
----

==== Mapping between JSON objects and Java objects

You can create a JSON object from the fields of a Java object as follows:

You can instantiate a Java object and populate its fields from a JSON object as follows:

[source,java]
----
request.bodyHandler(buff -> {
  JsonObject jsonObject = buff.toJsonObject();
  User javaObject = jsonObject.mapTo(User.class);
});
----

Note that both of the above mapping directions use Jackson's `ObjectMapper#convertValue()` to perform the
mapping. See the Jackson documentation for information on the impact of field and constructor visibility, caveats
on serialization and deserialization across object references, etc.

However, in the simplest case, both `mapFrom` and `mapTo` should succeed if all fields of the Java class are
public (or have public getters/setters), and if there is a public default constructor (or no defined constructors).

Referenced objects will be transitively serialized/deserialized to/from nested JSON objects as
long as the object graph is acyclic.

==== Encoding a 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.

=== 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 as follows:

[source,java]
----
String jsonString = "[\"foo\",\"bar\"]";
JsonArray array = new JsonArray(jsonString);
----

==== 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.Enum-[add]` methods.

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

==== Getting values from a JSON array

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

[source,java]
----
String val = array.getString(0);
Integer intVal = array.getInteger(1);
Boolean boolVal = array.getBoolean(2);
----

==== Encoding a 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.

==== Creating arbitrary JSON

Creating JSON object and array assumes you are using valid string representation.

When you are unsure of the string validity then you should use instead ``link:../../apidocs/io/vertx/core/json/Json.html#decodeValue-java.lang.String-[Json.decodeValue]``

[source,java]
----
Object object = Json.decodeValue(arbitraryJson);
if (object instanceof JsonObject) {
  // That's a valid json object
} else if (object instanceof JsonArray) {
  // That's a valid json array
} else if (object instanceof String) {
  // That's valid string
} else {
  // etc...
}
----