Package org.eclipse.ditto.json
Interface JsonObject
- All Superinterfaces:
Iterable<JsonField>
,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 Summary
Modifier and TypeMethodDescriptionboolean
contains
(CharSequence key) Indicates whether this JSON object contains a field at the key defined location.static JsonObject
empty()
Returns an empty instance ofJsonObject
.default JsonObject
Filters thejson fields
of this object and all nested objects based on the given predicate.get
(JsonFieldDefinition<?> fieldDefinition) This is a convenience method which does the same asget(JsonPointer)
.get
(JsonFieldSelector fieldSelector) Returns a new JSON object which is composed from parts of this object.get
(JsonPointer pointer) Returns a new JSON object containing the whole object hierarchy of the value which is defined by the given pointer.getField
(CharSequence key) Returns the JsonField which contains both JsonKey and JsonValue for the passed key.getKeys()
Returns a list of the keys in this JSON object in document order.getValue
(CharSequence key) Returns the value which is associated with the specified key.<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.<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.static JsonObjectBuilder
Returns a new mutable builder with a fluent API for aJsonObject
.static JsonObject
of
(byte[] jsonData) Creates aJsonObject
from the given byte array.static JsonObject
Creates aJsonObject
from the given string.remove
(CharSequence key) Removes the JSON field to which the given pointer points to.Sets the specified field to a copy of this object.<T> JsonObject
set
(JsonFieldDefinition<T> fieldDefinition, 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.Creates a new JSON object by setting the given JSON fields to this object.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 specifiedboolean
value to the new object.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 specifieddouble
value to the new object.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 specifiedint
value to the new object.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 specifiedlong
value to the new object.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 specifiedString
value to the new object.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.default JsonObjectBuilder
Returns a new mutable builder with a fluent API for aJsonObject
.Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
Methods inherited from interface org.eclipse.ditto.json.JsonValue
asArray, asBoolean, asDouble, asInt, asLong, asObject, asString, formatAsString, getUpperBoundForStringSize, isArray, isBoolean, isDouble, isInt, isLong, isNull, isNumber, isObject, isString, toString, writeValue
Methods inherited from interface org.eclipse.ditto.json.JsonValueContainer
getSize, isEmpty, stream
-
Method Details
-
of
Creates aJsonObject
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
- ifjsonObjectString
isnull
.IllegalArgumentException
- ifjsonObjectString
is empty.JsonParseException
- ifjsonObjectString
does not represent a valid JSON object.- See Also:
-
of
Creates aJsonObject
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
- ifjsonData
isnull
.IllegalArgumentException
- ifjsonData
is empty.JsonParseException
- ifjsonData
does not represent a valid JSON object.- Since:
- 1.5.0
-
newBuilder
Returns a new mutable builder with a fluent API for aJsonObject
.- Returns:
- the builder.
-
empty
Returns an empty instance ofJsonObject
.- Returns:
- the instance.
-
toBuilder
Returns a new mutable builder with a fluent API for aJsonObject
. 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
Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specifiedint
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
andvalue
or this instance if it already contains a field withkey
andvalue
. - Throws:
NullPointerException
- ifkey
isnull
.IllegalArgumentException
- ifkey
is empty or ifkey
is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.JsonKeyInvalidException
- if the JSONkey
was not valid.
-
setValue
Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specifiedlong
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
andvalue
or this instance if it already contains a field withkey
andvalue
. - Throws:
NullPointerException
- ifkey
isnull
.IllegalArgumentException
- ifkey
is empty or ifkey
is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.JsonKeyInvalidException
- if the JSONkey
was not valid.
-
setValue
Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specifieddouble
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
andvalue
or this instance if it already contains a field withkey
andvalue
. - Throws:
NullPointerException
- ifkey
isnull
.IllegalArgumentException
- ifkey
is empty or ifkey
is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.JsonKeyInvalidException
- if the JSONkey
was not valid.
-
setValue
Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specifiedboolean
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
andvalue
. - Throws:
NullPointerException
- ifkey
isnull
.IllegalArgumentException
- ifkey
is empty or ifkey
is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.JsonKeyInvalidException
- if the JSONkey
was not valid.
-
setValue
Creates a new JSON object by setting a new JSON field with the specified key and the JSON representation of the specifiedString
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
andvalue
. - Throws:
NullPointerException
- ifkey
isnull
.IllegalArgumentException
- ifkey
is empty or ifkey
is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.JsonKeyInvalidException
- if the JSONkey
was not valid.
-
setValue
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
andvalue
. - Throws:
NullPointerException
- ifkey
isnull
.IllegalArgumentException
- ifkey
is empty or ifkey
is an empty JsonPointer. Setting a value with slash as JsonKey object explicitly works.JsonKeyInvalidException
- if the JSONkey
was not valid.
-
set
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 ofvalue
.- Parameters:
fieldDefinition
- the definition of the JSON field containing the value, i. e. the field withJsonPointer.getLeaf()
as key andvalue
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
- iffieldDefinition
isnull
.IllegalArgumentException
- if the pointer offieldDefinition
is empty.JsonKeyInvalidException
- if the JSON key in the passedfieldDefinition
was not valid.
-
set
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
- iffield
isnull
.JsonKeyInvalidException
- if the JSON key in the passedjsonField
was not valid.
-
setAll
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
- ifjsonFields
is null.JsonKeyInvalidException
- if a JSON key in the passedjsonFields
was not valid.
-
contains
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 atkey
,false
else.- Throws:
NullPointerException
- ifkey
isnull
.
-
get
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
- ifpointer
isnull
.
-
get
This is a convenience method which does the same asget(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
- iffieldDefinition
isnull
.- See Also:
-
get
Returns a new JSON object which is composed from parts of this object. The parts to use are defined by the givenJsonFieldSelector
. 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
- iffield selector
isnull
.
-
getValue
Returns the value which is associated with the specified key. This method is similar toget(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
- ifkey
isnull
.
-
getValue
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
- iffieldDefinition
isnull
.JsonParseException
- if this JsonObject contained a value at the defined location with an unexpected type.
-
getValueOrThrow
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 aJsonMissingFieldException
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
- iffieldDefinition
isnull
.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 fromT
.
-
remove
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
- ifkey
isnull
.
-
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
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
- ifindex
isnull
.
-
filter
Filters thejson 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
-