1 /*
2 * Copyright 2011 The Kuali Foundation Licensed under the Educational Community
3 * License, Version 1.0 (the "License"); you may not use this file except in
4 * compliance with the License. You may obtain a copy of the License at
5 * http://www.opensource.org/licenses/ecl1.php Unless required by applicable law
6 * or agreed to in writing, software distributed under the License is
7 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
8 * KIND, either express or implied. See the License for the specific language
9 * governing permissions and limitations under the License.
10 */
11 package org.kuali.rice.krad.uif.service;
12
13 import java.util.Map;
14
15 /**
16 * Provides evaluation of expression language statements against a given context
17 *
18 * <p>
19 * Used within the UI framework to allow conditional logic to be configured through
20 * the XML which can alter the values of component properties
21 * </p>
22 *
23 * @author Kuali Rice Team (rice.collab@kuali.org)
24 */
25 public interface ExpressionEvaluatorService {
26
27 /**
28 * Evaluates any el expressions that are found as a string property value
29 * for the object
30 *
31 * <p>
32 * Using reflection the properties for the object are retrieved and if of
33 * <code>String</code> type the corresponding value is retrieved. If the
34 * value is not empty and contains the el placeholder see
35 * {@link #containsElPlaceholder(String)} then the expression is evaluated
36 * using the given context object and parameters. The evaluated string is
37 * then set as the new property value, or in the case of a template
38 * (expression contained within a literal string), the expression part is
39 * replaced in the property value.
40 * </p>
41 *
42 * <p>
43 * In addition to evaluating any property expressions, any configured
44 * <code>PropertyReplacer</code> for the object are also evaluated and if a
45 * match occurs those property replacements are made
46 * </p>
47 *
48 * @param object
49 * - object whose properties should be checked for expressions
50 * and evaluated
51 * @param contextObject
52 * - context object for the expression evaluations
53 * @param evaluationParameters
54 * - map of parameters that may appear in expressions, the map
55 * key gives the parameter name that may appear in the
56 * expression, and the map value is the object that expression
57 * should evaluate against when that name is found
58 */
59 public void evaluateObjectExpressions(Object object, Object contextObject, Map<String, Object> evaluationParameters);
60
61 /**
62 * Evaluates the given expression template string against the context object
63 * and map of parameters
64 *
65 * <p>
66 * If the template string contains one or more el placeholders (see
67 * {@link #containsElPlaceholder(String)}), the expression contained within
68 * the placeholder will be evaluated and the corresponding value will be
69 * substituted back into the property value where the placeholder occurred.
70 * If no placeholders are found, the string will be returned unchanged
71 * </p>
72 *
73 * @param contextObject
74 * - context object for the expression evaluations
75 * @param evaluationParameters
76 * - map of parameters that may appear in expressions, the map
77 * key gives the parameter name that may appear in the
78 * expression, and the map value is the object that expression
79 * should evaluate against when that name is found
80 * @param expressionTemplate
81 * - string that should be evaluated for el expressions
82 * @return String formed by replacing any el expressions in the original
83 * expression template with their corresponding evaluation results
84 */
85 public String evaluateExpressionTemplate(Object contextObject, Map<String, Object> evaluationParameters,
86 String expressionTemplate);
87
88 /**
89 * Evaluates the given el expression against the content object and
90 * parameters, and returns the result of the evaluation
91 *
92 * <p>
93 * The given expression string is assumed to be one el expression and should
94 * not contain the el placeholders. The returned result depends on the
95 * evaluation and what type is returns, for instance a boolean will be
96 * return for a boolean expression, or a string for string expression
97 * </p>
98 *
99 * @param contextObject
100 * - context object for the expression evaluations
101 * @param evaluationParameters
102 * - map of parameters that may appear in expressions, the map
103 * key gives the parameter name that may appear in the
104 * expression, and the map value is the object that expression
105 * should evaluate against when that name is found
106 * @param expression
107 * - el expression to evaluate
108 * @return Object result of the expression evaluation
109 */
110 public Object evaluateExpression(Object contextObject, Map<String, Object> evaluationParameters, String expression);
111
112 /**
113 * Indicates whether or not the given string contains the el placholder
114 * (begin and end delimiters)
115 *
116 * @param value
117 * - String to check for contained placeholders
118 * @return boolean true if the string contains one or more placeholders,
119 * false if it contains none
120 * @see org.kuali.rice.krad.uif.UifConstants.EL_PLACEHOLDER_PREFIX
121 * @see org.kuali.rice.krad.uif.UifConstants.EL_PLACEHOLDER_SUFFIX
122 */
123 public boolean containsElPlaceholder(String value);
124 }