Package org.eclipse.ditto.json

Interface JsonValue

All Known Subinterfaces:
JsonArray, JsonNumber, JsonObject
public interface JsonValue
Represents a JSON value. A JSON value can be
  • a literal like for example true or null,
  • a number like for example 42,
  • a string like for example "foo",
  • an array like for example [1,2,3,23] or
  • an object like for example 
     {
   "foo": "bar",
   "bar": 43.3,
   "baz": ["a", "b", "c"]
 }
For JSON objects and JSON arrays do exists dedicated interfaces which are JsonObject and JsonArray.

Implementations of this interface are required to be immutable!

  • Method Summary

    Modifier and Type
    Method
    Description
    JsonArray
    asArray()
    Returns this JSON value as JsonArray, assuming that this value represents a JSON array.
    boolean
    asBoolean()
    Returns this JSON value as a boolean value, assuming that this value is either true or false.
    double
    asDouble()
    Returns this JSON value as a double value, assuming that this value represents a JSON number.
    int
    asInt()
    Returns this JSON value as an int value, assuming that this value represents a JSON number that can be interpreted as Java int.
    long
    asLong()
    Returns this JSON value as an long value, assuming that this value represents a JSON number that can be interpreted as Java long.
    JsonObject
    asObject()
    Returns this JSON value as JsonObject, assuming that this value represents a JSON object.
    String
    asString()
    Returns this JSON value as string, assuming that this value represents a JSON string.
    default String
    formatAsString()
    Return this JSON value in string representation, without quoting if this is a JSON string already.
    long
    getUpperBoundForStringSize()
    Returns an upper bound for the size (in chars), that the serialized version of this value might have.
    boolean
    isArray()
    Indicates whether this value represents a JSON array.
    boolean
    isBoolean()
    Indicates whether this value represents a boolean JSON literal.
    boolean
    isDouble()
    Indicates whether this value is of type double.
    boolean
    isInt()
    Indicates whether this value is an integer.
    boolean
    isLong()
    Indicates whether this value is of type long.
    boolean
    isNull()
    Indicates whether this value represents a null JSON literal.
    boolean
    isNumber()
    Indicates whether this value represents a JSON number.
    boolean
    isObject()
    Indicates whether this value represents a JSON object.
    boolean
    isString()
    Indicates whether this value represents a JSON string.
    static JsonValue
    nullLiteral()
    Returns a JSON literal, which represents null.
    static JsonValue
    of(boolean value)
    Returns a JSON literal that represents the given boolean value.
    static JsonValue
    of(double value)
    Returns a JSON number that represents the given double value.
    static JsonValue
    of(int value)
    Returns a JSON number that represents the given int value.
    static JsonValue
    of(long value)
    Returns a JSON number that represents the given long value.
    static JsonValue
    of(String jsonString)
    Returns a JsonValue that represents the given Java string as JSON string.
    static <T> JsonValue
    of(T value)
    Tries to guess the appropriate JsonValue for the given Java value.
    String
    toString()
    Returns the JSON string for this value in its minimal form, without any additional whitespace.
    void
    writeValue(SerializationContext serializationContext)
    Writes this JsonValue into the provided serialization context.

  • Method Details

    • nullLiteral

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

    • of

      static JsonValue of(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.

    • of

      static JsonValue of(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.

    • of

      static JsonValue of(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.

    • of

      static JsonValue of(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.

    • of

      static JsonValue of(@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:

    • of

      static <T> JsonValue of(@Nullable T value)
      Tries to guess the appropriate JsonValue for the given Java value.
      Type Parameters:
      T - the Java type to be converted.
      Parameters:
      value - the Java value to be converted to its JsonValue counterpart.
      Returns:
      the appropriate JsonValue.
      Throws:
      JsonParseException - if value cannot be converted to a valid JSON value.

    • isBoolean

      boolean isBoolean()
      Indicates whether this value represents a boolean JSON literal.
      Returns:
      true this value represents a boolean JSON literal, false else.

    • isNumber

      boolean isNumber()
      Indicates whether this value represents a JSON number.
      Returns:
      true if this value represents a JSON number, false else.

    • isInt

      boolean isInt()
      Indicates whether this value is an integer.
      Returns:
      true if an only if this value is an integer.

    • isLong

      boolean isLong()
      Indicates whether this value is of type long.
      Returns:
      true if an only if this value is of type long.

    • isDouble

      boolean isDouble()
      Indicates whether this value is of type double.
      Returns:
      true if an only if this value is of type double.

    • isString

      boolean isString()
      Indicates whether this value represents a JSON string.
      Returns:
      true if this value represents a JSON string, false else.

    • isObject

      boolean isObject()
      Indicates whether this value represents a JSON object.
      Returns:
      true if this value represents a JSON object, false else.

    • isArray

      boolean isArray()
      Indicates whether this value represents a JSON array.
      Returns:
      true if this value represents a JSON array, false else.

    • isNull

      boolean isNull()
      Indicates whether this value represents a null JSON literal.
      Returns:
      true this value represents a null JSON literal, false else.

    • asBoolean

      boolean asBoolean()
      Returns this JSON value as a boolean value, assuming that this value is either true or false. If this is not the case, an exception is thrown.
      Returns:
      this value as Java boolean.
      Throws:
      UnsupportedOperationException - if this value is neither true or false.
      See Also:

    • asInt

      int asInt()
      Returns this JSON value as an int value, assuming that this value represents a JSON number that can be interpreted as Java int. If this is not the case, an exception is thrown.

      To be interpreted as Java int, the JSON number must neither contain an exponent nor a fraction part. Moreover, the number must be in the Integer range.

      Returns:
      this value as Java int.
      Throws:
      UnsupportedOperationException - if this value is not a JSON number.
      NumberFormatException - if this JSON number can not be interpreted as int value.
      See Also:

    • asLong

      long asLong()
      Returns this JSON value as an long value, assuming that this value represents a JSON number that can be interpreted as Java long. If this is not the case, an exception is thrown.

      To be interpreted as Java long, the JSON number must neither contain an exponent nor a fraction part. Moreover, the number must be in the Long range.

      Returns:
      this value as Java long.
      Throws:
      UnsupportedOperationException - if this value is not a JSON number.
      NumberFormatException - if this JSON number can not be interpreted as long value.
      See Also:

    • asDouble

      double asDouble()
      Returns this JSON value as a double value, assuming that this value represents a JSON number. If this is not the case, an exception is thrown.

      If the JSON number is out of the Double range, Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned.

      Returns:
      this value as Java double.
      Throws:
      UnsupportedOperationException - if this value is not a JSON number

    • asString

      String asString()
      Returns this JSON value as string, assuming that this value represents a JSON string. If this is not the case, an exception is thrown.
      Returns:
      the (simple) Java string represented by this value i. e. the returned string is not quoted.
      Throws:
      UnsupportedOperationException - if this value is not a JSON string.

    • asObject

      JsonObject asObject()
      Returns this JSON value as JsonObject, assuming that this value represents a JSON object. If this is not the case, an exception is thrown.
      Returns:
      a JsonObject for this value.
      Throws:
      UnsupportedOperationException - if this value is not a JSON object.

    • asArray

      JsonArray asArray()
      Returns this JSON value as JsonArray, assuming that this value represents a JSON array. If this is not the case, an exception is thrown.
      Returns:
      a JsonArray for this value.
      Throws:
      UnsupportedOperationException - if this value is not a JSON array.

    • toString

      String toString()
      Returns the JSON string for this value in its minimal form, without any additional whitespace.
      Overrides:
      toString in class Object
      Returns:
      a JSON string that represents this value. If this value is a JSON string, the returned string is surrounded by quotes.

    • formatAsString

      default String formatAsString()
      Return this JSON value in string representation, without quoting if this is a JSON string already.
      Returns:
      the string representation.

    • writeValue

      void writeValue(SerializationContext serializationContext) throws IOException
      Writes this JsonValue into the provided serialization context. This is intended to be used by serialization logic only. Pass this object to the relevant methods in JsonFactory instead if you want its serialized representation.
      Parameters:
      serializationContext - the context for serialization bundling configuration and state needed for serialization.
      Throws:
      IOException - in case writing the value to the backing OutputStream causes an IOException.
      Since:
      1.1.0

    • getUpperBoundForStringSize

      long getUpperBoundForStringSize()
      Returns an upper bound for the size (in chars), that the serialized version of this value might have. The result of toString().length() on this object is guaranteed to be lower or equal.
      Returns:
      the upper bound as defined above.
      Since:
      1.1.0