javax.json

Interface JsonObjectBuilder

public interface JsonObjectBuilder

A builder for creating JsonObject models from scratch. This interface initializes an empty JSON object model and provides methods to add name/value pairs to the object model and to return the resulting object. The methods in this class can be chained to add multiple name/value pairs to the object.

The class Json contains methods to create the builder object. The example code below shows how to build an empty JsonObject instance.

 
 JsonObject object = Json.createObjectBuilder().build();
 
 

The class JsonBuilderFactory also contains methods to create JsonObjectBuilder instances. A factory instance can be used to create multiple builder instances with the same configuration. This the preferred way to create multiple instances. The example code below shows how to build a JsonObject model that represents the following JSON object:

 
 {
     "firstName": "John", "lastName": "Smith", "age": 25,
     "address" : {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021"
     },
     "phoneNumber": [
         { "type": "home", "number": "212 555-1234" },
         { "type": "fax", "number": "646 555-4567" }
     ]
 }
 
 

The code to create the object shown above is the following:

 
 JsonBuilderFactory factory = Json.createBuilderFactory(config);
 JsonObject value = factory.createObjectBuilder()
     .add("firstName", "John")
     .add("lastName", "Smith")
     .add("age", 25)
     .add("address", factory.createObjectBuilder()
         .add("streetAddress", "21 2nd Street")
         .add("city", "New York")
         .add("state", "NY")
         .add("postalCode", "10021"))
     .add("phoneNumber", factory.createArrayBuilder()
         .add(factory.createObjectBuilder()
             .add("type", "home")
             .add("number", "212 555-1234"))
         .add(factory.createObjectBuilder()
             .add("type", "fax")
             .add("number", "646 555-4567")))
     .build();
 
 

This class does not allow null to be used as a name or value while building the JSON object

See Also:

JsonArrayBuilder

Method Summary

Modifier and Type	Method and Description
JsonObjectBuilder	add(String name, BigDecimal value) Adds a name/JsonNumber pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, BigInteger value) Adds a name/JsonNumber pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, boolean value) Adds a name/JsonValue#TRUE or name/JsonValue#FALSE pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, double value) Adds a name/JsonNumber pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, int value) Adds a name/JsonNumber pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, JsonArrayBuilder builder) Adds a name/JsonArray pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, JsonObjectBuilder builder) Adds a name/JsonObject pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, JsonValue value) Adds a name/JsonValue pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, long value) Adds a name/JsonNumber pair to the JSON object associated with this object builder.
JsonObjectBuilder	add(String name, String value) Adds a name/JsonString pair to the JSON object associated with this object builder.
default JsonObjectBuilder	addAll(JsonObjectBuilder builder) Adds all name/value pairs in the JSON object associated with the specified object builder to the JSON object associated with this object builder.
JsonObjectBuilder	addNull(String name) Adds a name/JsonValue#NULL pair to the JSON object associated with this object builder where the value is null.
JsonObject	build() Returns the JSON object associated with this object builder.
default JsonObjectBuilder	remove(String name) Remove the name/value pair from the JSON object associated with this object builder if it is present.

Method Detail

add

JsonObjectBuilder add(String name,
                      JsonValue value)

Adds a name/JsonValue pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name or value is null

add

JsonObjectBuilder add(String name,
                      String value)

Adds a name/JsonString pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name or value is null

add

JsonObjectBuilder add(String name,
                      BigInteger value)

Adds a name/JsonNumber pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name or value is null

See Also:

JsonNumber

add

JsonObjectBuilder add(String name,
                      BigDecimal value)

Adds a name/JsonNumber pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name or value is null

See Also:

JsonNumber

add

JsonObjectBuilder add(String name,
                      int value)

Adds a name/JsonNumber pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name is null

See Also:

JsonNumber

add

JsonObjectBuilder add(String name,
                      long value)

Adds a name/JsonNumber pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name is null

See Also:

JsonNumber

add

JsonObjectBuilder add(String name,
                      double value)

Adds a name/JsonNumber pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NumberFormatException - if the value is Not-a-Number (NaN) or infinity

NullPointerException - if the specified name is null

See Also:

JsonNumber

add

JsonObjectBuilder add(String name,
                      boolean value)

Adds a name/JsonValue#TRUE or name/JsonValue#FALSE pair to the JSON object associated with this object builder. If the object contains a mapping for the specified name, this method replaces the old value with the specified value.

Parameters:

name - name in the name/value pair

value - value in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name is null

addNull

JsonObjectBuilder addNull(String name)

Adds a name/JsonValue#NULL pair to the JSON object associated with this object builder where the value is null. If the object contains a mapping for the specified name, this method replaces the old value with null.

Parameters:

name - name in the name/value pair

Returns:

this object builder

Throws:

NullPointerException - if the specified name is null

add

JsonObjectBuilder add(String name,
                      JsonObjectBuilder builder)

Adds a name/JsonObject pair to the JSON object associated with this object builder. The value JsonObject is built from the specified object builder. If the object contains a mapping for the specified name, this method replaces the old value with the JsonObject from the specified object builder.

Parameters:

name - name in the name/value pair

builder - the value is the object associated with this builder

Returns:

this object builder

Throws:

NullPointerException - if the specified name or builder is null

add

JsonObjectBuilder add(String name,
                      JsonArrayBuilder builder)

Adds a name/JsonArray pair to the JSON object associated with this object builder. The value JsonArray is built from the specified array builder. If the object contains a mapping for the specified name, this method replaces the old value with the JsonArray from the specified array builder.

Parameters:

name - the name in the name/value pair

builder - the value is the object array with this builder

Returns:

this object builder

Throws:

NullPointerException - if the specified name or builder is null

addAll

default JsonObjectBuilder addAll(JsonObjectBuilder builder)

Adds all name/value pairs in the JSON object associated with the specified object builder to the JSON object associated with this object builder. The newly added name/value pair will replace any existing name/value pair with the same name.

Parameters:

builder - the specified object builder

Returns:

this object builder

Throws:

NullPointerException - if the specified builder is null

Since:

1.1

remove

default JsonObjectBuilder remove(String name)

Remove the name/value pair from the JSON object associated with this object builder if it is present.

Parameters:

name - the name in the name/value pair to be removed

Returns:

this object builder

Throws:

NullPointerException - if the specified name is null

Since:

1.1

build

JsonObject build()

Returns the JSON object associated with this object builder. The iteration order for the JsonObject is based on the order in which name/value pairs are added to the object using this builder.

Returns:

JSON object that is being built