Package dev.tachyonmcp.api.json

Interface JsonObject

All Superinterfaces:
JsonDocument
All Known Implementing Classes:
Args
public interface JsonObject extends JsonDocument
An immutable, provider-neutral view of a JSON object.

Missing properties and JSON null produce empty optionals. Accessing a property as the wrong type, narrowing a fraction to an integer, or overflowing the requested numeric type throws IllegalArgumentException. Numeric strings and other scalar types are never coerced.

Implementations may retain a provider-specific representation and expose it through JsonDocument.unwrap(Class).

Author:
Konstantin Pavlov

  • Method Details

    • has

      boolean has(String name)
      Returns whether the object has property name, including when its value is JSON null.
      Parameters:
      name - the property name
      Returns:
      true if the property exists

    • objectOpt

      Optional<JsonObject> objectOpt(String name)
      Returns the named object, or an empty optional when it is missing or JSON null.
      Parameters:
      name - the property name
      Returns:
      the object value, or empty if missing or null

    • arrayOpt

      Optional<JsonArray> arrayOpt(String name)
      Returns the named array, or an empty optional when it is missing or JSON null.
      Parameters:
      name - the property name
      Returns:
      the array value, or empty if missing or null

    • stringOpt

      Optional<String> stringOpt(String name)
      Returns the named string, or an empty optional when it is missing or JSON null.
      Parameters:
      name - the property name
      Returns:
      the string value, or empty if missing or null

    • boolOpt

      Optional<Boolean> boolOpt(String name)
      Returns the named boolean, or an empty optional when it is missing or JSON null.
      Parameters:
      name - the property name
      Returns:
      the boolean value, or empty if missing or null

    • decimalOpt

      Optional<BigDecimal> decimalOpt(String name)
      Returns the named number without precision loss.
      Parameters:
      name - the property name
      Returns:
      the decimal value, or empty if missing or null

    • intOpt

      OptionalInt intOpt(String name)
      Returns the named exact int.
      Parameters:
      name - the property name
      Returns:
      the int value, or empty if missing or null
      Throws:
      IllegalArgumentException - if the value is not a number or is not exactly representable as an int

    • longOpt

      OptionalLong longOpt(String name)
      Returns the named exact long.
      Parameters:
      name - the property name
      Returns:
      the long value, or empty if missing or null
      Throws:
      IllegalArgumentException - if the value is not a number or is not exactly representable as a long

    • doubleOpt

      OptionalDouble doubleOpt(String name)
      Returns the named value converted to a finite double.

      The conversion may lose precision. Use decimalOpt(String) when an exact decimal representation is required.

      Parameters:
      name - the property name
      Returns:
      the double value, or empty if missing or null

    • objectValue

      default JsonObject objectValue(String name)
      Returns the named required object.
      Parameters:
      name - the property name
      Returns:
      the object value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • arrayValue

      default JsonArray arrayValue(String name)
      Returns the named required array.
      Parameters:
      name - the property name
      Returns:
      the array value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • stringValue

      default String stringValue(String name)
      Returns the named required string.
      Parameters:
      name - the property name
      Returns:
      the string value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • boolValue

      default boolean boolValue(String name)
      Returns the named required boolean.
      Parameters:
      name - the property name
      Returns:
      the boolean value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • decimalValue

      default BigDecimal decimalValue(String name)
      Returns the named required number without precision loss.
      Parameters:
      name - the property name
      Returns:
      the decimal value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • intValue

      default int intValue(String name)
      Returns the named required exact int.
      Parameters:
      name - the property name
      Returns:
      the int value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • longValue

      default long longValue(String name)
      Returns the named required exact long.
      Parameters:
      name - the property name
      Returns:
      the long value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • doubleValue

      default double doubleValue(String name)
      Returns the named required finite double.
      Parameters:
      name - the property name
      Returns:
      the double value
      Throws:
      IllegalArgumentException - if the property is missing or null

    • objectOr

      default JsonObject objectOr(String name, JsonObject fallback)
      Returns the named object or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the object value, or fallback

    • arrayOr

      default JsonArray arrayOr(String name, JsonArray fallback)
      Returns the named array or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the array value, or fallback

    • stringOr

      default String stringOr(String name, String fallback)
      Returns the named string or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the string value, or fallback

    • boolOr

      default boolean boolOr(String name, boolean fallback)
      Returns the named boolean or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the boolean value, or fallback

    • decimalOr

      default BigDecimal decimalOr(String name, BigDecimal fallback)
      Returns the named decimal or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the decimal value, or fallback

    • intOr

      default int intOr(String name, int fallback)
      Returns the named exact int or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the int value, or fallback

    • longOr

      default long longOr(String name, long fallback)
      Returns the named exact long or fallback when it is missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the long value, or fallback

    • doubleOr

      default double doubleOr(String name, double fallback)
      Returns the named finite double or fallback when missing or JSON null.
      Parameters:
      name - the property name
      fallback - the fallback value
      Returns:
      the double value, or fallback

    • asMap

      @ExperimentalApi Map<String,Object> asMap()
      Returns an immutable map representation.
      Returns:
      the map view

    • of

      static JsonObject of(Map<String,?> values)
      Creates an immutable object by recursively snapshotting JSON-compatible values.
      Parameters:
      values - the source map
      Returns:
      a new JSON object

    • empty

      static JsonObject empty()
      Returns an empty JSON object.
      Returns:
      the empty instance