Package dev.tachyonmcp.api.json

Interface JsonArray

All Superinterfaces:
JsonDocument
public interface JsonArray extends JsonDocument
An immutable, provider-neutral view of a JSON array.

Elements are read by position. A JSON null element produces an empty optional; accessing an element 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. An index outside [0, size()) throws IndexOutOfBoundsException.

Nested objects and arrays are returned as JsonObject and JsonArray. For a bulk typed view of a homogeneous array use valuesAs(Class); for heterogeneous or nested generic shapes decode the enclosing payload with a serde.

Author:
Konstantin Pavlov

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<JsonArray>
    arrayOpt(int index)
    Returns the element at index as an array, or an empty optional when it is JSON null.
    default JsonArray
    arrayOr(int index, JsonArray fallback)
    Returns the array element at index or fallback when it is JSON null.
    default JsonArray
    arrayValue(int index)
    Returns the required array element at index.
    List<Object>
    asList()
    Returns an immutable list representation.
    Optional<Boolean>
    boolOpt(int index)
    Returns the element at index as a boolean, or an empty optional when it is JSON null.
    default boolean
    boolOr(int index, boolean fallback)
    Returns the boolean element at index or fallback when it is JSON null.
    default boolean
    boolValue(int index)
    Returns the required boolean element at index.
    Optional<BigDecimal>
    decimalOpt(int index)
    Returns the element at index as a number without precision loss.
    default BigDecimal
    decimalOr(int index, BigDecimal fallback)
    Returns the decimal element at index or fallback when it is JSON null.
    default BigDecimal
    decimalValue(int index)
    Returns the required number element at index without precision loss.
    OptionalDouble
    doubleOpt(int index)
    Returns the element at index converted to a finite double.
    default double
    doubleOr(int index, double fallback)
    Returns the finite double element at index or fallback when JSON null.
    default double
    doubleValue(int index)
    Returns the required finite double element at index.
    static JsonArray
    empty()
    Returns an empty JSON array.
    OptionalInt
    intOpt(int index)
    Returns the element at index as an exact int.
    default int
    intOr(int index, int fallback)
    Returns the exact int element at index or fallback when JSON null.
    default int
    intValue(int index)
    Returns the required exact int element at index.
    default boolean
    isEmpty()
    Returns whether the array has no elements.
    OptionalLong
    longOpt(int index)
    Returns the element at index as an exact long.
    default long
    longOr(int index, long fallback)
    Returns the exact long element at index or fallback when JSON null.
    default long
    longValue(int index)
    Returns the required exact long element at index.
    Optional<JsonObject>
    objectOpt(int index)
    Returns the element at index as an object, or an empty optional when it is JSON null.
    default JsonObject
    objectOr(int index, JsonObject fallback)
    Returns the object element at index or fallback when it is JSON null.
    default JsonObject
    objectValue(int index)
    Returns the required object element at index.
    static JsonArray
    of(List<?> values)
    Creates an immutable array by recursively snapshotting JSON-compatible values.
    int
    size()
    Returns the number of elements.
    Optional<String>
    stringOpt(int index)
    Returns the element at index as a string, or an empty optional when it is JSON null.
    default String
    stringOr(int index, String fallback)
    Returns the string element at index or fallback when it is JSON null.
    default String
    stringValue(int index)
    Returns the required string element at index.
    <T> List<T>
    valuesAs(Class<T> element)
    Returns every element coerced to element.

    Methods inherited from interface dev.tachyonmcp.api.json.JsonDocument

    json, unwrap

  • Method Details

    • size

      int size()
      Returns the number of elements.
      Returns:
      the element count

    • isEmpty

      default boolean isEmpty()
      Returns whether the array has no elements.
      Returns:
      true if empty

    • objectOpt

      Optional<JsonObject> objectOpt(int index)
      Returns the element at index as an object, or an empty optional when it is JSON null.
      Parameters:
      index - the element index
      Returns:
      the object value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • arrayOpt

      Optional<JsonArray> arrayOpt(int index)
      Returns the element at index as an array, or an empty optional when it is JSON null.
      Parameters:
      index - the element index
      Returns:
      the array value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • stringOpt

      Optional<String> stringOpt(int index)
      Returns the element at index as a string, or an empty optional when it is JSON null.
      Parameters:
      index - the element index
      Returns:
      the string value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • boolOpt

      Optional<Boolean> boolOpt(int index)
      Returns the element at index as a boolean, or an empty optional when it is JSON null.
      Parameters:
      index - the element index
      Returns:
      the boolean value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • decimalOpt

      Optional<BigDecimal> decimalOpt(int index)
      Returns the element at index as a number without precision loss.
      Parameters:
      index - the element index
      Returns:
      the decimal value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • intOpt

      OptionalInt intOpt(int index)
      Returns the element at index as an exact int.
      Parameters:
      index - the element index
      Returns:
      the int value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      IllegalArgumentException - if the value is not a number or is not exactly representable as an int

    • longOpt

      OptionalLong longOpt(int index)
      Returns the element at index as an exact long.
      Parameters:
      index - the element index
      Returns:
      the long value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      IllegalArgumentException - if the value is not a number or is not exactly representable as a long

    • doubleOpt

      OptionalDouble doubleOpt(int index)
      Returns the element at index converted to a finite double.
      Parameters:
      index - the element index
      Returns:
      the double value, or empty if null
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • objectValue

      default JsonObject objectValue(int index)
      Returns the required object element at index.
      Parameters:
      index - the element index
      Returns:
      the object value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • arrayValue

      default JsonArray arrayValue(int index)
      Returns the required array element at index.
      Parameters:
      index - the element index
      Returns:
      the array value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • stringValue

      default String stringValue(int index)
      Returns the required string element at index.
      Parameters:
      index - the element index
      Returns:
      the string value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • boolValue

      default boolean boolValue(int index)
      Returns the required boolean element at index.
      Parameters:
      index - the element index
      Returns:
      the boolean value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • decimalValue

      default BigDecimal decimalValue(int index)
      Returns the required number element at index without precision loss.
      Parameters:
      index - the element index
      Returns:
      the decimal value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • intValue

      default int intValue(int index)
      Returns the required exact int element at index.
      Parameters:
      index - the element index
      Returns:
      the int value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • longValue

      default long longValue(int index)
      Returns the required exact long element at index.
      Parameters:
      index - the element index
      Returns:
      the long value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • doubleValue

      default double doubleValue(int index)
      Returns the required finite double element at index.
      Parameters:
      index - the element index
      Returns:
      the double value
      Throws:
      IllegalArgumentException - if the element is JSON null
      IndexOutOfBoundsException - if the index is out of range

    • objectOr

      default JsonObject objectOr(int index, JsonObject fallback)
      Returns the object element at index or fallback when it is JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the object value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • arrayOr

      default JsonArray arrayOr(int index, JsonArray fallback)
      Returns the array element at index or fallback when it is JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the array value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • stringOr

      default String stringOr(int index, String fallback)
      Returns the string element at index or fallback when it is JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the string value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • boolOr

      default boolean boolOr(int index, boolean fallback)
      Returns the boolean element at index or fallback when it is JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the boolean value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • decimalOr

      default BigDecimal decimalOr(int index, BigDecimal fallback)
      Returns the decimal element at index or fallback when it is JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the decimal value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • intOr

      default int intOr(int index, int fallback)
      Returns the exact int element at index or fallback when JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the int value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • longOr

      default long longOr(int index, long fallback)
      Returns the exact long element at index or fallback when JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the long value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • doubleOr

      default double doubleOr(int index, double fallback)
      Returns the finite double element at index or fallback when JSON null.
      Parameters:
      index - the element index
      fallback - the fallback value
      Returns:
      the double value, or fallback
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • valuesAs

      <T> List<T> valuesAs(Class<T> element)
      Returns every element coerced to element.

      Supported element types: String, Boolean, BigDecimal, Integer, Long, Double, JsonObject, and JsonArray. A JSON null, wrong-typed, or overflowing element throws IllegalArgumentException naming its index. Bean and nested generic element types are not supported — decode the enclosing payload with a serde instead.

      Type Parameters:
      T - the element type
      Parameters:
      element - the element class
      Returns:
      an immutable list of the coerced elements
      Throws:
      IllegalArgumentException - if the element type is unsupported or an element cannot be coerced

    • asList

      @ExperimentalApi List<Object> asList()
      Returns an immutable list representation.
      Returns:
      the list view

    • of

      static JsonArray of(List<?> values)
      Creates an immutable array by recursively snapshotting JSON-compatible values.
      Parameters:
      values - the source list
      Returns:
      a new JSON array

    • empty

      static JsonArray empty()
      Returns an empty JSON array.
      Returns:
      the empty instance