001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.scxml2;
018
019/**
020 * Interface for a component that may be used by the SCXML engines to
021 * evaluate the expressions within the SCXML document.
022 *
023 */
024public interface Evaluator {
025
026    /** SCXML 1.0 Null Data Model name **/
027    String NULL_DATA_MODEL = "null";
028
029    /** SCXML 1.0 ECMAScript Data Model name **/
030    String ECMASCRIPT_DATA_MODEL = "ecmascript";
031
032    /** SCXML 1.0 XPath Data Model name **/
033    String XPATH_DATA_MODEL = "xpath";
034
035    /** Default Data Model name **/
036    String DEFAULT_DATA_MODEL = "";
037
038    /**
039     * The allowable types of <assign/> including and in particular when using XPath
040     */
041    enum AssignType {
042
043        REPLACE_CHILDREN("replacechildren"),
044        FIRST_CHILD("firstchild"),
045        LAST_CHILD("lastchild"),
046        PREVIOUS_SIBLING("previoussibling"),
047        NEXT_SIBLING("nextsibling"),
048        REPLACE("replace"),
049        DELETE("delete"),
050        ADD_ATTRIBUTE("addattribute");
051
052        private final String value;
053
054        private AssignType(String value) {
055            this.value = value;
056        }
057
058        public String value() {
059            return value;
060        }
061
062        public static AssignType fromValue(String value) {
063            for (AssignType type : AssignType.values()) {
064                if (type.value().equals(value)) {
065                    return type;
066                }
067            }
068            return null;
069        }
070    }
071
072    /**
073     * Get the datamodel type supported by this Evaluator
074     * @return The supported datamodel type
075     */
076    String getSupportedDatamodel();
077
078    /**
079     * Evaluate an expression returning a data value
080     *
081     * @param ctx variable context
082     * @param expr expression
083     * @return the result of the evaluation
084     * @throws SCXMLExpressionException A malformed expression exception
085     */
086    Object eval(Context ctx, String expr)
087    throws SCXMLExpressionException;
088
089    /**
090     * Evaluate a condition.
091     * Manifests as "cond" attributes of &lt;transition&gt;,
092     * &lt;if&gt; and &lt;elseif&gt; elements.
093     *
094     * @param ctx variable context
095     * @param expr expression
096     * @return true/false
097     * @throws SCXMLExpressionException A malformed expression exception
098     */
099    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