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