Package org.eclipse.rap.json

Class JsonObject

java.lang.Object
org.eclipse.rap.json.JsonValue
org.eclipse.rap.json.JsonObject
All Implemented Interfaces:
Serializable, Iterable<JsonObject.Member>
public class JsonObject extends JsonValue implements Iterable<JsonObject.Member>
Represents a JSON object, i.e. an unordered set of name/value pairs, where the names are strings and the values are JSON values.

Members can be added using the add(String, ...) methods which accept instances of JsonValue, strings, primitive numbers, and boolean values. To modify certain values of an object, use the set(String, ...) methods. Please note that the add methods are faster than set as they do not search for existing members. On the other hand, the add methods do not prevent adding multiple members with the same name, as duplicate names are discouraged but not prohibited by JSON.

Members can be accessed by their name using get(String). A list of all names can be obtained from the method names(). This class also supports iterating over the members in document order using an iterator() or an enhanced for loop: 

 for( Member member : jsonObject ) {
   String name = member.getName();
   JsonValue value = member.getValue();
   ...
 }

Even though JSON objects are unordered by definition, instances of this class preserve the order of members to allow processing in document order and to guarantee a predictable output.

Note that this class is not thread-safe. If multiple threads access a JsonObject instance concurrently, while at least one of these threads modifies the contents of this object, access to the instance must be synchronized externally. Failure to do so may lead to an inconsistent state.

This class is not supposed to be extended by clients.

