1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.core.metapath;
7   
8   import java.util.List;
9   
10  import dev.metaschema.core.metapath.cst.IExpressionVisitor;
11  import dev.metaschema.core.metapath.item.IItem;
12  import dev.metaschema.core.metapath.item.ISequence;
13  import edu.umd.cs.findbugs.annotations.NonNull;
14  
15  /**
16   * The common interface of all Metapath expression nodes.
17   * <p>
18   * Metapath expression nodes represent the different types of expressions that
19   * can appear in a Metapath query, forming a composite structure that can be
20   * traversed and evaluated.
21   *
22   * @since 1.0.0
23   * @see dev.metaschema.core.metapath.cst.IExpressionVisitor
24   */
25  public interface IExpression {
26    /**
27     * Get the text for the expression.
28     *
29     * @return the expression text
30     */
31    @NonNull
32    String getPath();
33  
34    /**
35     * Retrieve the child expressions associated with this expression.
36     *
37     * @return a list of expressions, which may be empty
38     */
39    @NonNull
40    List<? extends IExpression> getChildren();
41  
42    /**
43     * The minimum expected result type to be produced when evaluating the
44     * expression. The result may be a sub-class or sub-interface of this value.
45     *
46     * @return the base result type
47     */
48    @NonNull
49    default Class<? extends IItem> getBaseResultType() {
50      return IItem.class;
51    }
52  
53    /**
54     * The expected result type produced by evaluating the expression. The result
55     * must be the same or a sub-class or sub-interface of the value provided by
56     * {@link #getBaseResultType()}.
57     * <p>
58     * This method can be overloaded to provide static analysis of the expression to
59     * determine a more specific result type.
60     *
61     * @return the result type
62     */
63    @NonNull
64    default Class<? extends IItem> getStaticResultType() {
65      return getBaseResultType();
66    }
67  
68    /**
69     * Produce a string representation of this expression including the expression's
70     * name.
71     * <p>
72     * This method can be overloaded to provide a more appropriate representation of
73     * the expression.
74     *
75     * @return a string representing the data elements of the expression
76     */
77    @SuppressWarnings("null")
78    @NonNull
79    default String toCSTString() {
80      return String.format("%s[]", getClass().getName());
81    }
82  
83    /**
84     * Provides a double dispatch callback for visitor handling.
85     *
86     * @param dynamicContext
87     *          the dynamic evaluation context
88     * @param focus
89     *          the outer focus of the expression
90     * @return the result of evaluation
91     */
92    @NonNull
93    ISequence<? extends IItem> accept(@NonNull DynamicContext dynamicContext, @NonNull ISequence<?> focus);
94  
95    /**
96     * Provides a double dispatch callback for visitor handling.
97     *
98     * @param <RESULT>
99     *          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 }