1 /* 2 * $Id: ExpressionManager.java 20813 2010-12-21 11:37:48Z dirk.olmes $ 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 110 * boolean. The expression should be a single expression definition with or 111 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 112 * are both valid. 113 * 114 * @param expression a single expression i.e. header:foo=bar 115 * @param evaluator the evaluator to use when executing the expression 116 * @param message The current message being processed 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 122 * boolean. The expression should be a single expression definition with or 123 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 124 * are both valid. 125 * 126 * @param expression a single expression i.e. header:foo=bar 127 * @param message The current message being processed 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 133 * boolean. The expression should be a single expression definition with or 134 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 135 * are both valid. 136 * 137 * @param expression a single expression i.e. header:foo=bar 138 * @param evaluator the evaluator to use when executing the expression 139 * @param message The current message being processed 140 * @param nullReturnsTrue determines if true should be returned if the result of 141 * the evaluation is null 142 * @param nonBooleanReturnsTrue determines if true should returned if the result 143 * is not null but isn't recognised as a boolean 144 */ 145 public boolean evaluateBoolean(String expression, String evaluator, MuleMessage message, boolean nullReturnsTrue, boolean nonBooleanReturnsTrue) throws ExpressionRuntimeException; 146 147 /** 148 * Evaluates the given expression resolving the result of the evaluation to a 149 * boolean. The expression should be a single expression definition with or 150 * without enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" 151 * are both valid. 152 * 153 * @param expression a single expression i.e. header:foo=bar 154 * @param message The current message being processed 155 * @param nullReturnsTrue determines if true should be returned if the result of 156 * the evaluation is null 157 * @param nonBooleanReturnsTrue determines if true should returned if the result 158 * is not null but isn't recognised as a boolean 159 */ 160 public boolean evaluateBoolean(String expression, MuleMessage message, boolean nullReturnsTrue, boolean nonBooleanReturnsTrue) throws ExpressionRuntimeException; 161 162 /** 163 * Enriches the current message using 164 * @param expression a single expression i.e. header://foo that defines how the message shoud be enriched 165 * @param message The current message being processed that will be enriched 166 * @param object The object that will be used to enrich the message 167 */ 168 public void enrich(String expression, MuleMessage message, Object object); 169 170 /** 171 * Enriches the current message 172 * @param expression a single expression i.e. header://foo that defines how the message shoud be enriched 173 * @param enricher the enricher to use when executing the expression 174 * @param message The current message being processed that will be enriched 175 * @param object The object that will be used to enrich the message 176 */ 177 public void enrich(String expression, String enricher, MuleMessage message, Object object); 178 179 /** 180 * Evaluates expressions in a given string. This method will iterate through each expression and evaluate it. If 181 * a user needs to evaluate a single expression they can use {@link #evaluate(String,org.mule.api.MuleMessage,boolean)}. 182 * 183 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 184 * @param message The current message being processed 185 * @return the result of the evaluation 186 * @throws org.mule.api.expression.ExpressionRuntimeException 187 * if the expression is invalid, or a null is found for the expression and 188 * 'failIfNull is set to true. 189 */ 190 public String parse(String expression, MuleMessage message) throws ExpressionRuntimeException; 191 192 /** 193 * Evaluates expressions in a given string. This method will iterate through each expression and evaluate it. If 194 * a user needs to evaluate a single expression they can use {@link #evaluate(String,org.mule.api.MuleMessage,boolean)}. 195 * 196 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 197 * @param message The current message being processed 198 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 199 * null. @return the result of the evaluation 200 * @return the parsered expression string 201 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 202 * 'failIfNull is set to true. 203 */ 204 public String parse(final String expression, final MuleMessage message, final boolean failIfNull) throws ExpressionRuntimeException; 205 206 /** 207 * Clears all registered evaluators from the manager. 208 */ 209 public void clearEvaluators(); 210 211 /** 212 * Clears all registered enrichers from the manager. 213 */ 214 public void clearEnrichers(); 215 216 /** 217 * Determines if the expression is valid or not. This method will validate a single expression or 218 * expressions embedded in a string. the expression must be well formed i.e. #[bean:user] 219 * 220 * @param expression the expression to validate 221 * @return true if the expression evaluator is recognised 222 */ 223 public boolean isValidExpression(String expression); 224 225 /** 226 * Determines if the expression is valid or not. This method will validate a single expression or 227 * expressions embedded in a string. the expression must be well formed i.e. #[bean:user] 228 * 229 * @param expression the expression to validate 230 * @throws InvalidExpressionException if the expression is invalid, including information about the position and fault 231 * 232 * @since 3.0 233 */ 234 public void validateExpression(String expression) throws InvalidExpressionException; 235 236 /** 237 * Determines if the string is an expression. This method will validate that the string contains either the expression 238 * prefix (malformed) or a full expression. This isn't full proof but catches most error cases 239 * 240 * @param string is this string an expression string 241 * @return true if the string contains an expression 242 * 243 * @since 3.0 244 */ 245 public boolean isExpression(String string); 246 247 }