javax.json

## Interface JsonObject

- All Superinterfaces:
    JsonStructure, JsonValue, Map<String,JsonValue>

      public interface JsonObject
      extends JsonStructure, Map<String,JsonValue>

  `JsonObject` class represents an immutable JSON object value (an unordered collection of zero or more name/value pairs). It also provides unmodifiable map view to the JSON object name/value mappings.

  A JsonObject instance can be created from an input source using `JsonReader.readObject()`. For example:

       JsonReader jsonReader = Json.createReader(...);
       JsonObject object = jsonReader.readObject();
       jsonReader.close();

  It can also be built from scratch using a `JsonObjectBuilder`.

  For example 1: An empty JSON object can be built as follows:

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

  For example 2: The following JSON

       {
           "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" }
           ]
       }

  can be built using :

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

  `JsonObject` can be written to JSON as follows:

       JsonWriter writer = ...
       JsonObject obj = ...;
       writer.writeObject(obj);

  `JsonObject` values can be `JsonObject`, `JsonArray`, `JsonString`, `JsonNumber`, `JsonValue.TRUE`, `JsonValue.FALSE`, `JsonValue.NULL`. These values can be accessed using various accessor methods.

  In the above example 2, "John" can be got using

       String firstName = object.getString("firstName");

  This map object provides read-only access to the JSON object data, and attempts to modify the map, whether direct or via its collection views, result in an `UnsupportedOperationException`.

  The map object's iteration ordering is based on the order in which name/value pairs are added to the corresponding builder or the order in which name/value pairs appear in the corresponding stream.

  Author:
    Jitendra Kotamraju

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface javax.json.JsonValue

      `JsonValue.ValueType`

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `Map.Entry<K,V>`

  - ### Field Summary

    - ### Fields inherited from interface javax.json.JsonValue

      `FALSE, NULL, TRUE`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `getBoolean(String name)` Returns the boolean value of the associated mapping for the specified name.
    `boolean` | `getBoolean(String name, boolean defaultValue)` Returns the boolean value of the associated mapping for the specified name.
    `int` | `getInt(String name)` A convenience method for `getJsonNumber(name).intValue()`
    `int` | `getInt(String name, int defaultValue)` Returns the int value of the associated `JsonNumber` mapping for the specified name.
    `JsonArray` | `getJsonArray(String name)` Returns the array value to which the specified name is mapped.
    `JsonNumber` | `getJsonNumber(String name)` Returns the number value to which the specified name is mapped.
    `JsonObject` | `getJsonObject(String name)` Returns the object value to which the specified name is mapped.
    `JsonString` | `getJsonString(String name)` Returns the string value to which the specified name is mapped.
    `String` | `getString(String name)` A convenience method for `getJsonString(name).getString()`
    `String` | `getString(String name, String defaultValue)` Returns the string value of the associated `JsonString` mapping for the specified name.
    `boolean` | `isNull(String name)` Returns `true` if the associated value for the specified name is `JsonValue.NULL`.

    - ### Methods inherited from interface javax.json.JsonValue

      `getValueType, toString`

    - ### Methods inherited from interface java.util.Map

      `clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values`

