View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.scxml2;
18  
19  /**
20   * Interface for a component that may be used by the SCXML engines to
21   * evaluate the expressions within the SCXML document.
22   *
23   */
24  public interface Evaluator {
25  
26      /** SCXML 1.0 Null Data Model name **/
27      String NULL_DATA_MODEL = "null";
28  
29      /** SCXML 1.0 ECMAScript Data Model name **/
30      String ECMASCRIPT_DATA_MODEL = "ecmascript";
31  
32      /** SCXML 1.0 XPath Data Model name **/
33      String XPATH_DATA_MODEL = "xpath";
34  
35      /** Default Data Model name **/
36      String DEFAULT_DATA_MODEL = "";
37  
38      /**
39       * The allowable types of <assign/> including and in particular when using XPath
40       */
41      enum AssignType {
42  
43          REPLACE_CHILDREN("replacechildren"),
44          FIRST_CHILD("firstchild"),
45          LAST_CHILD("lastchild"),
46          PREVIOUS_SIBLING("previoussibling"),
47          NEXT_SIBLING("nextsibling"),
48          REPLACE("replace"),
49          DELETE("delete"),
50          ADD_ATTRIBUTE("addattribute");
51  
52          private final String value;
53  
54          private AssignType(String value) {
55              this.value = value;
56          }
57  
58          public String value() {
59              return value;
60          }
61  
62          public static AssignType fromValue(String value) {
63              for (AssignType type : AssignType.values()) {
64                  if (type.value().equals(value)) {
65                      return type;
66                  }
67              }
68              return null;
69          }
70      }
71  
72      /**
73       * Get the datamodel type supported by this Evaluator
74       * @return The supported datamodel type
75       */
76      String getSupportedDatamodel();
77  
78      /**
79       * Evaluate an expression returning a data value
80       *
81       * @param ctx variable context
82       * @param expr expression
83       * @return the result of the evaluation
84       * @throws SCXMLExpressionException A malformed expression exception
85       */
86      Object eval(Context ctx, String expr)
87      throws SCXMLExpressionException;
88  
89      /**
90       * Evaluate a condition.
91       * Manifests as "cond" attributes of &lt;transition&gt;,
92       * &lt;if&gt; and &lt;elseif&gt; elements.
93       *
94       * @param ctx variable context
95       * @param expr expression
96       * @return true/false
97       * @throws SCXMLExpressionException A malformed expression exception
98       */
99      Boolean evalCond(Context ctx, String expr)
100     throws SCXMLExpressionException;
101 
102     /**
103      * Evaluate a location that returns a data assignable reference or list of references.
104      * Manifests as "location" attributes of &lt;assign&gt; element.
105      *
106      * @param ctx variable context
107      * @param expr expression
108      * @return The location result.
109      * @throws SCXMLExpressionException A malformed expression exception
110      */
111     Object evalLocation(Context ctx, String expr)
112     throws SCXMLExpressionException;
113 
114     /**
115      * Assigns data to a location
116      *
117      * @param ctx variable context
118      * @param location location expression
119      * @param data the data to assign.
120      * @param type the type of assignment to perform, null assumes {@link AssignType#REPLACE_CHILDREN}
121      * @param attr the name of the attribute to add when using type {@link AssignType#ADD_ATTRIBUTE}
122      * @throws SCXMLExpressionException A malformed expression exception
123      */
124     void evalAssign(Context ctx, String location, Object data, AssignType type, String attr)
125             throws SCXMLExpressionException;
126 
127     /**
128      * Evaluate a script.
129      * Manifests as &lt;script&gt; element.
130      *
131      * @param ctx variable context
132      * @param script The script
133      * @return The result of the script execution.
134      * @throws SCXMLExpressionException A malformed script
135      */
136     Object evalScript(Context ctx, String script)
137     throws SCXMLExpressionException;
138 
139     /**
140      * Create a new child context.
141      *
142      * @param parent parent context
143      * @return new child context
144      */
145     Context newContext(Context parent);
146 
147 }
148