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.service;
017
018import java.util.Map;
019
020/**
021 * Provides evaluation of expression language statements against a given context
022 *
023 * <p>
024 * Used within the UI framework to allow conditional logic to be configured through
025 * the XML which can alter the values of component properties
026 * </p>
027 * 
028 * @author Kuali Rice Team (rice.collab@kuali.org)
029 */
030public interface ExpressionEvaluatorService {
031
032    /**
033     * Evaluates any el expressions that are found as a string property value
034     * for the object
035     * 
036     * <p>
037     * Using reflection the properties for the object are retrieved and if of
038     * <code>String</code> type the corresponding value is retrieved. If the
039     * value is not empty and contains the el placeholder see
040     * {@link #containsElPlaceholder(String)} then the expression is evaluated
041     * using the given context object and parameters. The evaluated string is
042     * then set as the new property value, or in the case of a template
043     * (expression contained within a literal string), the expression part is
044     * replaced in the property value.
045     * </p>
046     * 
047     * <p>
048     * In addition to evaluating any property expressions, any configured
049     * <code>PropertyReplacer</code> for the object are also evaluated and if a
050     * match occurs those property replacements are made
051     * </p>
052     * 
053     * @param object
054     *            - object whose properties should be checked for expressions
055     *            and evaluated
056     * @param contextObject
057     *            - context object for the expression evaluations
058     * @param evaluationParameters
059     *            - map of parameters that may appear in expressions, the map
060     *            key gives the parameter name that may appear in the
061     *            expression, and the map value is the object that expression
062     *            should evaluate against when that name is found
063     */
064    public void evaluateObjectExpressions(Object object, Object contextObject, Map<String, Object> evaluationParameters);
065
066    /**
067     * Evaluates the given expression template string against the context object
068     * and map of parameters
069     * 
070     * <p>
071     * If the template string contains one or more el placeholders (see
072     * {@link #containsElPlaceholder(String)}), the expression contained within
073     * the placeholder will be evaluated and the corresponding value will be
074     * substituted back into the property value where the placeholder occurred.
075     * If no placeholders are found, the string will be returned unchanged
076     * </p>
077     * 
078     * @param contextObject
079     *            - context object for the expression evaluations
080     * @param evaluationParameters
081     *            - map of parameters that may appear in expressions, the map
082     *            key gives the parameter name that may appear in the
083     *            expression, and the map value is the object that expression
084     *            should evaluate against when that name is found
085     * @param expressionTemplate
086     *            - string that should be evaluated for el expressions
087     * @return String formed by replacing any el expressions in the original
088     *         expression template with their corresponding evaluation results
089     */
090    public String evaluateExpressionTemplate(Object contextObject, Map<String, Object> evaluationParameters,
091            String expressionTemplate);
092
093    /**
094     * Evaluates the given el expression against the content object and
095     * parameters, and returns the result of the evaluation
096     * 
097     * <p>
098     * The given expression string is assumed to be one el expression and should
099     * not contain the el placeholders. The returned result depends on the
100     * evaluation and what type is returns, for instance a boolean will be
101     * return for a boolean expression, or a string for string expression
102     * </p>
103     * 
104     * @param contextObject
105     *            - context object for the expression evaluations
106     * @param evaluationParameters
107     *            - map of parameters that may appear in expressions, the map
108     *            key gives the parameter name that may appear in the
109     *            expression, and the map value is the object that expression
110     *            should evaluate against when that name is found
111     * @param expression
112     *            - el expression to evaluate
113     * @return Object result of the expression evaluation
114     */
115    public Object evaluateExpression(Object contextObject, Map<String, Object> evaluationParameters, String expression);
116
117    /**
118     * Indicates whether or not the given string contains the el placholder
119     * (begin and end delimiters)
120     * 
121     * @param value
122     *            - String to check for contained placeholders
123     * @return boolean true if the string contains one or more placeholders,
124     *         false if it contains none
125     * @see org.kuali.rice.krad.uif.UifConstants.EL_PLACEHOLDER_PREFIX
126     * @see org.kuali.rice.krad.uif.UifConstants.EL_PLACEHOLDER_SUFFIX
127     */
128    public boolean containsElPlaceholder(String value);
129}