1 /* 2 * Copyright (c) MuleSoft, Inc. All rights reserved. http://www.mulesoft.com 3 * The software in this package is published under the terms of the CPAL v1.0 4 * license, a copy of which has been included with this distribution in the 5 * LICENSE.txt file. 6 */ 7 package org.mule.api.expression; 8 9 import org.mule.api.MuleMessage; 10 11 /** 12 * Provides universal access for evaluating expressions embedded in Mule configurations, such as Xml, Java, 13 * scripting and annotations. 14 * <p/> 15 * Users can register or unregister {@link ExpressionEvaluator} through this interface. 16 */ 17 public interface ExpressionManager 18 { 19 String DEFAULT_EXPRESSION_PREFIX = "#["; 20 String DEFAULT_EXPRESSION_POSTFIX = "]"; 21 22 public void registerEvaluator(ExpressionEvaluator evaluator); 23 24 /** 25 * Checks whether an evaluator is registered with the manager 26 * 27 * @param name the name of the expression evaluator 28 * @return true if the evaluator is registered with the manager, false otherwise 29 */ 30 public boolean isEvaluatorRegistered(String name); 31 32 /** 33 * Removes the evaluator with the given name 34 * 35 * @param name the name of the evaluator to remove 36 * @return the evaluator that was removed. This will be null if the evaluator was not registered 37 */ 38 public ExpressionEvaluator unregisterEvaluator(String name); 39 40 public void registerEnricher(ExpressionEnricher enricher); 41 42 /** 43 * Checks whether an enricher is registered with the manager 44 * 45 * @param name the name of the expression enricher 46 * @return true if the enricher is registered with the manager, false otherwise 47 */ 48 public boolean isEnricherRegistered(String name); 49 50 /** 51 * Removes the enricher with the given name 52 * 53 * @param name the name of the enricher to remove 54 * @return the enricher that was removed. This will be null if the enricher was not registered 55 */ 56 public ExpressionEnricher unregisterEnricher(String name); 57 58 /** 59 * Evaluates the given expression. The expression should be a single expression definition with or without 60 * enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" are both valid. For situations where 61 * one or more expressions need to be parsed within a single text, the {@link #parse(String,org.mule.api.MuleMessage,boolean)} 62 * method should be used since it will iterate through all expressions in a string. 63 * 64 * @param expression a single expression i.e. xpath://foo 65 * @param message The current message being processed 66 * @return the result of the evaluation 67 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 68 * 'failIfNull is set to true. 69 */ 70 public Object evaluate(String expression, MuleMessage message) throws ExpressionRuntimeException; 71 72 /** 73 * Evaluates the given expression. The expression should be a single expression definition with or without 74 * enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" are both valid. For situations where 75 * one or more expressions need to be parsed within a single text, the {@link #parse(String,org.mule.api.MuleMessage,boolean)} 76 * method should be used since it will iterate through all expressions in a string. 77 * 78 * @param expression a single expression i.e. xpath://foo 79 * @param message The current message being processed 80 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 81 * null. @return the result of the evaluation 82 * @return the parsered expression string 83 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 84 * 'failIfNull is set to true. 85 */ 86 public Object evaluate(String expression, MuleMessage message, boolean failIfNull) throws ExpressionRuntimeException; 87 88 /** 89 * Evaluates the given expression. The expression should be a single expression definition with or without 90 * enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" are both valid. For situations where 91 * one or more expressions need to be parsed within a single text, the {@link #parse(String,org.mule.api.MuleMessage,boolean)} 92 * method should be used since it will iterate through all expressions in a string. 93 * 94 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 95 * @param evaluator the evaluator to use when executing the expression 96 * @param message The current message being processed 97 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 98 * null. @return the result of the evaluation 99 * @return the parsered expression string 100 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 101 * 'failIfNull is set to true. 102 */ 103 public Object evaluate(String expression, String evaluator, MuleMessage message, boolean failIfNull) throws ExpressionRuntimeException; 104 105 /** 106 * Evaluates the given expression resolving the result of the evaluation to a 107 * boolean. The expression should be a single expression definition with or 108 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 109 * are both valid. 110 * 111 * @param expression a single expression i.e. header:foo=bar 112 * @param evaluator the evaluator to use when executing the expression 113 * @param message The current message being processed 114 */ 115 public boolean evaluateBoolean(String expression, String evaluator, MuleMessage message) throws ExpressionRuntimeException; 116 117 /** 118 * Evaluates the given expression resolving the result of the evaluation to a 119 * boolean. The expression should be a single expression definition with or 120 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 121 * are both valid. 122 * 123 * @param expression a single expression i.e. header:foo=bar 124 * @param message The current message being processed 125 */ 126 public boolean evaluateBoolean(String expression, MuleMessage message) throws ExpressionRuntimeException; 127 128 /** 129 * Evaluates the given expression resolving the result of the evaluation to a 130 * boolean. The expression should be a single expression definition with or 131 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 132 * are both valid. 133 * 134 * @param expression a single expression i.e. header:foo=bar 135 * @param evaluator the evaluator to use when executing the expression 136 * @param message The current message being processed 137 * @param nullReturnsTrue determines if true should be returned if the result of 138 * the evaluation is null 139 * @param nonBooleanReturnsTrue determines if true should returned if the result 140 * is not null but isn't recognised as a boolean 141 */ 142 public boolean evaluateBoolean(String expression, String evaluator, MuleMessage message, boolean nullReturnsTrue, boolean nonBooleanReturnsTrue) throws ExpressionRuntimeException; 143 144 /** 145 * Evaluates the given expression resolving the result of the evaluation to a 146 * boolean. The expression should be a single expression definition with or 147 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 148 * are both valid. 149 * 150 * @param expression a single expression i.e. header:foo=bar 151 * @param message The current message being processed 152 * @param nullReturnsTrue determines if true should be returned if the result of 153 * the evaluation is null 154 * @param nonBooleanReturnsTrue determines if true should returned if the result 155 * is not null but isn't recognised as a boolean 156 */ 157 public boolean evaluateBoolean(String expression, MuleMessage message, boolean nullReturnsTrue, boolean nonBooleanReturnsTrue) throws ExpressionRuntimeException; 158 159 /** 160 * Enriches the current message using 161 * @param expression a single expression i.e. header://foo that defines how the message shoud be enriched 162 * @param message The current message being processed that will be enriched 163 * @param object The object that will be used to enrich the message 164 */ 165 public void enrich(String expression, MuleMessage message, Object object); 166 167 /** 168 * Enriches the current message 169 * @param expression a single expression i.e. header://foo that defines how the message shoud be enriched 170 * @param enricher the enricher to use when executing the expression 171 * @param message The current message being processed that will be enriched 172 * @param object The object that will be used to enrich the message 173 */ 174 public void enrich(String expression, String enricher, MuleMessage message, Object object); 175 176 /** 177 * Evaluates expressions in a given string. This method will iterate through each expression and evaluate it. If 178 * a user needs to evaluate a single expression they can use {@link #evaluate(String,org.mule.api.MuleMessage,boolean)}. 179 * 180 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 181 * @param message The current message being processed 182 * @return the result of the evaluation 183 * @throws org.mule.api.expression.ExpressionRuntimeException 184 * if the expression is invalid, or a null is found for the expression and 185 * 'failIfNull is set to true. 186 */ 187 public String parse(String expression, MuleMessage message) throws ExpressionRuntimeException; 188 189 /** 190 * Evaluates expressions in a given string. This method will iterate through each expression and evaluate it. If 191 * a user needs to evaluate a single expression they can use {@link #evaluate(String,org.mule.api.MuleMessage,boolean)}. 192 * 193 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 194 * @param message The current message being processed 195 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 196 * null. @return the result of the evaluation 197 * @return the parsered expression string 198 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 199 * 'failIfNull is set to true. 200 */ 201 public String parse(final String expression, final MuleMessage message, final boolean failIfNull) throws ExpressionRuntimeException; 202 203 /** 204 * Clears all registered evaluators from the manager. 205 */ 206 public void clearEvaluators(); 207 208 /** 209 * Clears all registered enrichers from the manager. 210 */ 211 public void clearEnrichers(); 212 213 /** 214 * Determines if the expression is valid or not. This method will validate a single expression or 215 * expressions embedded in a string. the expression must be well formed i.e. #[bean:user] 216 * 217 * @param expression the expression to validate 218 * @return true if the expression evaluator is recognised 219 */ 220 public boolean isValidExpression(String expression); 221 222 /** 223 * Determines if the expression is valid or not. This method will validate a single expression or 224 * expressions embedded in a string. the expression must be well formed i.e. #[bean:user] 225 * 226 * @param expression the expression to validate 227 * @throws InvalidExpressionException if the expression is invalid, including information about the position and fault 228 * 229 * @since 3.0 230 */ 231 public void validateExpression(String expression) throws InvalidExpressionException; 232 233 /** 234 * Determines if the string is an expression. This method will validate that the string contains either the expression 235 * prefix (malformed) or a full expression. This isn't full proof but catches most error cases 236 * 237 * @param string is this string an expression string 238 * @return true if the string contains an expression 239 * 240 * @since 3.0 241 */ 242 public boolean isExpression(String string); 243 244 }