Package org.eclipse.ditto.json

Interface JsonObject

All Superinterfaces:
Iterable<JsonField>, JsonValue, JsonValueContainer<JsonField>
public interface JsonObject extends JsonValue, JsonValueContainer<JsonField>
Represents a JSON object. A JSON object is a set of key-value-pairs with unique keys.

Implementations of this interface are required to be immutable!

  • Method Details

    • of

      static JsonObject of(String jsonObjectString)
      Creates a JsonObject from the given string.
      Parameters:
      jsonObjectString - the string that represents the JSON object.
      Returns:
      the JSON object that has been created from the string.
      Throws:
      NullPointerException - if jsonObjectString is null.
      IllegalArgumentException - if jsonObjectString is empty.
      JsonParseException - if jsonObjectString does not represent a valid JSON object.
      See Also:

    • of

      static JsonObject of(byte[] jsonData)
      Creates a JsonObject from the given byte array.
      Parameters:
      jsonData - the byte array that represents the JSON object.
      Returns:
      the JSON object that has been created from the data.
      Throws:
      NullPointerException - if jsonData is null.
      IllegalArgumentException - if jsonData is empty.
      JsonParseException - if jsonData does not represent a valid JSON object.
      Since:
      1.5.0

    • newBuilder

      static JsonObjectBuilder newBuilder()
      Returns a new mutable builder with a fluent API for a JsonObject.
      Returns:
      the builder.

    • empty

      static JsonObject empty()
      Returns an empty instance of JsonObject.
      Returns:
      the instance.

    • toBuilder

      default JsonObjectBuilder toBuilder()
      Returns a new mutable builder with a fluent API for a JsonObject. The returned builder is already initialised with the data of the this JSON object. This method is useful if an existing JSON object should be strongly modified but the amount of creating objects should be kept low at the same time.
      Returns:
      the builder which is initialised with the data of this JSON object instance.

    • setValue

      JsonObject setValue(CharSequence key, int value)
      Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specified int value to the new object. If this object previously contained a field with the same key, the old field is replaced by the new field in the new object.
      Parameters:
      key - the JSON key or JSON pointer of the field to be set.
      value - the value of the field to be set.
      Returns:
      a new JSON object with an association between key and value or this instance if it already contains a field with key and value.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty or if key is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.
      JsonKeyInvalidException - if the JSON key was not valid.

    • setValue

      JsonObject setValue(CharSequence key, long value)
      Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specified long value to the new object. If this object previously contained a field with the same key, the old field is replaced by the new field in the new object.
      Parameters:
      key - the JSON key or JSON pointer of the field to be set.
      value - the value of the field to be set.
      Returns:
      a new JSON object with an association between key and value or this instance if it already contains a field with key and value.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty or if key is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.
      JsonKeyInvalidException - if the JSON key was not valid.

    • setValue

      JsonObject setValue(CharSequence key, double value)
      Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specified double value to the new object. If this object previously contained a field with the same key, the old field is replaced by the new field in the new object.
      Parameters:
      key - the JSON key or JSON pointer of the field to be set.
      value - the value of the field to be set.
      Returns:
      a new JSON object with an association between key and value or this instance if it already contains a field with key and value.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty or if key is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.
      JsonKeyInvalidException - if the JSON key was not valid.

    • setValue

      JsonObject setValue(CharSequence key, boolean value)
      Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specified boolean value to the new object. If this object previously contained a field with the same key, the old field is replaced by the new field in the new object.
      Parameters:
      key - the JSON key or JSON pointer of the field to be set.
      value - the value of the field to be set.
      Returns:
      a new JSON object with an association between key and value.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty or if key is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.
      JsonKeyInvalidException - if the JSON key was not valid.

    • setValue

      JsonObject setValue(CharSequence key, String value)
      Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specified String value to the new object. If this object previously contained a field with the same key, the old field is replaced by the new field in the new object.
      Parameters:
      key - the JSON key or JSON pointer of the field to be set.
      value - the value of the field to be set.
      Returns:
      a new JSON object with an association between key and value.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty or if key is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.
      JsonKeyInvalidException - if the JSON key was not valid.

    • setValue

      JsonObject setValue(CharSequence key, JsonValue value)
      Creates a new JSON object by setting a new JSON field with the specified key and the specified JSON value to the new object. If this object previously contained a field with the same key, the old field is replaced by the new field in the new object.
      Parameters:
      key - the JSON key or JSON pointer of the field to be set.
      value - the value of the field to be set.
      Returns:
      a new JSON object with an association between key and value.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty or if key is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.
      JsonKeyInvalidException - if the JSON key was not valid.

    • set

      <T> JsonObject set(JsonFieldDefinition<T> fieldDefinition, @Nullable T value)
      Sets the specified value to a field which is defined by the pointer of the given field definition on a copy of this object.
      Type Parameters:
      T - the type of value.
      Parameters:
      fieldDefinition - the definition of the JSON field containing the value, i. e. the field with JsonPointer.getLeaf() as key and value as value.
      value - the value to be set.
      Returns:
      a copy of this object with the value set at the pointer defined location.
      Throws:
      NullPointerException - if fieldDefinition is null.
      IllegalArgumentException - if the pointer of fieldDefinition is empty.
      JsonKeyInvalidException - if the JSON key in the passed fieldDefinition was not valid.

    • set

      JsonObject set(JsonField field)
      Sets the specified field to a copy of this object. A previous field with the same key is replaced.
      Parameters:
      field - the field to be set.
      Returns:
      a copy of this object with the field set.
      Throws:
      NullPointerException - if field is null.
      JsonKeyInvalidException - if the JSON key in the passed jsonField was not valid.

    • setAll

      JsonObject setAll(Iterable<JsonField> jsonFields)
      Creates a new JSON object by setting the given JSON fields to this object. All previous fields with the same key are replaced.
      Parameters:
      jsonFields - the fields to set.
      Returns:
      a new JSON object extended by the specified fields.
      Throws:
      NullPointerException - if jsonFields is null.
      JsonKeyInvalidException - if a JSON key in the passed jsonFields was not valid.

    • contains

      boolean contains(CharSequence key)
      Indicates whether this JSON object contains a field at the key defined location.
      Parameters:
      key - the JSON key or JSON pointer to be looked up.
      Returns:
      true if this JSON object contains a field at key, false else.
      Throws:
      NullPointerException - if key is null.

    • get

      JsonObject get(JsonPointer pointer)
      Returns a new JSON object containing the whole object hierarchy of the value which is defined by the given pointer. If, for example, on the following JSON object 
          {
       "thingId": "myThing",
       "attributes": {
          "someAttr": {
             "subsel": 42
          },
          "anotherAttr": "baz"
       }
    }

      this method with the pointer "attributes/someAttr/subsel" is called the returned JSON object is 

          {
       "attributes": {
          "someAttr": {
             "subsel": 42
          }
       }
    }
      Parameters:
      pointer - defines which value to get.
      Returns:
      this object if the pointer is empty, a new hierarchical JSON object containing the pointer-defined value or an empty object if the pointer refers to a non-existing value.
      Throws:
      NullPointerException - if pointer is null.

    • get

      JsonObject get(JsonFieldDefinition<?> fieldDefinition)
      This is a convenience method which does the same as get(JsonPointer). The pointer is obtained from the specified field definition.
      Parameters:
      fieldDefinition - supplies the JSON pointer to be used.
      Returns:
      a new hierarchical JSON object containing the pointer-defined value or an empty object if the pointer refers to a non-existing value.
      Throws:
      NullPointerException - if fieldDefinition is null.
      See Also:

    • get

      JsonObject get(JsonFieldSelector fieldSelector)
      Returns a new JSON object which is composed from parts of this object. The parts to use are defined by the given JsonFieldSelector. The order of the fields defined in the field selector is maintained in the result. For example, if on the following JSON object 
          {
       "thingId": "0x1337",
       "foo": {
          "bar": {
             "baz": 23,
             "oogle": "boogle"
          },
          "yo": 10
       },
       "isOn": false
    }

      this method is called with the field selector "foo(bar/baz,yo),thingId" the returned JSON object is 

          {
    "foo": {
       "bar": {
          "baz": 23
       },
       "yo": 10
    },
    "thingId": "0x1337"
    }
      This also works with arbitrarily nested levels.
      Parameters:
      fieldSelector - the JSON field selector which defines what the returned object should contain.
      Returns:
      if the field selector is empty or contains only pointers to non-existing values an empty JSON object; otherwise a new JSON object containing the field selector-defined parts of this object.
      Throws:
      NullPointerException - if field selector is null.

    • getValue

      Optional<JsonValue> getValue(CharSequence key)
      Returns the value which is associated with the specified key. This method is similar to get(JsonPointer) however it does not maintain any hierarchy but returns simply the value. If, for example, on the following JSON object 
          {
       "thingId": "myThing",
       "attributes": {
          "someAttr": {
             "subsel": 42
          },
          "anotherAttr": "baz"
       }
    }
      this method is called with key "attributes/someAttr/subsel" an empty Optional is returned. Is the key "thingId" used instead the returned Optional would contain "myThing". If the specified key is empty or "/" this object reference is returned within the result.
      Parameters:
      key - defines which value to get.
      Returns:
      the JSON value at the key-defined location within this object.
      Throws:
      NullPointerException - if key is null.

    • getValue

      <T> Optional<T> getValue(JsonFieldDefinition<T> fieldDefinition)
      Returns the plain Java typed value of the field whose location is defined by the JsonPointer of the specified JsonFieldDefinition. The expected Java type is the value type of the JsonFieldDefinition. If this JsonObject does not contain a value at the defined location an empty Optional is returned.
      Type Parameters:
      T - the expected type of the result.
      Parameters:
      fieldDefinition - supplies the JsonPointer to and expected value type of the desired result value.
      Returns:
      the JSON value at the defined location within this object or an empty Optional if this JsonObject did not contain a field at the location.
      Throws:
      NullPointerException - if fieldDefinition is null.
      JsonParseException - if this JsonObject contained a value at the defined location with an unexpected type.

    • getValueOrThrow

      <T> T getValueOrThrow(JsonFieldDefinition<T> fieldDefinition)
      Returns the plain Java typed value of the field whose location is defined by the JsonPointer of the specified JsonFieldDefinition. The expected Java type is the value type of the JsonFieldDefinition. If this JsonObject does not contain a value at the defined location a JsonMissingFieldException is thrown.
      Type Parameters:
      T - the expected type of the result.
      Parameters:
      fieldDefinition - supplies the JsonPointer to and expected value type of the desired result value.
      Returns:
      the JSON value at the defined location within this object.
      Throws:
      NullPointerException - if fieldDefinition is null.
      JsonMissingFieldException - if this JsonObject did not contain a value at all at the defined location.
      JsonParseException - if this JsonObject contained a value at the defined location with a type which is different from T.

    • remove

      JsonObject remove(CharSequence key)
      Removes the JSON field to which the given pointer points to. The pointer's leaf is the key of the field to be removed. For example, if on the following JSON object 
          {
       "someObjectAttribute": {
          "someKey": {
             "someNestedKey": 42
          }
       }
    }
      this method is called with the pointer "/someObjectAttribute/someKey/someNestedKey" the returned object is 
          {
       "someObjectAttribute": {
          "someKey": {}
       }
    }
      Parameters:
      key - the key or JSON pointer which denotes the field to be removed.
      Returns:
      a new JSON object without the JSON field which is defined by the pointer.
      Throws:
      NullPointerException - if key is null.

    • getKeys

      List<JsonKey> getKeys()
      Returns a list of the keys in this JSON object in document order. The returned list cannot be used to modify this JSON object.
      Returns:
      an unmodifiable list of the keys in this JSON object;

    • getField

      Optional<JsonField> getField(CharSequence key)
      Returns the JsonField which contains both JsonKey and JsonValue for the passed key.
      Parameters:
      key - the JSON key or JSON pointer which denotes the field to be get.
      Returns:
      the JSON field containing key and value.
      Throws:
      NullPointerException - if index is null.

    • filter

      default JsonObject filter(Predicate<JsonField> predicate)
      Filters the json fields of this object and all nested objects based on the given predicate.
      Parameters:
      predicate - The predicate that all fields should pass.
      Returns:
      the filtered JSON object.
      Since:
      2.4.0