Message-driven rule beans

A message-driven rule bean, or MDB, is an enterprise bean that Java™ EE applications use to process messages asynchronously.

Clients use interfaces to access rule sessions but they do not access message-driven rule beans through interfaces.

When a Java Message Service (JMS) message comes in, an instance of a message-driven rule bean calls the execution unit (XU) and posts the results of the rule engine processing to a JMS destination. The actual call to the rule engine is delegated to a simple rule session.

Restriction:

The supported JMS version is 1.1. As a consequence, message-driven beans do not run on an earlier version of the JMS engine.

To access a message-driven rule bean through JMS, the client sends messages to the message destination for which the message-driven rule bean class is MessageListener. You can use the application server resources to assign the destination of the message-driven rule bean.

The process runs as follows:

The client locates the connection factory and queue.
The client creates a session and sender.
The client can then send messages to the queue.
When the queue receives a message, the EJB container calls the onMessage method of the message-driven rule bean.
The message-driven rule bean receives the messages and calls a simple rule session.
The stateless rule session sends the response messages, if any.

The beans are identified by their respective class and EJB names in the ejb-jar.xml deployment descriptor.

Architecture of message-driven rule beans

The body of the delivered message is a java.util.Map instance inside a javax.jms.ObjectMessage instance. For the call to receive the necessary parameters, the message must include these JMS properties:ilog_rules_bres_mdb_rulesetPath and ilog_rules_bres_mdb_status. The message body ObjectMessage.setObject(java.io.Serializable) can also include ruleset parameters in a hash map that is identified by their name and value.

Examples

The following code sample shows Queue and Topic MDBs.

<message-driven>
   <ejb-name>IlrRuleExecutionEJB</ejb-name>
   <ejb-class>ilog.rules.res.mdb.ejb.IlrRuleExecutionBean</ejb-class>
   ...
</message-driven>

<message-driven>
   <ejb-name>IlrRuleExecutionTopicEJB</ejb-name>
   <ejb-class>ilog.rules.res.mdb.ejb.IlrRuleExecutionBean</ejb-class>
   ...
</message-driven>

Section Creating a message body shows how to create a message body that sets ruleset parameters in a hash map.

JMS properties and body of incoming messages

The following table summarizes the JMS properties available and how they operate in relation to incoming messages.

Table 1. JMS properties linked to execution
JMS property name	Type	Description	Mandatory?
ilog_rules_bres_mdb_rulesetPath	String	Contains the ruleset path to execute.	Mandatory
ilog_rules_bres_mdb_status	String	Must be set to `request`.	Mandatory
ilog_rules_bres_mdb_enableInterceptor	Boolean	Set to true to enable a ruleset execution interceptor. The default value is false.	Optional
ilog_rules_bres_mdb_userData	String	Contains the `userData` value that is passed to the simple rule session.	Optional
ilog_rules_bres_mdb_mainTask	String	Contains the name of the main task to be executed.	Optional
ilog_rules_bres_mdb_bom_access	Boolean	Set to true for input parameters to be expressed on the BOM types.	Optional
ilog_rules_bres_mdb_decisionId	String	Use this parameter to specify the identifier that you want for ruleset execution messages. If you do not set this property, an identifier is generated by default and reused in Decision Warehouse.	Optional

Table 2. The message body (java.util.Map) inside a java.jms.ObjectMessage
Key	Type	Value
Parameter name	String	Parameter value (serializable)
ilog_rules_bres_mdb_filters		Associated with a java.util.Properties object. This object contains the filters that determine the level of execution trace. The property key is a string that references a specific metric to be traced. The value is also a string, and the `true` value enables the metric in the trace. The following property keys are supported: INFO_TOTAL_RULES_FIRED INFO_TOTAL_TASKS_EXECUTED INFO_EXECUTION_EVENTS INFO_TOTAL_RULES_NOT_FIRED INFO_TOTAL_TASKS_NOT_EXECUTED INFO_RULES_NOT_FIRED INFO_TASKS_NOT_EXECUTED INFO_EXECUTION_DURATION INFO_RULES INFO_TASKS

Table 3. JMS properties linked to management
JMS property name	Type	Description	Mandatory?
JMSMessageID	String	Used to link the reply message to the input message.	Set by the JMS provider.
JMSReplyTo	String	Used to get the destination of the reply message.	Optional

JMS properties and body of outgoing messages

The following table summarizes the JMS properties available and how they operate in relation to outgoing messages.

Table 4. JMS properties linked to execution
JMS property name	Type	Description
ilog_rules_bres_mdb_rulesetPath	String	Contains the ruleset path to execute.
ilog_rules_bres_mdb_status	String	You must set it to response.
ilog_rules_bres_mdb_decisionId	String	If you specified a decision identifier, that same ID is used to store the trace in Decision Warehouse.
ilog_rules_bres_mdb_userData	String	Contains the `userData` value that was previously set in the incoming message.

Table 5. The message body (java.util.Map) inside a java.jms.ObjectMessage
Key	Type	Value
Parameter name	String	Parameter value (serializable)
ilog_rules_bres_mdb_contextOut		Associated with what is printed with `context.note` by the executed ruleset.
ilog_rules_bres_mdb_executionWarnings		Associated with a `String` value that contains the warnings that were raised during execution.
ilog.rules.firedRulesCount		Associated with the number of executed rules.
ilog_rules_bres_mdb_canonicalRulesetPath	String	The canonical ruleset path of the executed ruleset.
The following information is present depending on the filters that were set in the incoming message.
ilog_rules_bres_mdb_num_rules_fired		Associated with a `Long` value that contains the number of executed rules.
ilog_rules_bres_mdb_rules_fired		Associated with a list that contains the names of the executed rules.
ilog_rules_bres_mdb_num_rules_not_fired		Associated with a `Long` value that contains the number of rules that were not executed.
ilog_rules_bres_mdb_all_rules		Associated with a list that contains the names of all the ruleset rules.
ilog_rules_bres_mdb_num_tasks_executed		Associated with a `Long` value that contains the number of executed tasks.
ilog_rules_bres_mdb_tasks_executed		Associated with a list that contains the names of the executed tasks.
ilog_rules_bres_mdb_num_tasks_not_executed		Associated with a `Long` value that contains the number of tasks that were not executed.
ilog_rules_bres_mdb_all_tasks		Associated with a list that contains the names of all the ruleset tasks.
ilog_rules_bres_mdb_execution_duration		Associated with a `Long` value that contains the execution duration.

JMS properties and selectors

JMS properties are useful for building accurate message selectors. A message selector is a facility to filter messages at the message-consumer level. You can use selectors to make a message-consumer specific for a particular kind of message. Decision Server MDBs use message selectors in the ejb-jar.xml file to filter received messages with the property ilog_rules_bres_mdb_status set to request.

<message-selector>ilog_rules_bres_mdb_status = 'request'</message-selector>

Note:

You cannot write a message selector on the message body. As a consequence, you cannot write selectors on parameters or warnings. For example:
```
(ilog_rules_bres_mdb_status = 'response') AND (ilog_rules_bres_mdb_userData = 'myUserData')
```
To implement authentication, you must declare it in the application server resources. When a client creates a connection, that client can specify its credentials as name and password. The server can authorize the use of these resources based on this declaration. An exception must be thrown when a provider rejects a user name and password that were submitted by a client.

For more information about message selectors, see the Java API documentation: Interface message and Sample: Message-driven rule beans.