1 /**
2 * Copyright 2005-2012 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 org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean;
19 import org.kuali.rice.krad.uif.view.View;
20
21 import java.util.Map;
22
23 /**
24 * Provides evaluation of expression language statements against a given context
25 *
26 * <p>
27 * Used within the UI framework to allow conditional logic to be configured through
28 * the XML which can alter the values of component properties
29 * </p>
30 *
31 * @author Kuali Rice Team (rice.collab@kuali.org)
32 */
33 public interface ExpressionEvaluatorService {
34
35 /**
36 * Indicator that can be added to a property name to indicate the expression result should be added to the
37 * property (assumed to be a collection) instead of replaced
38 */
39 public static String EMBEDDED_PROPERTY_NAME_ADD_INDICATOR = ".add";
40
41 /**
42 * Evaluates any el expressions that are found as a string property value
43 * for the object
44 *
45 * <p>
46 * Using reflection the properties for the object are retrieved and if of
47 * <code>String</code> type the corresponding value is retrieved. If the
48 * value is not empty and contains the el placeholder see
49 * {@link #containsElPlaceholder(String)} then the expression is evaluated
50 * using the given context object and parameters. The evaluated string is
51 * then set as the new property value, or in the case of a template
52 * (expression contained within a literal string), the expression part is
53 * replaced in the property value.
54 * </p>
55 *
56 * <p>
57 * In addition to evaluating any property expressions, any configured
58 * <code>PropertyReplacer</code> for the object are also evaluated and if a
59 * match occurs those property replacements are made
60 * </p>
61 *
62 * @param view - view instance being rendered
63 * @param expressionConfigurable - object whose properties should be checked for expressions
64 * and evaluated
65 * @param contextObject - context object for the expression evaluations
66 * @param evaluationParameters - map of parameters that may appear in expressions, the map
67 * key gives the parameter name that may appear in the
68 * expression, and the map value is the object that expression
69 * should evaluate against when that name is found
70 */
71 public void evaluateExpressionsOnConfigurable(View view, UifDictionaryBean expressionConfigurable, Object contextObject,
72 Map<String, Object> evaluationParameters);
73
74 /**
75 * Evaluates the given expression template string against the context object
76 * and map of parameters
77 *
78 * <p>
79 * If the template string contains one or more el placeholders (see
80 * {@link #containsElPlaceholder(String)}), the expression contained within
81 * the placeholder will be evaluated and the corresponding value will be
82 * substituted back into the property value where the placeholder occurred.
83 * If no placeholders are found, the string will be returned unchanged
84 * </p>
85 *
86 * @param contextObject - context object for the expression evaluations
87 * @param evaluationParameters - map of parameters that may appear in expressions, the map
88 * key gives the parameter name that may appear in the
89 * expression, and the map value is the object that expression
90 * should evaluate against when that name is found
91 * @param expressionTemplate - string that should be evaluated for el expressions
92 * @return String formed by replacing any el expressions in the original
93 * expression template with their corresponding evaluation results
94 */
95 public String evaluateExpressionTemplate(Object contextObject, Map<String, Object> evaluationParameters,
96 String expressionTemplate);
97
98 /**
99 * Evaluates the given el expression against the content object and
100 * parameters, and returns the result of the evaluation
101 *
102 * <p>
103 * The given expression string is assumed to be one el expression and should
104 * not contain the el placeholders. The returned result depends on the
105 * evaluation and what type is returns, for instance a boolean will be
106 * return for a boolean expression, or a string for string expression
107 * </p>
108 *
109 * @param contextObject - context object for the expression evaluations
110 * @param evaluationParameters - map of parameters that may appear in expressions, the map
111 * key gives the parameter name that may appear in the
112 * expression, and the map value is the object that expression
113 * should evaluate against when that name is found
114 * @param expression - el expression to evaluate
115 * @return Object result of the expression evaluation
116 */
117 public Object evaluateExpression(Object contextObject, Map<String, Object> evaluationParameters, String expression);
118
119 /**
120 * Indicates whether or not the given string contains the el placholder
121 * (begin and end delimiters)
122 *
123 * @param value - String to check for contained placeholders
124 * @return boolean true if the string contains one or more placeholders,
125 * false if it contains none
126 * @see org.kuali.rice.krad.uif.UifConstants.EL_PLACEHOLDER_PREFIX
127 * @see org.kuali.rice.krad.uif.UifConstants.EL_PLACEHOLDER_SUFFIX
128 */
129 public boolean containsElPlaceholder(String value);
130
131 /**
132 * Adjusts the property expressions for a given object
133 *
134 * <p>
135 * The {@link org.kuali.rice.krad.uif.UifConstants#NO_BIND_ADJUST_PREFIX} prefix will be removed
136 * as this is a placeholder indicating that the property is directly on the form.
137 * The {@link org.kuali.rice.krad.uif.UifConstants#FIELD_PATH_BIND_ADJUST_PREFIX} prefix will be replaced by
138 * the object's field path - this is only applicable to DataFields. The
139 * {@link org.kuali.rice.krad.uif.UifConstants#DEFAULT_PATH_BIND_ADJUST_PREFIX} prefix will be replaced
140 * by the view's default path if it is set.
141 * </p>
142 *
143 * @param view - the parent view of the object
144 * @param object - Object to adjust property expressions on
145 * @param expression - The expression to adjust
146 * @return the adjusted expression String
147 */
148 public String replaceBindingPrefixes(View view, Object object, String expression);
149 }