Java Platform, Enterprise Edition (Java EE) 8 The Java EE Tutorial

## Overview of the JSON Binding API

This section provides basic instructions for using the JSON-B client API. The instructions provide a basis for understanding the jsonbbasics Example Application. Refer to the JSON-B project page for API documentation and a more detailed User Guide.

The following topics are addressed here:

- Creating a jasonb Instance

- Using the Default Mapping

- Using Customizations

- Using Annotations

### Creating a jasonb Instance

A `jsonb` instance provides access to methods for binding objects to JSON. A single `jsonb` instance is required for most applications. A `jsonb` instance is created using the `JsonbBuilder` interface, which is a client’s entry point to the JSON Binding API. For example:

    Jsonb jsonb = JsonbBuilder.create();

### Using the Default Mapping

JSON-B provides default mappings for serializing and deserializing basic Java and Java SE types as well Java date and time classes. To use the default mappings and mapping behavior, create a josnb instance and use the `toJson` method to serialize to JSON and the `fromJson` method to deserialize back to an object. The following example binds a simple `Person` object that contains a single `name` field.

    Jsonb jsonb = JsonbBuilder.create();

    Person person = new Person();
    person.name = "Fred";

    Jsonb jsonb = JsonbBuilder.create();

    // serialize to JSON
    String result = jsonb.toJson(person);

    // deserialize from JSON
    person = jsonb.fromJson("{name:\"joe"\"}", Person.class);

### Using Customizations

JSON-B supports many ways to customize the default mapping behavior. For runtime customizations, a `JsonbConfig` configuration object is used when creating the `jsonbinstance`. The `JsonbConfig` class supports many configuration options and also includes advanced options for binding custom types. For advanced options, see the `JsonbAdapter` interface and the `JsonbSerializer` and `JsonbDeserializer` interfaces.

The following example creates a configuration object that sets the `FORMATTING` property to specify whether or not the serialized JSON data is formatted with linefeeds and indentation.

    JsonbConfig config = new JsonbConfig()
        .withFormatting(true);

    Jsonb jsonb = JsonbBuilder.create(config);

### Using Annotations

JSON-B includes many annotations that can be used at compile time to customize the default mapping behavior. The following example uses the `@JsonbProperty` annotation to change the `name` field to `person-name` when the object is serialized to JSON.

    public class Person {
        @JsonbProperty("person-name")
        private String name;
    }

The resulting JSON document is written as:

    {
        "person-name": "Fred",
    }

Copyright © 2017, Oracle and/or its affiliates. All rights reserved.