Interface JsonValue

All Known Subinterfaces:
JsonArray, JsonBoolean, JsonNull, JsonNumber, JsonObject, JsonString
public sealed interface JsonValue permits JsonString, JsonNumber, JsonObject, JsonArray, JsonBoolean, JsonNull
The interface that represents a JSON value. A JsonValue represents a syntactic element within a JSON text. The JsonValue subtypes correspond to the JSON types, while JsonValue itself provides a uniform interface for navigation, conversion, and generation.

JsonValue does not define any identity or value semantics. Code that requires equality, hashing, or comparisons should use a conversion method to obtain a Java value upon which such operations are performed.

Instances of JsonValue are immutable and thread safe. See the package specification for an overview of parsing, accessing, converting, and generating JSON text.

Since:
28

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    asBoolean()
    Returns the boolean value represented by this JsonValue if it is an instance of JsonBoolean; otherwise, throws a JsonValueException.
    default double
    asDouble()
    Returns a double if this JsonValue is an instance of JsonNumber that can be converted, as if by Double.parseDouble, to a finite double value; otherwise, throws a JsonValueException.
    default int
    asInt()
    Returns an int if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException.
    default List<JsonValue>
    asList()
    Returns an unmodifiable list of the JsonValues if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException.
    default long
    asLong()
    Returns a long if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException.
    default Map<String, JsonValue>
    asMap()
    Returns an unmodifiable map of String to JsonValue if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException.
    default String
    asString()
    Returns the String value represented by this JsonValue if it is an instance of JsonString; otherwise, throws a JsonValueException.
    default JsonValue
    get(int index)
    Returns the JsonValue associated with the given index if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException.
    default JsonValue
    get(String name)
    Returns the JsonValue associated with the given member name if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException.
    String
    toString()
    Returns a String representation of this JsonValue that conforms to JSON syntax.
    default Optional<JsonValue>
    tryGet(String name)
    Returns an Optional containing the value of a given member of this JsonObject, or an empty Optional if the member is absent; throws JsonValueException if this JsonValue is not a JsonObject.
    default Optional<JsonValue>
    tryValue()
    Returns an Optional containing this JsonValue if it is not an instance of JsonNull, otherwise an empty Optional.

  • Method Details

    • toString

      String toString()
      Returns a String representation of this JsonValue that conforms to JSON syntax. The returned string represents the same JSON value as this object and does not contain insignificant whitespace or line separators. The returned String may or may not be a canonical representation of the JSON value. If this JsonValue was obtained via one of the parsing methods on the Json class, the returned String is not necessarily an exact lexical match of the JSON text that was parsed. Subinterfaces may specify stronger preservation behavior for their corresponding JSON type.

      For a String representation suitable for display, use Json.toDisplayString(JsonValue, String).

      Overrides:
      toString in class Object
      Returns:
      a String representation of this JsonValue that conforms to JSON syntax
      See Also:

    • asBoolean

      default boolean asBoolean()
      Returns the boolean value represented by this JsonValue if it is an instance of JsonBoolean; otherwise, throws a JsonValueException.
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonBoolean are expected to provide an implementation of this method.
      Returns:
      the boolean value represented by this JsonValue if it is an instance of JsonBoolean; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonBoolean.

    • asInt

      default int asInt()
      Returns an int if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException. This JsonValue must be a JSON number that represents a whole number and that is within the range Integer.MIN_VALUE to Integer.MAX_VALUE, inclusive. This is true even if the JSON number contains an exponent or a fractional part consisting of all zeroes. For example, the JSON numbers "123.0" and "1.23e2" both produce an int value of 123. A JsonValueException is thrown when the numeric value cannot be represented as an int; for example, the JSON number "5.5".
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonNumber are expected to provide an implementation of this method.
      Returns:
      an int if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonNumber or is not representable as an int.

    • asLong

      default long asLong()
      Returns a long if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException. This JsonValue must be a JSON number that represents a whole number and that is within the range Long.MIN_VALUE to Long.MAX_VALUE, inclusive. This is true even if the JSON number contains an exponent or a fractional part consisting of all zeroes. For example, the JSON numbers "123.0" and "1.23e2" both produce a long value of 123. A JsonValueException is thrown when the numeric value cannot be represented as a long; for example, the JSON number "5.5".
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonNumber are expected to provide an implementation of this method.
      Returns:
      a long if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonNumber or is not representable as a long.

    • asDouble

      default double asDouble()
      Returns a double if this JsonValue is an instance of JsonNumber that can be converted, as if by Double.parseDouble, to a finite double value; otherwise, throws a JsonValueException.
      API Note:
      Callers of this method should be aware of the potential loss in precision or magnitude when a JsonNumber is converted to a double. A JSON number may be rounded to the nearest representable double value, and a JSON number with more than about 15 decimal digits may lose precision. A JSON number with a magnitude larger than about 1.8 × 10308 cannot be represented as a finite double, and attempting to convert such a number will result in JsonValueException. (This differs from Double.parseDouble, which will return Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY for such cases.) This method will never return Double.NaN. However, this method will properly convert and return negative zero (-0.0). To handle numbers of almost arbitrary precision and magnitude, consider converting to BigDecimal using new BigDecimal(jsonNumber.toString()). Note that BigDecimal cannot represent negative zero.
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonNumber are expected to provide an implementation of this method.
      Returns:
      a double if this JsonValue is an instance of JsonNumber that can be converted, as if by Double.parseDouble, to a finite double value; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonNumber or is not representable as a finite double.

    • asString

      default String asString()
      Returns the String value represented by this JsonValue if it is an instance of JsonString; otherwise, throws a JsonValueException. If this JsonString was created by parsing a JSON text, any escaped characters in the original JSON text are converted to their unescaped form.
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonString are expected to provide an implementation of this method.
      Returns:
      the String value represented by this JsonValue if it is an instance of JsonString; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonString.

    • asList

      default List<JsonValue> asList()
      Returns an unmodifiable list of the JsonValues if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException.
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonArray are expected to provide an implementation of this method.
      Returns:
      an unmodifiable list of the JsonValues if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonArray.

    • asMap

      default Map<String, JsonValue> asMap()
      Returns an unmodifiable map of String to JsonValue if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException.
      Implementation Requirements:
      The default implementation provided by JsonValue throws JsonValueException. As such, implementors of JsonObject are expected to provide an implementation of this method.
      Implementation Note:
      The JDK platform implementation of JsonObject preserves the encounter order of members. When a JsonObject is created by parsing, this corresponds to the order of members in the source JSON text. When created via the JsonObject.of(Map) factory method, the order follows the encounter order of the provided map.
      Returns:
      an unmodifiable map of String to JsonValue if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of JsonObject.

    • get

      default JsonValue get(String name)
      Returns the JsonValue associated with the given member name if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException.
      Implementation Requirements:
      The default implementation obtains a JsonValue which is the result of invoking asMap().get(name). If name is absent, JsonValueException is thrown.
      Parameters:
      name - the member name
      Returns:
      the JsonValue associated with the given member name if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException
      Throws:
      NullPointerException - if the member name is null
      JsonValueException - if this JsonValue is not an instance of a JsonObject or there is no association with the member name

    • tryGet

      default Optional<JsonValue> tryGet(String name)
      Returns an Optional containing the value of a given member of this JsonObject, or an empty Optional if the member is absent; throws JsonValueException if this JsonValue is not a JsonObject.
      Implementation Requirements:
      The default implementation obtains an Optional<JsonValue> by invoking asMap().get(name), which is then passed to Optional.ofNullable(T).
      Parameters:
      name - the member name
      Returns:
      an Optional containing the value of a given member of this JsonObject, or an empty Optional if the member is absent; throws JsonValueException if this JsonValue is not a JsonObject
      Throws:
      NullPointerException - if the member name is null
      JsonValueException - if this JsonValue is not an instance of a JsonObject

    • get

      default JsonValue get(int index)
      Returns the JsonValue associated with the given index if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException.
      Implementation Requirements:
      The default implementation obtains a JsonValue which is the result of invoking asList().get(index). If index is out of bounds, JsonValueException is thrown.
      Parameters:
      index - the index of the array
      Returns:
      the JsonValue associated with the given index if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException
      Throws:
      JsonValueException - if this JsonValue is not an instance of a JsonArray or the given index is out of bounds

    • tryValue

      default Optional<JsonValue> tryValue()
      Returns an Optional containing this JsonValue if it is not an instance of JsonNull, otherwise an empty Optional.
      Implementation Requirements:
      The default implementation returns Optional.empty() if this JsonValue is an instance of JsonNull; otherwise Optional.of(this).
      Returns:
      an Optional containing this JsonValue if it is not an instance of JsonNull, otherwise an empty Optional