Since:
2.1
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    JsonObject.Member
    Represents a member of a JSON object, i.e.

  • Field Summary

    Fields inherited from class org.eclipse.rap.json.JsonValue

    FALSE, NULL, TRUE

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonObject()
    Creates a new empty JsonObject.
    JsonObject(JsonObject object)
    Creates a new JsonObject, initialized with the contents of the specified JSON object.

  • Method Summary

    Modifier and Type
    Method
    Description
    JsonObject
    add(String name, boolean value)
    Adds a new member at the end of this object, with the specified name and the JSON representation of the specified boolean value.
    JsonObject
    add(String name, double value)
    Adds a new member at the end of this object, with the specified name and the JSON representation of the specified double value.
    JsonObject
    add(String name, float value)
    Adds a new member at the end of this object, with the specified name and the JSON representation of the specified float value.
    JsonObject
    add(String name, int value)
    Adds a new member at the end of this object, with the specified name and the JSON representation of the specified int value.
    JsonObject
    add(String name, long value)
    Adds a new member at the end of this object, with the specified name and the JSON representation of the specified long value.
    JsonObject
    add(String name, String value)
    Adds a new member at the end of this object, with the specified name and the JSON representation of the specified string.
    JsonObject
    add(String name, JsonValue value)
    Adds a new member at the end of this object, with the specified name and the specified JSON value.
    JsonObject
    asObject()
    Returns this JSON value as JsonObject, assuming that this value represents a JSON object.
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one according to the contract specified in Object.equals(Object).
    JsonValue
    get(String name)
    Returns the value of the member with the specified name in this object.
    int
    hashCode()
     
    boolean
    isEmpty()
    Returns true if this object contains no members.
    boolean
    isObject()
    Detects whether this value represents a JSON object.
    Iterator<JsonObject.Member>
    iterator()
    Returns an iterator over the members of this object in document order.
    List<String>
    names()
    Returns a list of the names in this object in document order.
    static JsonObject
    readFrom(Reader reader)
    Reads a JSON object from the given reader.
    static JsonObject
    readFrom(String string)
    Reads a JSON object from the given string.
    JsonObject
    remove(String name)
    Removes a member with the specified name from this object.
    JsonObject
    set(String name, boolean value)
    Sets the value of the member with the specified name to the JSON representation of the specified boolean value.
    JsonObject
    set(String name, double value)
    Sets the value of the member with the specified name to the JSON representation of the specified double value.
    JsonObject
    set(String name, float value)
    Sets the value of the member with the specified name to the JSON representation of the specified float value.
    JsonObject
    set(String name, int value)
    Sets the value of the member with the specified name to the JSON representation of the specified int value.
    JsonObject
    set(String name, long value)
    Sets the value of the member with the specified name to the JSON representation of the specified long value.
    JsonObject
    set(String name, String value)
    Sets the value of the member with the specified name to the JSON representation of the specified string.
    JsonObject
    set(String name, JsonValue value)
    Sets the value of the member with the specified name to the specified JSON value.
    int
    size()
    Returns the number of members (i.e.
    static JsonObject
    unmodifiableObject(JsonObject object)
    Returns an unmodifiable JsonObject for the specified one.
    protected void
    write(org.eclipse.rap.json.JsonWriter writer)
     

    Methods inherited from class org.eclipse.rap.json.JsonValue

    asArray, asBoolean, asDouble, asFloat, asInt, asLong, asString, isArray, isBoolean, isFalse, isNull, isNumber, isString, isTrue, toString, valueOf, valueOf, valueOf, valueOf, valueOf, valueOf, writeTo

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Constructor Details

    • JsonObject

      public JsonObject()
      Creates a new empty JsonObject.

    • JsonObject

      public JsonObject(JsonObject object)
      Creates a new JsonObject, initialized with the contents of the specified JSON object.
      Parameters:
      object - the JSON object to get the initial contents from, must not be null

  • Method Details

    • readFrom

      public static JsonObject readFrom(Reader reader) throws IOException
      Reads a JSON object from the given reader.

      Characters are read in chunks and buffered internally, therefore wrapping an existing reader in an additional BufferedReader does not improve reading performance.

      Parameters:
      reader - the reader to read the JSON object from
      Returns:
      the JSON object that has been read
      Throws:
      IOException - if an I/O error occurs in the reader
      ParseException - if the input is not valid JSON
      UnsupportedOperationException - if the input does not contain a JSON object

    • readFrom

      public static JsonObject readFrom(String string)
      Reads a JSON object from the given string.
      Parameters:
      string - the string that contains the JSON object
      Returns:
      the JSON object that has been read
      Throws:
      ParseException - if the input is not valid JSON
      UnsupportedOperationException - if the input does not contain a JSON object

    • unmodifiableObject

      public static JsonObject unmodifiableObject(JsonObject object)
      Returns an unmodifiable JsonObject for the specified one. This method allows to provide read-only access to a JsonObject.

      The returned JsonObject is backed by the given object and reflect changes that happen to it. Attempts to modify the returned JsonObject result in an UnsupportedOperationException.

      Parameters:
      object - the JsonObject for which an unmodifiable JsonObject is to be returned
      Returns:
      an unmodifiable view of the specified JsonObject

    • add

      public JsonObject add(String name, int value)
      Adds a new member at the end of this object, with the specified name and the JSON representation of the specified int value.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • add

      public JsonObject add(String name, long value)
      Adds a new member at the end of this object, with the specified name and the JSON representation of the specified long value.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining

    • add

      public JsonObject add(String name, float value)
      Adds a new member at the end of this object, with the specified name and the JSON representation of the specified float value.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining

    • add

      public JsonObject add(String name, double value)
      Adds a new member at the end of this object, with the specified name and the JSON representation of the specified double value.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining

    • add

      public JsonObject add(String name, boolean value)
      Adds a new member at the end of this object, with the specified name and the JSON representation of the specified boolean value.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining

    • add

      public JsonObject add(String name, String value)
      Adds a new member at the end of this object, with the specified name and the JSON representation of the specified string.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining

    • add

      public JsonObject add(String name, JsonValue value)
      Adds a new member at the end of this object, with the specified name and the specified JSON value.

      This method does not prevent duplicate names. Adding a member with a name that already exists in the object will add another member with the same name. In order to replace existing members, use the method set(name, value) instead. However, add is much faster than set (because it does not need to search for existing members). Therefore add should be preferred when constructing new objects.

      Parameters:
      name - the name of the member to add
      value - the value of the member to add, must not be null
      Returns:
      the object itself, to enable method chaining

    • set

      public JsonObject set(String name, int value)
      Sets the value of the member with the specified name to the JSON representation of the specified int value. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to replace
      value - the value to set to the member
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • set

      public JsonObject set(String name, long value)
      Sets the value of the member with the specified name to the JSON representation of the specified long value. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to replace
      value - the value to set to the member
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • set

      public JsonObject set(String name, float value)
      Sets the value of the member with the specified name to the JSON representation of the specified float value. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • set

      public JsonObject set(String name, double value)
      Sets the value of the member with the specified name to the JSON representation of the specified double value. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • set

      public JsonObject set(String name, boolean value)
      Sets the value of the member with the specified name to the JSON representation of the specified boolean value. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • set

      public JsonObject set(String name, String value)
      Sets the value of the member with the specified name to the JSON representation of the specified string. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to add
      value - the value of the member to add
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • set

      public JsonObject set(String name, JsonValue value)
      Sets the value of the member with the specified name to the specified JSON value. If this object does not contain a member with this name, a new member is added at the end of the object. If this object contains multiple members with this name, only the last one is changed.

      This method should only be used to modify existing objects. To fill a new object with members, the method add(name, value) should be preferred which is much faster (as it does not need to search for existing members).

      Parameters:
      name - the name of the member to add
      value - the value of the member to add, must not be null
      Returns:
      the object itself, to enable method chaining
      Since:
      2.2

    • remove

      public JsonObject remove(String name)
      Removes a member with the specified name from this object. If this object contains multiple members with the given name, only the last one is removed. If this object does not contain a member with the specified name, the object is not modified.
      Parameters:
      name - the name of the member to remove
      Returns:
      the object itself, to enable method chaining

    • get

      public JsonValue get(String name)
      Returns the value of the member with the specified name in this object. If this object contains multiple members with the given name, this method will return the last one.
      Parameters:
      name - the name of the member whose value is to be returned
      Returns:
      the value of the last member with the specified name, or null if this object does not contain a member with that name

    • size

      public int size()
      Returns the number of members (i.e. name/value pairs) in this object.
      Returns:
      the number of members in this object

    • isEmpty

      public boolean isEmpty()
      Returns true if this object contains no members.
      Returns:
      true if this object contains no members

    • names

      public List<String> names()
      Returns a list of the names in this object in document order. The returned list is backed by this object and will reflect subsequent changes. It cannot be used to modify this object. Attempts to modify the returned list will result in an exception.

    • iterator

      public Iterator<JsonObject.Member> iterator()
      Returns an iterator over the members of this object in document order. The returned iterator cannot be used to modify this object.
      Specified by:
      iterator in interface Iterable<JsonObject.Member>
      Returns:
      an iterator over the members of this object
      Since:
      2.2

    • write

      protected void write(org.eclipse.rap.json.JsonWriter writer) throws IOException
      Specified by:
      write in class JsonValue
      Throws:
      IOException

    • isObject

      public boolean isObject()
      Description copied from class: JsonValue
      Detects whether this value represents a JSON object. If this is the case, this value is an instance of JsonObject.
      Overrides:
      isObject in class JsonValue
      Returns:
      true if this value is an instance of JsonObject

    • asObject

      public JsonObject asObject()
      Description copied from class: JsonValue
      Returns this JSON value as JsonObject, assuming that this value represents a JSON object. If this is not the case, an exception is thrown.
      Overrides:
      asObject in class JsonValue
      Returns:
      a JSONObject for this value

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class JsonValue

    • equals

      public boolean equals(Object obj)
      Description copied from class: JsonValue
      Indicates whether some other object is "equal to" this one according to the contract specified in Object.equals(Object).

      Two JsonValues are considered equal if and only if they represent the same JSON text. As a consequence, two given JsonObjects may be different even though they contain the same set of names with the same values, but in a different order.

      Overrides:
      equals in class JsonValue
      Parameters:
      obj - the reference object with which to compare
      Returns:
      true if this object is the same as the object argument; false otherwise