- - ### Method Detail

    - #### getJsonArray

          JsonArray getJsonArray(String name)

      Returns the array value to which the specified name is mapped. This is a convenience method for `(JsonArray)get(name)` to get the value.
      Parameters:
        `name` - the name whose associated value is to be returned
      Returns:
        the array value to which the specified name is mapped, or `null` if this object contains no mapping for the name
      Throws:
        `ClassCastException` - if the value to which the specified name is mapped is not assignable to JsonArray type

    - #### getJsonObject

          JsonObject getJsonObject(String name)

      Returns the object value to which the specified name is mapped. This is a convenience method for `(JsonObject)get(name)` to get the value.
      Parameters:
        `name` - the name whose associated value is to be returned
      Returns:
        the object value to which the specified name is mapped, or `null` if this object contains no mapping for the name
      Throws:
        `ClassCastException` - if the value to which the specified name is mapped is not assignable to JsonObject type

    - #### getJsonNumber

          JsonNumber getJsonNumber(String name)

      Returns the number value to which the specified name is mapped. This is a convenience method for `(JsonNumber)get(name)` to get the value.
      Parameters:
        `name` - the name whose associated value is to be returned
      Returns:
        the number value to which the specified name is mapped, or `null` if this object contains no mapping for the name
      Throws:
        `ClassCastException` - if the value to which the specified name is mapped is not assignable to JsonNumber type

    - #### getJsonString

          JsonString getJsonString(String name)

      Returns the string value to which the specified name is mapped. This is a convenience method for `(JsonString)get(name)` to get the value.
      Parameters:
        `name` - the name whose associated value is to be returned
      Returns:
        the string value to which the specified name is mapped, or `null` if this object contains no mapping for the name
      Throws:
        `ClassCastException` - if the value to which the specified name is mapped is not assignable to JsonString type

    - #### getString

          String getString(String name)

      A convenience method for `getJsonString(name).getString()`
      Parameters:
        `name` - whose associated value is to be returned as String
      Returns:
        the String value to which the specified name is mapped
      Throws:
        `NullPointerException` - if the specified name doesn't have any mapping
        `ClassCastException` - if the value for specified name mapping is not assignable to JsonString

    - #### getString

          String getString(String name,
                         String defaultValue)

      Returns the string value of the associated `JsonString` mapping for the specified name. If `JsonString` is found, then its `JsonString.getString()` is returned. Otherwise, the specified default value is returned.
      Parameters:
        `name` - whose associated value is to be returned as String
        `defaultValue` - a default value to be returned
      Returns:
        the string value of the associated mapping for the name, or the default value

    - #### getInt

          int getInt(String name)

      A convenience method for `getJsonNumber(name).intValue()`
      Parameters:
        `name` - whose associated value is to be returned as int
      Returns:
        the int value to which the specified name is mapped
      Throws:
        `NullPointerException` - if the specified name doesn't have any mapping
        `ClassCastException` - if the value for specified name mapping is not assignable to JsonNumber

    - #### getInt

          int getInt(String name,
                   int defaultValue)

      Returns the int value of the associated `JsonNumber` mapping for the specified name. If `JsonNumber` is found, then its `JsonNumber.intValue()` is returned. Otherwise, the specified default value is returned.
      Parameters:
        `name` - whose associated value is to be returned as int
        `defaultValue` - a default value to be returned
      Returns:
        the int value of the associated mapping for the name, or the default value

    - #### getBoolean

          boolean getBoolean(String name)

      Returns the boolean value of the associated mapping for the specified name. If the associated mapping is JsonValue.TRUE, then returns true. If the associated mapping is JsonValue.FALSE, then returns false.
      Parameters:
        `name` - whose associated value is to be returned as boolean
      Returns:
        the boolean value to which the specified name is mapped
      Throws:
        `NullPointerException` - if the specified name doesn't have any mapping
        `ClassCastException` - if the value for specified name mapping is not assignable to JsonValue.TRUE or JsonValue.FALSE

    - #### getBoolean

          boolean getBoolean(String name,
                           boolean defaultValue)

      Returns the boolean value of the associated mapping for the specified name. If the associated mapping is JsonValue.TRUE, then returns true. If the associated mapping is JsonValue.FALSE, then returns false. Otherwise, the specified default value is returned.
      Parameters:
        `name` - whose associated value is to be returned as int
        `defaultValue` - a default value to be returned
      Returns:
        the boolean value of the associated mapping for the name, or the default value

    - #### isNull

          boolean isNull(String name)

      Returns `true` if the associated value for the specified name is `JsonValue.NULL`.
      Parameters:
        `name` - name whose associated value is checked
      Returns:
        return true if the associated value is `JsonValue.NUL`, otherwise false
      Throws:
        `NullPointerException` - if the specified name doesn't have any mapping

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.