Interface BuildingFunctionExtension

public interface BuildingFunctionExtension

A function extension that can make new JSON values (RFC 9535, Section 2.4). It runs only with a model that also implements JsonFactory.

A building extension can have each signature. Each ValueType argument is a node: the evaluator builds a literal of the query, for example 'abc', with the factory of the model. A ValueType result can be a new node from the factory, for example a new array.

// upper(ValueType): ValueType. The upper case of a string, or Nothing for other values.
// It makes a new string, so it needs a model that can build nodes.
static final class Upper implements BuildingFunctionExtension {

    static final FunctionSignature SIGNATURE =
            new FunctionSignature("upper", FunctionType.VALUE, List.of(FunctionType.VALUE));

    @Override
    public FunctionSignature signature() {
        return SIGNATURE;
    }

    @Override
    public <N, M extends JsonModel<N> & JsonFactory<N>> Instance<N> apply(List<Instance<N>> arguments, M model) {
        // A ValueType argument is a node. A literal such as 'abc' arrives as a built node.
        if (arguments.getFirst() instanceof Instance.ValueInstance<N>(Maybe.Some<N>(N node))
                && model.kind(node) == JsonKind.STRING) {
            String upper = JsonString.copyOf(model.stringValue(node)).toUpperCase(Locale.ROOT);
            return new Instance.ValueInstance<>(Maybe.some(model.string(JsonString.of(upper))));
        }
        return new Instance.ValueInstance<>(Maybe.none());
    }
}

JsonPathEvaluator.withFunctions(List, List) registers building extensions. The result is a BuildingEvaluator, which accepts only models that implement JsonModel and JsonFactory.

A NodesType result must have nodes of the query argument with their paths, not built nodes. The rules of FunctionExtension also apply.

  • Method Details

    • signature

      FunctionSignature signature()
      Returns the signature. The parser that makes the queries must know the same signature.
      Returns:
      the signature

    • apply

      <N, M extends JsonModel<N> & JsonFactory<N>> Instance<N> apply(List<Instance<N>> arguments, M model)
      Applies the function.
      Type Parameters:
      N - the node type of the JSON model
      M - the type of the model
      Parameters:
      arguments - one instance for each parameter, of the declared type of the parameter
      model - the model of the query argument, to read and build nodes
      Returns:
      the result, an instance of the declared result type