View Javadoc

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 }