001    /**
002     * Copyright 2005-2012 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 org.kuali.rice.krad.uif.component.Configurable;
019    import org.kuali.rice.krad.uif.view.View;
020    
021    import java.util.Map;
022    
023    /**
024     * Provides evaluation of expression language statements against a given context
025     *
026     * <p>
027     * Used within the UI framework to allow conditional logic to be configured through
028     * the XML which can alter the values of component properties
029     * </p>
030     *
031     * @author Kuali Rice Team (rice.collab@kuali.org)
032     */
033    public interface ExpressionEvaluatorService {
034    
035        /**
036         * Indicator that can be added to a property name to indicate the expression result should be added to the
037         * property (assumed to be a collection) instead of replaced
038         */
039        public static String EMBEDDED_PROPERTY_NAME_ADD_INDICATOR = ".add";
040    
041        /**
042         * Evaluates any el expressions that are found as a string property value
043         * for the object
044         *
045         * <p>
046         * Using reflection the properties for the object are retrieved and if of
047         * <code>String</code> type the corresponding value is retrieved. If the
048         * value is not empty and contains the el placeholder see
049         * {@link #containsElPlaceholder(String)} then the expression is evaluated
050         * using the given context object and parameters. The evaluated string is
051         * then set as the new property value, or in the case of a template
052         * (expression contained within a literal string), the expression part is
053         * replaced in the property value.
054         * </p>
055         *
056         * <p>
057         * In addition to evaluating any property expressions, any configured
058         * <code>PropertyReplacer</code> for the object are also evaluated and if a
059         * match occurs those property replacements are made
060         * </p>
061         *
062         * @param view - view instance being rendered
063         * @param configurable - object whose properties should be checked for expressions
064         * and evaluated
065         * @param contextObject - context object for the expression evaluations
066         * @param evaluationParameters - map of parameters that may appear in expressions, the map
067         * key gives the parameter name that may appear in the
068         * expression, and the map value is the object that expression
069         * should evaluate against when that name is found
070         */
071        public void evaluateExpressionsOnConfigurable(View view, Configurable configurable, Object contextObject,
072                Map<String, Object> evaluationParameters);
073    
074        /**
075         * Evaluates the given expression template string against the context object
076         * and map of parameters
077         *
078         * <p>
079         * If the template string contains one or more el placeholders (see
080         * {@link #containsElPlaceholder(String)}), the expression contained within
081         * the placeholder will be evaluated and the corresponding value will be
082         * substituted back into the property value where the placeholder occurred.
083         * If no placeholders are found, the string will be returned unchanged
084         * </p>
085         *
086         * @param contextObject - context object for the expression evaluations
087         * @param evaluationParameters - map of parameters that may appear in expressions, the map
088         * key gives the parameter name that may appear in the
089         * expression, and the map value is the object that expression
090         * should evaluate against when that name is found
091         * @param expressionTemplate - string that should be evaluated for el expressions
092         * @return String formed by replacing any el expressions in the original
093         *         expression template with their corresponding evaluation results
094         */
095        public String evaluateExpressionTemplate(Object contextObject, Map<String, Object> evaluationParameters,
096                String expressionTemplate);
097    
098        /**
099         * 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    }