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