Coverage Report - org.mule.api.expression.ExpressionManager
 
Classes in this File Line Coverage Branch Coverage Complexity
ExpressionManager
N/A
N/A
1
 
 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  
 }