View Javadoc

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 }