View Javadoc
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 }