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