1 /* 2 * $Id: ExpressionManager.java 19191 2010-08-25 21:05:23Z tcarlson $ 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 /** 44 * Evaluates the given expression. The expression should be a single expression definition with or without 45 * enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" are both valid. For situations where 46 * one or more expressions need to be parsed within a single text, the {@link #parse(String,org.mule.api.MuleMessage,boolean)} 47 * method should be used since it will iterate through all expressions in a string. 48 * 49 * @param expression a single expression i.e. xpath://foo 50 * @param message The current message being processed 51 * @return the result of the evaluation 52 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 53 * 'failIfNull is set to true. 54 */ 55 public Object evaluate(String expression, MuleMessage message) throws ExpressionRuntimeException; 56 57 /** 58 * Evaluates the given expression. The expression should be a single expression definition with or without 59 * enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" are both valid. For situations where 60 * one or more expressions need to be parsed within a single text, the {@link #parse(String,org.mule.api.MuleMessage,boolean)} 61 * method should be used since it will iterate through all expressions in a string. 62 * 63 * @param expression a single expression i.e. xpath://foo 64 * @param message The current message being processed 65 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 66 * null. @return the result of the evaluation 67 * @return the parsered expression string 68 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 69 * 'failIfNull is set to true. 70 */ 71 public Object evaluate(String expression, MuleMessage message, boolean failIfNull) throws ExpressionRuntimeException; 72 73 /** 74 * Evaluates the given expression. The expression should be a single expression definition with or without 75 * enclosing braces. i.e. "mule:serviceName" and "#[mule:serviceName]" are both valid. For situations where 76 * one or more expressions need to be parsed within a single text, the {@link #parse(String,org.mule.api.MuleMessage,boolean)} 77 * method should be used since it will iterate through all expressions in a string. 78 * 79 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 80 * @param evaluator the evaluator to use when executing the expression 81 * @param message The current message bing processed 82 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 83 * null. @return the result of the evaluation 84 * @return the parsered expression string 85 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 86 * 'failIfNull is set to true. 87 */ 88 public Object evaluate(String expression, String evaluator, MuleMessage message, boolean failIfNull) throws ExpressionRuntimeException; 89 90 91 /** 92 * Evaluates expressions in a given string. This method will iterate through each expression and evaluate it. If 93 * a user needs to evaluate a single expression they can use {@link #evaluate(String,org.mule.api.MuleMessage,boolean)}. 94 * 95 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 96 * @param message The current message being processed 97 * @return the result of the evaluation 98 * @throws org.mule.api.expression.ExpressionRuntimeException 99 * if the expression is invalid, or a null is found for the expression and 100 * 'failIfNull is set to true. 101 */ 102 public String parse(String expression, MuleMessage message) throws ExpressionRuntimeException; 103 104 /** 105 * Evaluates expressions in a given string. This method will iterate through each expression and evaluate it. If 106 * a user needs to evaluate a single expression they can use {@link #evaluate(String,org.mule.api.MuleMessage,boolean)}. 107 * 108 * @param expression one or more expressions ebedded in a literal string i.e. "Value is #[xpath://foo] other value is #[header:foo]." 109 * @param message The current message being processed 110 * @param failIfNull determines if an exception should be thrown if expression could not be evaluated or returns 111 * null. @return the result of the evaluation 112 * @return the parsered expression string 113 * @throws ExpressionRuntimeException if the expression is invalid, or a null is found for the expression and 114 * 'failIfNull is set to true. 115 */ 116 public String parse(final String expression, final MuleMessage message, final boolean failIfNull) throws ExpressionRuntimeException; 117 118 /** 119 * Clears all registered evaluators from the manager. 120 */ 121 public void clearEvaluators(); 122 123 /** 124 * Determines if the expression is valid or not. This method will validate a single expression or 125 * expressions embedded in a string. the expression must be well formed i.e. #[bean:user] 126 * 127 * @param expression the expression to validate 128 * @return true if the expression evaluator is recognised 129 */ 130 public boolean isValidExpression(String expression); 131 132 /** 133 * Determines if the expression is valid or not. This method will validate a single expression or 134 * expressions embedded in a string. the expression must be well formed i.e. #[bean:user] 135 * 136 * @param expression the expression to validate 137 * @throws InvalidExpressionException if the expression is invalid, including information about the position and fault 138 * 139 * @since 3.0 140 */ 141 public void validateExpression(String expression) throws InvalidExpressionException; 142 143 /** 144 * Determines if the string is an expression. This method will validate that the string contains either the expression 145 * prefix (malformed) or a full expression. This isn't full proof but catches most error cases 146 * 147 * @param string is this string an expression string 148 * @return true if the string contains an expression 149 * 150 * @since 3.0 151 */ 152 public boolean isExpression(String string); 153 154 }