Copyright © Cloud Software Group, Inc. All Rights Reserved

JMS Queue Receiver

Process Starter

Starts a process based on the receipt of a message for the specified JMS queue.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
JMS Connection	No	The JMS connection. See JMS Connection for more information about creating a JMS connection.
Destination Queue	Yes	Name of the queue of the incoming message. The syntax of the queue name is specific to the JMS provider you are using. See your JMS provider documentation for more information about queue names. Note: If you are using TIBCO Enterprise Message Service as your JMS provider, you can use the Browse button next to this field after specifying a valid connection in the JMS Connection field. The Browse button displays a list of configured destinations in the JMS server that are appropriate for this activity.
Message Type	No	The type of the message. This can be one of the following: • Simple — A message with no body portion. • Bytes — A stream of bytes. • Map — A set of name/value pairs. The names are strings, and the values are simple data types (Java primitives), an array of bytes (use the Binary datatype when mapping this data), or a string. Each item can be accessed sequentially or by its name. • Object — A serializable Java object. • Object Ref — An object reference to a Java object. • Stream — A stream of Java primitives, strings, or arrays of bytes. Each value must be read sequentially. • Text — The message is a java.lang.String. • XML Text — The message is XML text.
Acknowledge Mode	Yes	The acknowledge mode for incoming messages. It can be one of the following: • Auto — the message is automatically acknowledged when it is received. • Client — the message will be acknowledged at a later point by using the Confirm activity. If the message is not confirmed before the process instance ends, the message is redelivered and a new process instance is created to handle the new incoming message. Ensure that your process definition confirms the message when using this acknowledge mode.
		• TIBCO EMS Explicit — (only available for TIBCO Enterprise Message Service) a message which is not acknowledged using the Confirm activity before the process instance ends, will be redelivered instead of all messages in the session. The session is not blocked and one session handles all incoming messages for each process instance. Note — In the TIBCO ActiveMatrix BusinessWorks 5.10 release, there is a change in the behavior of this feature. Now only the messages that are not confirmed, will be redelivered. • TIBCO EMS Explicit Dups OK — (only available for TIBCO Enterprise Message Service) a message which is not acknowledged using the Confirm activity before the process instance ends, will be redelivered instead of all messages in the session. The session is not blocked and one session handles all the incoming messages for each process instance. The messages however, would be lazily acknowledged. • TIBCO EMS No Acknowledge — the message is not acknowledged when it is received. • Dups OK — the message is acknowledged automatically when it is received. JMS provides this mode for lazy acknowledgement, but TIBCO ActiveMatrix BusinessWorks acknowledges messages upon receipt.
		• Transactional — this mode is used when a transaction that can process JMS messages is included in the process definition. The message is acknowledged when the transaction commits. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about creating transactions that JMS activities can participate in. • Local Transactional — this mode is used when a transaction involves only JMS messages. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about creating transactions that JMS activities can participate in.
Max Sessions	Yes	When the Acknowledge Mode field is set to Client, Transactional and Local Transactional, this field appears for specifying the maximum number of JMS sessions to create for incoming messages. When a JMS queue message is received, the session is blocked until the message is acknowledged. Because the acknowledgement can come at a later time with the Confirm activity, this field allows you to specify a maximum number of new sessions to create to handle incoming messages. After reaching a maximum number of sessions, no new incoming messages can be processed. The total number of active sessions is decreased and another incoming message can be processed after confirming an incoming message.

Misc

The Misc tab contains the following fields:

Field	Description
Sequencing Key	This field can contain an XPath expression that specifies which processes should run in order. Process instances with sequencing keys that evaluate to the same value will be executed sequentially in the order the process instance was created. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about controlling the execution order of process instances and about XPath expressions.
Custom Id	This field can contain an XPath expression that specifies a custom ID for the process instance. This ID is displayed in the View Service dialog of TIBCO Administrator, and it is also available in the $_processContext process variable.

Load-Balancing of Incoming Messages

One common application of a JMS queue is to distribute queue messages across multiple receivers, thus balancing the processing of the messages on the queue. To achieve this goal, both the JMS server and TIBCO ActiveMatrix BusinessWorks must be properly configured. The JMS server must allow the queue messages to be distributed across multiple receivers. For example, in TIBCO Enterprise Message Service, the exclusive property on the queue controls whether messages can be delivered across receivers or not. In TIBCO ActiveMatrix BusinessWorks, the process definition containing the JMS Queue Receiver must be deployed across multiple process engines. This creates multiple queue receivers for the same queue.

