Package software.amazon.smithy.jmespath.evaluation

Interface JmespathRuntime<T>

All Superinterfaces:
Comparator<T>
All Known Implementing Classes:
LiteralExpressionJmespathRuntime
public interface JmespathRuntime<T> extends Comparator<T>
An interface to provide the operations needed for JMESPath expression evaluation based on any runtime representation of JSON values.

Several methods have default implementations that are at least correct, but implementors can override them with more efficient implementations.

In the documentation of the required behavior of each method, note that conditions like "if the value is NULL", refer to T value where typeOf(value) returns RuntimeType.NULL. A runtime may or may not use a Java `null` value for this purpose.

  • Method Details

    • typeOf

      RuntimeType typeOf(T value)
      Returns the basic type of the given value: NULL, BOOLEAN, STRING, NUMBER, OBJECT, or ARRAY.

      MUST NOT ever return EXPRESSION or ANY.

    • is

      default boolean is(T value, RuntimeType type)
      Shorthand for typeOf(value).equals(type).

    • isTruthy

      default boolean isTruthy(T value)
      Returns true iff the given value is truthy according to the JMESPath specification.

    • equal

      default boolean equal(T a, T b)
      Returns true iff the two given values are equal.

      Note that just calling Objects.equals() is generally not correct because it does not consider different Number representations of the same value the same.

    • compare

      default int compare(T a, T b)
      Specified by:
      compare in interface Comparator<T>

    • toString

      default String toString(T value)
      Returns a JSON string representation of the given value.

      Note the distinction between this method and asString(), which can be called only on STRINGs and just casts the value to a String.

    • createNull

      T createNull()
      Returns `null`.

      Runtimes may or may not use a Java null value to represent a JSON null value.

    • createBoolean

      T createBoolean(boolean b)
      Creates a BOOLEAN value.

    • asBoolean

      boolean asBoolean(T value)
      If the given value is a BOOLEAN, return it as a boolean. Otherwise, throws a JmespathException of type INVALID_TYPE.

    • createString

      T createString(String string)
      Creates a STRING value.

    • asString

      String asString(T value)
      If the given value is a STRING, return it as a String. Otherwise, throws a JmespathException of type INVALID_TYPE.

      Note the distinction between this method and toString(), which can be called on any value and produces a JSON string.

    • createNumber

      T createNumber(Number value)
      Creates a NUMBER value.

    • numberType

      NumberType numberType(T value)
      Returns the type of Number that asNumber() will produce for this value. Will be more efficient for some runtimes than checking the class of asNumber().

    • asNumber

      Number asNumber(T value)
      If the given value is a NUMBER, return it as a Number. Otherwise, throws a JmespathException of type INVALID_TYPE.

    • arrayBuilder

      JmespathRuntime.ArrayBuilder<T> arrayBuilder()
      Creates a new ArrayBuilder.

    • element

      T element(T array, int index)
      If the given value is an ARRAY, returns the element at the given index. Otherwise, throws a JmespathException of type INVALID_TYPE.

    • slice

      default T slice(T array, int start, int stop, int step)
      If the given value is an ARRAY, returns the specified slice. Otherwise, throws a JmespathException of type INVALID_TYPE.

      Start and stop will always be non-negative, and step will always be non-zero.

    • objectBuilder

      JmespathRuntime.ObjectBuilder<T> objectBuilder()
      Creates a new ObjectBuilder.

    • value

      T value(T object, T key)
      If the given value is an OBJECT, returns the value mapped to the given key. Otherwise, returns NULL.

    • length

      int length(T value)
      Returns the number of elements in an ARRAY or the number of keys in an OBJECT. Otherwise, throws a JmespathException of type INVALID_TYPE.

    • asIterable

      Iterable<? extends T> asIterable(T value)
      Iterate over the elements of an ARRAY or the keys of an OBJECT. Otherwise, throws a JmespathException of type INVALID_TYPE.