001 /**
002 * Copyright 2005-2014 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 */
016 package org.kuali.rice.krad.uif.service;
017
018 import 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 */
030 public 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 }