001/**
002 * Copyright 2005-2016 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.krad.uif.view;
017
018import org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean;
019
020import java.util.Map;
021
022/**
023 * Provides evaluation of expression language statements against a given context
024 *
025 * <p>
026 * Used within the UI framework to allow conditional logic to be configured through
027 * the XML which can alter the values of component properties
028 * </p>
029 *
030 * @author Kuali Rice Team (rice.collab@kuali.org)
031 */
032public interface ExpressionEvaluator {
033
034    /**
035     * Indicator that can be added to a property name to indicate the expression result should be added to the
036     * property (assumed to be a collection) instead of replaced
037     */
038    public static String EMBEDDED_PROPERTY_NAME_ADD_INDICATOR = ".add";
039
040    /**
041     * Initializes the expression context for the given expression context object
042     *
043     * <p>
044     * The object given here will form the default context for expression terms (terms without any
045     * variable prefix)
046     * </p>
047     *
048     * @param contextObject instance of an Object
049     */
050    public void initializeEvaluationContext(Object contextObject);
051
052    /**
053     * Evaluates any el expressions that are found as a string property value
054     * for the object
055     *
056     * <p>
057     * Using reflection the properties for the object are retrieved and if of
058     * <code>String</code> type the corresponding value is retrieved. If the
059     * value is not empty and contains the el placeholder see
060     * {@link #containsElPlaceholder(String)} then the expression is evaluated
061     * using the given context object and parameters. The evaluated string is
062     * then set as the new property value, or in the case of a template
063     * (expression contained within a literal string), the expression part is
064     * replaced in the property value.
065     * </p>
066     *
067     * <p>
068     * In addition to evaluating any property expressions, any configured
069     * <code>PropertyReplacer</code> for the object are also evaluated and if a
070     * match occurs those property replacements are made
071     * </p>
072     *
073     * @param view view instance being rendered
074     * @param expressionConfigurable object whose properties should be checked for expressions
075     * and evaluated
076     * @param evaluationParameters map of parameters that may appear in expressions, the map
077     * key gives the parameter name that may appear in the expression, and the map value is the object that expression
078     * should evaluate against when that name is found
079     */
080    public void evaluateExpressionsOnConfigurable(View view, UifDictionaryBean expressionConfigurable,
081            Map<String, Object> evaluationParameters);
082
083    /**
084     * Evaluates the given expression template string against the context object
085     * and map of parameters
086     *
087     * <p>
088     * If the template string contains one or more el placeholders (see
089     * {@link #containsElPlaceholder(String)}), the expression contained within
090     * the placeholder will be evaluated and the corresponding value will be
091     * substituted back into the property value where the placeholder occurred.
092     * If no placeholders are found, the string will be returned unchanged
093     * </p>
094     *
095     * @param evaluationParameters map of parameters that may appear in expressions, the map
096     * key gives the parameter name that may appear in the expression, and the map value is the object that expression
097     * should evaluate against when that name is found
098     * @param expressionTemplate string that should be evaluated for el expressions
099     * @return String formed by replacing any el expressions in the original expression template with
100     * their corresponding evaluation results
101     */
102    public String evaluateExpressionTemplate(Map<String, Object> evaluationParameters, String expressionTemplate);
103
104    /**
105     * Evaluates the configured expression for the given property name (if not exists) on the given configurable
106     *
107     * @param view view instance the configurable is associated with, used to adjust binding prefixes
108     * @param evaluationParameters map that will be exposed as EL parameters
109     * @param expressionConfigurable configurable object to pull and evaluate the expression on
110     * @param propertyName name of the property whose expression should be evaluated
111     * @param removeExpression boolean that indicates whether the expression should be removed after evaluation
112     */
113    public void evaluatePropertyExpression(View view, Map<String, Object> evaluationParameters,
114            UifDictionaryBean expressionConfigurable, String propertyName, boolean removeExpression);
115
116    /**
117     * Evaluates the given el expression against the content object and
118     * parameters, and returns the result of the evaluation
119     *
120     * <p>
121     * The given expression string is assumed to be one el expression and should
122     * not contain the el placeholders. The returned result depends on the
123     * evaluation and what type is returns, for instance a boolean will be
124     * return for a boolean expression, or a string for string expression
125     * </p>
126     *
127     * @param evaluationParameters map of parameters that may appear in expressions, the map
128     * key gives the parameter name that may appear in the expression, and the map value is the object that expression
129     * should evaluate against when that name is found
130     * @param expression el expression to evaluate
131     * @return Object result of the expression evaluation
132     */
133    public Object evaluateExpression(Map<String, Object> evaluationParameters, String expression);
134
135    /**
136     * Indicates whether or not the given string contains the el placeholder
137     * (begin and end delimiters)
138     *
139     * @param value String to check for contained placeholders
140     * @return boolean true if the string contains one or more placeholders, false if it contains none
141     * @see org.kuali.rice.krad.uif.UifConstants#EL_PLACEHOLDER_PREFIX
142     * @see org.kuali.rice.krad.uif.UifConstants#EL_PLACEHOLDER_SUFFIX
143     */
144    public boolean containsElPlaceholder(String value);
145
146    /**
147     * Adjusts the property expressions for a given object
148     *
149     * <p>
150     * The {@link org.kuali.rice.krad.uif.UifConstants#NO_BIND_ADJUST_PREFIX}  prefix will be removed
151     * as this is a placeholder indicating that the property is directly on the form.
152     * The {@link org.kuali.rice.krad.uif.UifConstants#FIELD_PATH_BIND_ADJUST_PREFIX} prefix will be replaced by
153     * the object's field path - this is only applicable to DataFields. The
154     * {@link org.kuali.rice.krad.uif.UifConstants#DEFAULT_PATH_BIND_ADJUST_PREFIX} prefix will be replaced
155     * by the view's default path if it is set.
156     * </p>
157     *
158     * @param view the parent view of the object
159     * @param object Object to adjust property expressions on
160     * @param expression The expression to adjust
161     * @return the adjusted expression String
162     */
163    public String replaceBindingPrefixes(View view, Object object, String expression);
164}