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