001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.core.metapath;
007
008import java.util.List;
009
010import dev.metaschema.core.metapath.cst.IExpressionVisitor;
011import dev.metaschema.core.metapath.item.IItem;
012import dev.metaschema.core.metapath.item.ISequence;
013import edu.umd.cs.findbugs.annotations.NonNull;
014
015/**
016 * The common interface of all Metapath expression nodes.
017 * <p>
018 * Metapath expression nodes represent the different types of expressions that
019 * can appear in a Metapath query, forming a composite structure that can be
020 * traversed and evaluated.
021 *
022 * @since 1.0.0
023 * @see dev.metaschema.core.metapath.cst.IExpressionVisitor
024 */
025public interface IExpression {
026  /**
027   * Get the text for the expression.
028   *
029   * @return the expression text
030   */
031  @NonNull
032  String getPath();
033
034  /**
035   * Retrieve the child expressions associated with this expression.
036   *
037   * @return a list of expressions, which may be empty
038   */
039  @NonNull
040  List<? extends IExpression> getChildren();
041
042  /**
043   * The minimum expected result type to be produced when evaluating the
044   * expression. The result may be a sub-class or sub-interface of this value.
045   *
046   * @return the base result type
047   */
048  @NonNull
049  default Class<? extends IItem> getBaseResultType() {
050    return IItem.class;
051  }
052
053  /**
054   * The expected result type produced by evaluating the expression. The result
055   * must be the same or a sub-class or sub-interface of the value provided by
056   * {@link #getBaseResultType()}.
057   * <p>
058   * This method can be overloaded to provide static analysis of the expression to
059   * determine a more specific result type.
060   *
061   * @return the result type
062   */
063  @NonNull
064  default Class<? extends IItem> getStaticResultType() {
065    return getBaseResultType();
066  }
067
068  /**
069   * Produce a string representation of this expression including the expression's
070   * name.
071   * <p>
072   * This method can be overloaded to provide a more appropriate representation of
073   * the expression.
074   *
075   * @return a string representing the data elements of the expression
076   */
077  @SuppressWarnings("null")
078  @NonNull
079  default String toCSTString() {
080    return String.format("%s[]", getClass().getName());
081  }
082
083  /**
084   * Provides a double dispatch callback for visitor handling.
085   *
086   * @param dynamicContext
087   *          the dynamic evaluation context
088   * @param focus
089   *          the outer focus of the expression
090   * @return the result of evaluation
091   */
092  @NonNull
093  ISequence<? extends IItem> accept(@NonNull DynamicContext dynamicContext, @NonNull ISequence<?> focus);
094
095  /**
096   * Provides a double dispatch callback for visitor handling.
097   *
098   * @param <RESULT>
099   *          the type of the evaluation result
100   * @param <CONTEXT>
101   *          the type of the visitor context
102   * @param visitor
103   *          the visitor calling this method
104   * @param context
105   *          the visitor context
106   * @return the result of evaluation
107   */
108  <RESULT, CONTEXT> RESULT accept(@NonNull IExpressionVisitor<RESULT, CONTEXT> visitor, @NonNull CONTEXT context);
109}