View Javadoc

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 }