When balancing incoming messages across TIBCO ActiveMatrix BusinessWorks engines, you should ensure that one engine does not attempt to accept and confirm a large number of incoming messages before other engines can receive the messages. In general, most JMS servers balance the load by distributing messages in a round-robin fashion to all queue receivers. However, there are situations that can cause an uneven distribution of messages across queue receivers. If you set the Acknowledge Mode field to "Auto" on the Configuration tab of the JMS Queue Receiver, the process starter confirms messages as it receives them. When process engines are started at different times, this can lead to one process engine receiving all queue messages and paging them to disk, depending upon how the engine’s Max Jobs and Activation Limit properties are set when the engine is deployed.

If you are using TIBCO Enterprise Messaging Service, you can avoid this problem by setting the acknowledge mode to TIBCO EMS Explicit and then use the Flow Limit property in the deployment configuration to control the number of process instances created by the process starter.

If you are not using TIBCO Enterprise Messaging Service, set the Acknowledge Mode field to "Client". In this mode, a process engine can only receive as many messages as it has sessions specified in the Max Sessions field. Once a process engine reaches the maximum number of sessions, another process engine can begin to accept incoming messages. A process engine cannot receive more messages until the messages have been acknowledged by using the Confirm activity. Once the message is acknowledged, the session is released and the process engine can accept a new message.

If the Sequencing Key field is set to preserve the order of incoming messages, to confirm the messages sequentially you must either set the Acknowledge mode to TIBCO EMS Explicit Client Acknowledge mode or set the Acknowledge mode to Client and Max Sessions to 1. Setting Max Sessions to 1 can limit the system's throughput, so using TIBCO Enterprise Message Service and TIBCO EMS Explicit Client Acknowledge is a better choice.

Advanced

The Advanced tab has the following fields.

Field	Global Var?	Description
Message Selector	Yes	A string to determine whether a message should be received. The syntax of the message selector is determined by the JMS provider, but it is usually a subset of SQL92 (where message properties are used instead of table column names). See your JMS provider documentation for more information and syntax for a message selector string.
JMS Application Properties	Yes	Any application-specific message properties that will be part of the message. This is specified by the JMS Application Properties shared configuration object. Once specified, these properties appear on the Output tab as "OtherProperties".
Receiver Timeout (seconds)	No	Specifies the polling interval to check for new messages. This default interval is set by the custom engine property bw.plugin.jms.receiverTimeout. If no value is specified for the property, the default polling interval is one second. Set a value in this field to specify the polling interval (in seconds) for this activity. The value in this field overrides the default polling interval.
Precreate Transactions	No	When selected, this field specifies that the transaction is created before a message arrives at the JMS receiver. This field is available when Acknowledge Mode is set to Transactional. Note: The Precreate Transactions feature should be used only with IBM MQ Websphere.
XA Transaction Manager Reference	No	Specifies the XA Transaction Manager Configuration used to create the XA transaction. This field is available when Precreate Transactions field is checked. This configuration overrides the Transaction Manager associated with the group the Event Source is tied to.

Output Editor

The Output Editor tab defines the schema to use for incoming messages whose message type is Map, Stream, or XML Text. Map messages are name/value pairs, and the schema allows you to define the structure of the incoming message. Once defined, the schema on the Output Editor tab becomes the structure used for the body of the message displayed on the Output tab.

See Appendix A, Specifying Data Schema for a complete description of using the Output Editor tab.

Output

The output for the activity is the following.

Output Item	Datatype	Description
JMSHeaders	complex	The message header fields for the message. See JMS Properties for more information about message header fields. Only properties applicable to this type of message are displayed.
JMSProperties	complex	The message properties for the message. See JMS Properties for more information about message properties. Only properties applicable to this type of message are displayed.
OtherProperties	complex	If the JMS Application Properties field is specified on the Advanced tab, the OtherProperties group lists the application-specific properties in the selected JMS Application Properties shared configuration resource.
Body	depends upon the message type	The body of the message.
DynamicProperties	complex	The dynamic properties is an additional parameter to add runtime property to the Outgoing JMS Messages which is specified in the Input tab. This is an optional element with only one instance. Dynamic property can have multiple property elements. Each property element denotes a single dynamic property and can contain the following elements: Name — Required. Name of the property with one instance. Value — Required. Value of the property with one instance. Type — Optional. Type of the property. If not provided, it will be considered as string. Following Types are supported: • string • boolean • short • integer • long • float • double • byte Note: The DynamicProperty will overwrite the value of a property (with the same name) added using the JMS Application Property. The DynamicProperties will be also added to the outgoing message.

Copyright © Cloud Software Group, Inc. All Rights Reserved