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: *
017: * $Header:$
018: */
019: package org.apache.beehive.netui.script;
020:
021: import javax.servlet.jsp.el.VariableResolver;
022:
023: /**
024: * Interface for implementing a runtime for evaluating expressions. An ExpressionEvaluator is
025: * used to execute <i>read</i> and <i>update</i> expressions. It also provides a set of methods
026: * for performing utility type operations on expressions.
027: */
028: public interface ExpressionEvaluator {
029:
030: /**
031: * Evaluate an expression and return the result.
032: *
033: * @param expression the expression to evaluate
034: * @param variableResolver the set of contexts that may be used in expression evaluation. This set
035: * is not necessarily complete as some objects that can be used as top-level expression contexts
036: * may be contained within an object available in this JavaBean.
037: * @throws ExpressionEvaluationException when an error occurs
038: */
039: public Object evaluateStrict(String expression,
040: VariableResolver variableResolver)
041: throws ExpressionEvaluationException;
042:
043: /**
044: * Update an expression with the given value. This will apply the parameter <code>value</code>
045: * to the object referenced by the expression <code>expression</code>. The <code>requestParameter</code>
046: * flag is used by a caller to restrict the set of contexts into which an update can occur on
047: * the request.
048: *
049: * @param expression the expression whose value to update
050: * @param value the new value for the update
051: * @param variableResolver the set of contexts that may be used in expression evaluation. This set
052: * is not necessarily complete as some objects that can be used as top-level expression contexts
053: * may be contained within an object available in this JavaBean.
054: * @param requestParameter a boolean that marks this update as occurring from data in the request, if
055: * <code>true</code> or simply as a regular update.
056: * @throws ExpressionUpdateException when an exception occurs updating a value
057: */
058: public void update(String expression, Object value,
059: VariableResolver variableResolver, boolean requestParameter)
060: throws ExpressionUpdateException;
061:
062: /**
063: * Change the evaluation context of an expression. This is used to rewrite some expressions
064: * that need to be qualified into a different context for evaluation. The context
065: * of an expression is its first identifier, up to the first delimiter.
066: *
067: * @param expression the expression whose context to change
068: * @param oldContext the old context to replace, if present
069: * @param newContext the new context to replace if the expression starts with the <code>oldContext</code>
070: * @param lookupIndex an index used to qualify an expression into an array look-up.
071: */
072: public String changeContext(String expression, String oldContext,
073: String newContext, int lookupIndex)
074: throws ExpressionEvaluationException;
075:
076: /**
077: * Qualify the expression into the given context. This will take the <code>expression</code>
078: * and simply qualify it into the new context <code>implicitObjectName</code>.
079: *
080: * @param implicitObjectName the new context
081: * @param expression the expression to qualify
082: * @return the new expression created by adding the implicit object name <code>implicitObjectName</code>
083: * to the expression string <code>expression</code>
084: * @throws ExpressionEvaluationException if an exception occurs qualifying the expression with the implict object name
085: */
086: public String qualify(String implicitObjectName, String expression)
087: throws ExpressionEvaluationException;
088:
089: /**
090: * Checks to see if a particular String is exactly an expression.
091: *
092: * @param expression the expression to check
093: * @return <code>true</code> if the expression is exactly an expression; <code>false</code> otherwise.
094: * @throws IllegalExpressionException if the given expression <code>expression</code> is not legal.
095: */
096: public boolean isExpression(String expression);
097:
098: /**
099: * Checks to see if a particular expression contains an expression. This method will return
100: * <code>true</code> if there is an expression surrounded by whitespace, other expressions,
101: * or literal text.
102: *
103: * @param expression the expression to check
104: * @return <code>true</code> if the expression contains an expression; <code>false</code> otherwise.
105: */
106: public boolean containsExpression(String expression);
107:
108: /**
109: * Parse an expression into its object representation as a {@link Expression}.
110: *
111: * @param expression the String expression to parse
112: * @return the parsed expression
113: */
114: public Expression parseExpression(String expression);
115: }
|