Package org.eclipse.ditto.json

Class JsonFactory

java.lang.Object
org.eclipse.ditto.json.JsonFactory
@Immutable public final class JsonFactory extends Object
The main entry point for the Eclipse Ditto JSON API. It provides a lot of convenience methods. Apart from newArrayBuilder() and newObjectBuilder() all methods of this class return immutable objects.

  • Method Details

    • newKey

      public static JsonKey newKey(CharSequence keyValue)
      Returns JSON key for the given character sequence. If the given key value is already a JSON key, this is immediately properly cast and returned.
      Parameters:
      keyValue - the character sequence value of the JSON key to be created.
      Returns:
      a new JSON key with keyValue as its value.
      Throws:
      NullPointerException - if keyValue is null.
      IllegalArgumentException - if keyValue is empty.

    • nullLiteral

      public static JsonValue nullLiteral()
      Returns a JSON literal which represents null.
      Returns:
      the null JSON literal.

    • newValue

      public static JsonValue newValue(boolean value)
      Returns a JSON literal that represents the given boolean value.
      Parameters:
      value - the value to get a JSON literal for.
      Returns:
      a JSON literal that represents the given boolean value.

    • newValue

      public static JsonNumber newValue(int value)
      Returns a JSON number that represents the given int value.
      Parameters:
      value - the value to get a JSON number for.
      Returns:
      a JSON number that represents the given value.

    • newValue

      public static JsonNumber newValue(long value)
      Returns a JSON number that represents the given long value.
      Parameters:
      value - the value to get a JSON number for.
      Returns:
      a JSON number that represents the given value.

    • newValue

      public static JsonNumber newValue(double value)
      Returns a JSON number that represents the given double value.
      Parameters:
      value - the value to get a JSON number for.
      Returns:
      a JSON number that represents the given value.

    • newValue

      public static JsonValue newValue(@Nullable String jsonString)
      Returns a JsonValue that represents the given Java string as JSON string. For example the Java string "foo" would be "\"foo\"" as JSON string.
      Parameters:
      jsonString - the string to get a JSON representation for.
      Returns:
      a JSON value that represents the given string. If jsonString is null, a "null" object is returned.
      Throws:
      IllegalArgumentException - if jsonString is empty.
      See Also:

    • readFrom

      public static JsonValue readFrom(String jsonString)
      Reads the given string and creates a JSON value based on the read data. The actual type of this JSON value is unknown but can be obtained by invoking the is... methods.
      Parameters:
      jsonString - the JSON document to read.
      Returns:
      a JSON value representing the read document. This value can be a JSON literal, a JSON object and so on.
      Throws:
      NullPointerException - if jsonString is empty.
      JsonParseException - if jsonString is empty or if it is no valid JSON.

    • readFrom

      public static JsonValue readFrom(Reader reader)
      Reads the entire input stream from the specified reader and parses it as JSON value. The input stream is expected to contain a valid JSON value with optional whitespace padding.

      As characters are read in chunks and buffered internally it does not improve reading performance to wrap an existing reader in a BufferedReader.

      Parameters:
      reader - the reader to read the JSON value from.
      Returns:
      a JSON value which represents the read stream.
      Throws:
      NullPointerException - if reader is null.
      JsonParseException - if an I/O error occurred or if the input is no valid JSON.

    • newObjectBuilder

      public static JsonObjectBuilder newObjectBuilder()
      Returns a new mutable builder for a JsonObject.
      Returns:
      a new JSON object builder.

    • newObjectBuilder

      public static JsonObjectBuilder newObjectBuilder(Iterable<JsonField> jsonFields)
      Returns a new mutable builder for the specified JsonFields. The returned builder is already initialised with the data of the provided 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.
      Parameters:
      jsonFields - are the initial data of the returned builder.
      Returns:
      a new JSON object builder with pre-filled data of jsonFields.
      Throws:
      NullPointerException - if jsonFields is null.

    • newObject

      public static JsonObject newObject()
      Returns an empty JSON object.
      Returns:
      an empty JSON object.

    • newObject

      public static JsonObject newObject(String jsonString)
      Creates a JSON object from the given string.
      Parameters:
      jsonString - the string that represents the JSON object.
      Returns:
      the JSON object that has been created from the string.
      Throws:
      NullPointerException - if jsonString is null.
      IllegalArgumentException - if jsonString is empty.
      JsonParseException - if jsonString does not contain a valid JSON object.

    • newObject

      public static JsonObject newObject(JsonValue jsonValue)

    • newObject

      public static JsonObject newObject(byte[] jsonData)
      Creates a JSON object 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 contain a valid JSON object.
      Since:
      1.5.0

    • newObject

      public static JsonObject newObject(Map<JsonKey,JsonValue> fields)
      Creates a JSON object from the given key-value pairs aka fields.
      Parameters:
      fields - the fields of the JSON object to be created.
      Returns:
      a new JSON object based on the provided fields.
      Throws:
      NullPointerException - if fields is null.

    • newObject

      public static JsonObject newObject(JsonPointer path, JsonValue value)
      Creates a JSON object from the given path and value.
      Parameters:
      path - the path where the given value will be set
      value - the value that will be set at the given path
      Returns:
      a new JSON object containing the given value at the given path.
      Throws:
      NullPointerException - if path or value is null.
      IllegalArgumentException - if path is empty and value is not an object.
      Since:
      1.5.0

    • newObject

      public static JsonObject newObject(Iterable<JsonField> jsonFields)
      Parameters:
      jsonFields - the json fields to create a new JsonObject from.
      Returns:
      a null object if jsonFields is a null json object. Else this returns a new object containing the given {code jsonFields}.

    • newObject

      public static JsonObject newObject(JsonObject jsonObject1, JsonObject jsonObject2)
      Merge two JSON objects into one JSON object.
      Parameters:
      jsonObject1 - the json object to merge, overrides conflicting fields.
      jsonObject2 - the json object to merge.
      Returns:
      returns a new object merged the given {code jsonObject1} and {code jsonObject2}.
      Since:
      1.5.0

    • mergeJsonValues

      public static JsonValue mergeJsonValues(JsonValue jsonValue1, JsonValue jsonValue2)
      Merge two JSON values into one JSON value. Implementation is conform to RFC 7396.
      Parameters:
      jsonValue1 - the json value to merge, overrides conflicting fields.
      jsonValue2 - the json value to merge.
      Returns:
      returns a new value merged the given jsonValue1 and jsonValue2.
      Since:
      2.0.0

    • nullObject

      public static JsonObject nullObject()
      Returns a JSON NULL literal which is typed as JSON object.
      Returns:
      an object typed JSON NULL literal.

    • newArrayBuilder

      public static JsonArrayBuilder newArrayBuilder()
      Returns a new mutable builder for a JsonArray.
      Returns:
      a new JSON array builder.

    • newArrayBuilder

      public static JsonArrayBuilder newArrayBuilder(Iterable<? extends JsonValue> values)
      Returns a new mutable builder for a JsonArray which is already initialised with the given values.
      Parameters:
      values - the values of the JSON array to be created. This might be an existing JSON array as well.
      Returns:
      a new JSON array builder.
      Throws:
      NullPointerException - if values is null.

    • newArray

      public static JsonArray newArray()
      Returns a new empty JSON array.
      Returns:
      a new empty JSON array.

    • newArray

      public static JsonArray newArray(String jsonString)
      Creates a new JSON array from the given string.
      Parameters:
      jsonString - the string that represents the JSON array.
      Returns:
      the JSON array that has been created from the string.
      Throws:
      NullPointerException - if jsonString is null.
      IllegalArgumentException - if jsonString is empty.
      JsonParseException - if jsonString does not contain a valid JSON array.

    • nullArray

      public static JsonArray nullArray()
      Returns a JSON NULL literal which is typed as JSON array.
      Returns:
      an array typed JSON NULL literal.

    • newField

      public static JsonField newField(JsonKey key, @Nullable JsonValue value)
      Returns a new JSON field based on the specified key value pair.
      Parameters:
      key - the key of the field to be created.
      value - the value of the field to be created. null will be converted to the JSON NULL Literal.
      Returns:
      a new JSON field containing the specified key value pair.
      Throws:
      NullPointerException - if key is null;

    • newField

      public static JsonField newField(JsonKey key, @Nullable JsonValue value, @Nullable JsonFieldDefinition<?> definition)
      Returns a new JSON field based on the specified key value pair and definition.
      Parameters:
      key - the key of the field to be created.
      value - the value of the field to be created. null will be converted to the JSON NULL Literal.
      definition - the definition of the field to be created.
      Returns:
      a new JSON field containing the specified key value pair and definition.
      Throws:
      NullPointerException - if key is null.

    • newPatch

      public static JsonPatch newPatch(JsonPatch.Operation operation, JsonPointer path, @Nullable JsonValue value)
      Returns a new JSON Patch which can be used to specify modifications on JSON Objects.
      Parameters:
      operation - the patch operation type
      path - a JSON Pointer specifying the path within the JSON Object on which the operation is defined
      value - the value to be used for the specified operation on the given path
      Returns:
      the new JSON Patch.
      Throws:
      NullPointerException - if operation or path is null.

    • newPatch

      public static JsonPatch newPatch(String jsonString)
      Returns a new JSON Patch created from the given string.
      Parameters:
      jsonString - the string representation of the JSON Patch object to be created.
      Returns:
      the new JSON Patch.
      Throws:
      NullPointerException - if jsonString is null.
      IllegalArgumentException - if jsonString is empty.
      JsonParseException - if jsonString does not contain a valid JSON Patch JSON object.
      JsonMissingFieldException - if jsonString did not contain JsonPatch.JsonFields.OPERATION or JsonPatch.JsonFields.PATH.

    • emptyPointer

      public static JsonPointer emptyPointer()
      Returns an empty JSON pointer.
      Returns:
      JSON pointer containing no JSON keys.

    • newPointer

      public static JsonPointer newPointer(JsonKey rootLevel, JsonKey... subLevels)
      Returns a new JSON pointer which consist of the specified hierarchical keys..
      Parameters:
      rootLevel - the JSON key which is the root level of the JSON pointer to create.
      subLevels - the JSON keys which form sub levels to the root level as well as to each other.
      Returns:
      a new JSON pointer consisting of hierarchical JSON keys.
      Throws:
      NullPointerException - if any argument is null.

    • newPointer

      public static JsonPointer newPointer(CharSequence slashDelimitedCharSequence)
      Parses the given string to obtain a new JSON pointer. This method is the inverse of JsonPointer.toString() with one exception: both strings "/" and "" lead to an empty pointer while the string representation of an empty string is always "/".

      To support tildes in JsonKeys, they have to be escaped with "~0". For example, parsing the string "/foo/~0dum~0die~0dum/baz" would result in a JsonPointer consisting of the JsonKeys

      1. "foo",
      2. "~dum~die~dum" and
      3. "baz".
      Parameters:
      slashDelimitedCharSequence - a string representing a JSON pointer.
      Returns:
      a new JSON pointer consisting of the JSON keys which were extracted from slashDelimitedCharSequence.
      Throws:
      NullPointerException - if slashDelimitedCharSequence is null.
      JsonPointerInvalidException - if the passed slashDelimitedCharSequence contained double slashes.

    • newParseOptionsBuilder

      public static JsonParseOptionsBuilder newParseOptionsBuilder()
      Returns a new mutable builder for JsonParseOptions.
      Returns:
      the new JsonParseOptionsBuilder.

    • emptyFieldSelector

      public static JsonFieldSelector emptyFieldSelector()
      Returns a new empty JSON field selector.
      Returns:
      a new empty JSON field selector.

    • newFieldSelector

      public static JsonFieldSelector newFieldSelector(@Nullable String fieldSelectorString, JsonParseOptions options)
      Returns a new JSON field selector by parsing the given string. If the JSON field selector string is null or empty this means that no fields were selected thus this method returns an empty JSON field selector.

      For example, the field selector string 

       "thingId,attributes(acceleration,someData(foo,bar/baz)),features/key"
      would lead to a JSON field selector which consists of the following JSON pointers:
      • "thingId",
      • "attributes/acceleration",
      • "attributes/someData/foo",
      • "attributes/someData/bar/baz",
      • "features/key".
      Parameters:
      fieldSelectorString - string to be transformed into a JSON field selector object.
      options - the JsonParseOptions to apply when parsing the fieldSelectorString.
      Returns:
      a new JSON field selector.
      Throws:
      JsonFieldSelectorInvalidException - if fieldSelectorString is empty or if fieldSelectorString does not contain a closing parenthesis ()) for each opening parenthesis (().
      IllegalStateException - if fieldSelectorString cannot be decoded as UTF-8.

    • newFieldSelector

      public static JsonFieldSelector newFieldSelector(Iterable<String> fieldSelectorStrings, JsonParseOptions options)
      Returns a new JSON field selector by parsing the given string. If the JSON field selector string is null or empty this means that no fields were selected thus this method returns an empty JSON field selector.

      For example, the field selector string 

       "thingId,attributes(acceleration,someData(foo,bar/baz)),features/key"
      would lead to a JSON field selector which consists of the following JSON pointers:
      • "thingId",
      • "attributes/acceleration",
      • "attributes/someData/foo",
      • "attributes/someData/bar/baz",
      • "features/key".
      Parameters:
      fieldSelectorStrings - strings to be transformed into a JSON field selector object.
      options - the JsonParseOptions to apply when parsing the fieldSelectorString.
      Returns:
      a new JSON field selector.
      Throws:
      JsonFieldSelectorInvalidException - if fieldSelectorString is empty or if fieldSelectorString does not contain a closing parenthesis ()) for each opening parenthesis (().
      IllegalStateException - if fieldSelectorStrings cannot be decoded as UTF-8.
      Since:
      3.3.0

    • newFieldSelector

      public static JsonFieldSelector newFieldSelector(Iterable<JsonPointer> pointers)
      Returns a new JSON field selector which is based on the given set of JsonPointers. If the set of JSON pointers string is empty this means that no fields were selected thus this method returns an empty JSON field selector.
      Parameters:
      pointers - the JSON pointers of the field selector to be created.
      Returns:
      a new JSON field selector.
      Throws:
      NullPointerException - if pointers is null.
      IllegalArgumentException - if pointers is empty.

    • newFieldSelector

      public static JsonFieldSelector newFieldSelector(JsonPointer pointer, JsonPointer... furtherPointers)
      Returns a new JSON field selector which is based on the given JsonPointer(s).
      Parameters:
      pointer - a JSON pointer of the field selector to be created.
      furtherPointers - additional JSON pointers to form the field selector to be created by this method.
      Returns:
      a new JSON field selector.
      Throws:
      NullPointerException - if any argument is null.

    • newFieldSelector

      public static JsonFieldSelector newFieldSelector(CharSequence pointerString, CharSequence... furtherPointerStrings)
      Returns a new JSON field selector which is based on the given JsonPointer(s).
      Parameters:
      pointerString - a JSON pointer of the field selector to be created.
      furtherPointerStrings - additional JSON pointers to form the field selector to be created by this method.
      Returns:
      a new JSON field selector.
      Throws:
      NullPointerException - if any argument is null.
      JsonPointerInvalidException - if any passed pointerString contained double slashes.

    • parseJsonFieldSelector

      @Nullable public static JsonFieldSelector parseJsonFieldSelector(@Nullable String jsonFieldSelectorString)
      Parse a nullable string as JSON field selector. Return null if the string is null or contains a single comma.
      Parameters:
      jsonFieldSelectorString - the string to parse.
      Returns:
      the Json field selector.
      Since:
      1.1.0

    • newFieldSelector

      public static JsonFieldSelector newFieldSelector(JsonFieldDefinition<?> fieldDefinition, JsonFieldDefinition<?>... furtherFieldDefinitions)
      Returns a new JSON field selector which is based on pointers of the given JsonFieldDefinition(s).
      Parameters:
      fieldDefinition - the JSON field definition of the returned field selector.
      furtherFieldDefinitions - additional JSON field definitions of the returned field selector.
      Returns:
      a new JSON field selector.
      Throws:
      NullPointerException - if any argument is null.

    • newFieldSelectorBuilder

      public static JsonFieldSelectorBuilder newFieldSelectorBuilder()
      Returns a new JSON field selector builder for building JSON field selectors.
      Returns:
      the JSON field selector builder.

    • newStringFieldDefinition

      public static JsonFieldDefinition<String> newStringFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains a String value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if pointer is empty.

    • newBooleanFieldDefinition

      public static JsonFieldDefinition<Boolean> newBooleanFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains a boolean value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • newIntFieldDefinition

      public static JsonFieldDefinition<Integer> newIntFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains an int value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • newLongFieldDefinition

      public static JsonFieldDefinition<Long> newLongFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains an long value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • newDoubleFieldDefinition

      public static JsonFieldDefinition<Double> newDoubleFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains an double value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • newJsonArrayFieldDefinition

      public static JsonFieldDefinition<JsonArray> newJsonArrayFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains an JsonArray value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • newJsonObjectFieldDefinition

      public static JsonFieldDefinition<JsonObject> newJsonObjectFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains an JsonObject value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • newJsonValueFieldDefinition

      public static JsonFieldDefinition<JsonValue> newJsonValueFieldDefinition(CharSequence pointer, JsonFieldMarker... markers)
      Returns a new definition of a JSON field which contains an JsonValue value.
      Parameters:
      pointer - a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.
      markers - an optional array of markers which add user defined semantics to the defined JSON field.
      Returns:
      the new JSON field definition.
      Throws:
      NullPointerException - if any argument but markers is null.
      IllegalArgumentException - if pointer is empty.

    • createJsonArray

      public static JsonArray createJsonArray(List<JsonValue> jsonValueList, @Nullable byte[] cborRepresentation)
      Creates a JsonArray backed with an already serialized CBOR representation as the passed bytes.

      This is a Ditto internal API is not intended for re-use. It therefore is not treated as API which is held binary compatible to previous versions.

      Parameters:
      jsonValueList - the JSON values to create the JsonArray from.
      cborRepresentation - the already CBOR serialized representation of the JsonArray.
      Returns:
      the created JsonArray.
      Since:
      1.2.1

    • createJsonObject

      public static JsonObject createJsonObject(Map<String,JsonField> jsonFieldMap, @Nullable byte[] cborObjectRepresentation)
      Creates a JsonObject backed with an already serialized CBOR representation as the passed bytes.

      This is a Ditto internal API is not intended for re-use. It therefore is not treated as API which is held binary compatible to previous versions.

      Parameters:
      jsonFieldMap - the JSON fields to create the JsonObject from.
      cborObjectRepresentation - the already CBOR serialized representation of the JsonObject.
      Returns:
      the created JsonObject.
      Since:
      1.2.1