- All Implemented Interfaces:
- MessagePersister
public class MessageEvaluator
extends Persister
MessageEvaluator evaluates JMS Messages according to rulesets. The incoming
messages are supposed to specify what rules to be invoked for the evaluation.
The evaluation consists two separate steps. The first one is to apply the
filter on the message with the pattern matches, etc. The second is to invoke
the formatter to transform the message properties and the payload. If the
pattern does not match, the evaluation process will abort with the return
code of the message set to 1 for FAILURE to indicate NOHIT. Otherwise, the
message will be transformed according to the ruleset and its return code
will be set to 0 for SUCCESS. In case of failures, the return code will be
set to -1 for EXCEPTION. MessageEvaluator will not consume any messages,
nor commit any messages. It just bounces them back via removing them from
the input XQueue.
MessageEvaluator contains a number of predefined rulesets. Each ruleset
has its own unique name and the evaluation rules. It may also contain the
formatting rules or plugins for modifying the properties of the messages.
There are many built-in transformation supports. The default one is the
simple Templates and TextSubstitutions. Others are simple template files,
JSONPath evaluations, JSONT templates, XPath evaluations and XSLT templates,
etc. MessageEvaluator also supports CommaList, PipeList or ColonList for
evaluations on multiple rulesets.
For the default formatting support, the ruleset is supposed to have an array
of FormatterArgument. A FormatterArgument contains a name specifying what
property to be modifued, and two sets of format operations. The first set
of operations lists format templates in the name of Template. The other lists
substitutions with the name of Substitution. Each Template appends the
previous non-empty text to the variable and sets the next initial text for
its corresponding Substitutions. If the first template is null, the initial
text will be the variable itself. Each Substitution modifies the text
before it is appended to the variable. The associations between the
Templates and Substitutions are based on their positions. Either Template
or Substitution can be null for no action and a place holder. Therefore,
you can insert multiple null Templates so that the associated Substitutions
will be able to modify the same text in turns. MessageEvaluator will apply
all the operations of FormatterArguments on each SUCCESS message in the
order of the list. If any of the operations fails, the message will be
marked as EXCEPTION.
Besides FormatterArgument, MessageEvaluator also allows to have a simple
template file defined in the name of TemplateFile for a ruleset. In this
case, MessageEvaluator will load the template file at the start up and
stores it into the cache. It will be used to format the message body at the
end of the format process. If NeedChop is defined with the value of "true",
MessageEvaluator will try to chop the newline off the end of the loaded
content.
MessageEvaluator also supports SimpleParser with a list of ParserArgument
defined. It is used to parse the message payload and updates the various
properties of the message.
MessageEvaluator also supports JSONPath evaluations with a map of JSONPath
defined. It is used to retrieve data from the JSON payload and updates the
various properties of the message. Therefore, the map of JSONPath should
specify the property name as the key and a JSONPath expression as the value.
For JSONT support, the ruleset must not have any FormatterArgument defined.
Instead, the full path of the JSONT template file must be specified in the
name of JTMPFile. If there is any parameter to be set, they should be defined
in the map of JSONParameter where the key is the name of the parameter and
the value is a template for message properties. MessageEvaluator will load
the JSONT template file, compiles it at the startup and stores it to cache.
The parameters will be set dynamically in case there is any reference on the
properties of the incoming message.
MessageEvaluator also supports JSON formatter with a list of JSONFormatter
defined. A JSONFormatter is a map containing JSONPath, Operation, DataType,
Selector, and Template and Substitution. It supports various operations on
the messages and their JSON payload, such as get, set, remove, select,
first, last and merge, etc.
MessageEvaluator also supports XPath evaluations, similar to the evaluation
of JSONPath. It also supports operations of xmerge and xcut. XMerge is to
merge an XML content stored in XMLField into the XML payload of the message.
The ruleset should define SourceXPath and TargetXPath. Currently, only
append is supported for XMerge. XCut is to remove the object at a given
XPath expression.
For XSLT support, the ruleset must not have any FormatterArgument defined.
Instead, the full path of the XSL template file must be specified
in the name of XSLFile. If there is any parameters to be set, they should
be defined in the map of XSLParameter. MessageEvaluator will load the XSL
template file, compiles it at startup and stores it to cache. The parameters
will be set dynamically in case there is any references on the data of the
incoming message.
A PipeList is a list of pipe delimited names which reference a bunch of
existing rulesets. MessageEvaluator will match the message to the patterns
of each ruleset and invokes the formatter on the first hit only.
A ColonList is a list of colon delimited names which reference a bunch of
existing rulesets. MessageEvaluator will match the message to the patterns
of each ruleset and invokes the formatter on every ruleset that is a hit.
A CommaList is a list of comma delimited names which reference a bunch of
existing rulesets. MessageEvaluator will evaluate all the rulesets one by
one at the listed order. If any ruleset fails or does not match, the entire
evaluation process also fails.
For time window support, the ruleset can evalute the age of the message.
It requires ActiveTime, KeyTemplate and TimePattern to be defined in the
ruleset. If it is for age, please make sure the threshold contains at
lease two numbers. For occurrence, please make sure it contains only
one negative number.
For static caching support, the ruleset must have StaticCache defined as
a map with key-value pairs. Optionally, ResultField, KeyTemplate and
KeySubstitution can be defined also. ResultField specifies where to store
the cache result. By default, it is stored to message body. KeyTemplate
and KeySubstitution are used to retrieve the cache key. By default,
KeyTemplate is "##body##".
MessageEvaluator allows developers to plugin their own transformations by
specifying the full classname in the rules. The requirement is minimum.
First, the method of the transformation has to be defined. The second,
the method must take a JMS Message to be transformed as the only argument.
The return object must be a String of null meaning OK or error message,
otherwise. It must have a constructor taking a Map with a unique
value for the key of the Name, or a List or a String as the single
argument for configurations. Based on the data type of the constructor
argument, developers should define configuration parameters in the base
tag of FormatterArgument. MessageEvaluator will pass the data to the
plugin's constructor as an opaque object during the instantiation of the
plugin. In the normal operation, MessageEvaluator will invoke the method
to format the SUCCESS messages. The method should never acknowledge or
commit any messages in any case.
In case a plugin needs to connect to external resources for dynamic
format process, it should define an extra method of close() to close all
the external resources gracefully. Its format method should also be able
to detect the disconnections and cleanly reconnect to the resources
automatically. If the container wants to stop the node, it will call the
methods of close() on all transformers in order to release all external
resources.
MessageEvaluator always copies the original value of RCField to the
OriginalRCField before resetting it. If you want to evaluate the value of
the property in RCField, please ensure to reference the OriginalRCField in
your pattern group.
- Author:
- yannanlu@yahoo.com