Copyright © Cloud Software Group, Inc. All Rights Reserved

Wait for JMS Topic Message

Activity

The Wait for JMS Topic Message waits for the receipt of a message for the specified JMS topic.

See Scalability With Incoming Events in TIBCO ActiveMatrix BusinessWorks Process Design Guide for information on running the "Wait for..." activities in a multi-engine mode.

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 Topic	Yes	Name of the topic of the outgoing message. The syntax of the topic name is specific to the JMS provider you are using. See your JMS provider documentation for more information about topic 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 to map 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.
Durable Subscription	Yes	Specifies a durable subscription. You must specify a name in the Subscription name field that is registered with the JMS application as the durable subscription name.
Subscription Name	Yes	The subscription name registered with the JMS application for durable subscriptions. This field is only available when the Durable subscription field is checked. Once a durable subscription is created, it can only be removed by accessing the administration tool of the JMS provider. See the documentation of your JMS provider for more information about managing durable subscriptions.
Suppress Local Messages	No	Specifies to not receive messages on the specified topic name when the message origin is the JMS application on the same connection as the process engine. If your process definition publishes and subscribes to messages with the same topic name, this option is useful if you want to specify whether to receive messages sent by the same JMS application that published the message. Checking this field prevents the process from receiving messages sent by the same connection. Unchecking this option specifies messages sent by the same connection should be received.
Acknowledge Mode	Yes	The acknowledge mode for the incoming messages. It can be one of the following: • Auto : the message is automatically acknowledged when it is received. • 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, would 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. • 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.

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	No	Any application-specific message properties to include in the message. This is specified by the JMS Application Properties shared configuration resource. 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.

Message Event

The Event tab has the following fields.

Field	Description
Candidate Event Key	Expression built from the data of the incoming file change event. This expression should evaluate to a string and it is compared to the "key" field of the activity’s input. If the Candidate Event Key and the activity’s key match, then the process accepts the incoming message. For example, you may have JMS Topic Publisher activity earlier in the process diagram and you are expecting a message in response to the sent message. You would place the JMSCorrelationID from the header of the incoming message into the Candidate Event Key field. You would then place the JMSMessageID from the header of the outgoing message earlier in the process in the "key" field on the input tab. This expression is specified in XPath, and only data from the incoming event is available for use in this XPath expression. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about XPath expressions.
Event Timeout (msec)	A message may arrive before this activity is executed. This field specifies the amount of time (in milliseconds) a message waits if it is received before this activity is executed. If the event timeout expires, an error is logged and the event is discarded. If no value is specified in this field, the message waits indefinitely. If zero is specified, the event is discarded immediately, unless this activity has already been reached.

When building an expression in the Candidate Event Key field, only data from the incoming event is available. This is because you want to place an expression containing incoming event data in the Candidate Event Key field. When the results of this expression match the results of the expression in the "key" item on the Input tab, the Wait For JMS Topic Message activity proceeds.

Using Wait for JMS Queue Message Activity in Multi-Engine Design

All "Wait for ..." activities start listening from the time the bwengine loads and can be configured to filter static data. These activities cannot filter dynamic data.

The activity pulls all the messages that are in the queue upon startup and processes them according to the Event key. Any messages that were picked up but do not match the key are discarded. A Wait for JMS Queue Message Activity cannot be used with the Candidate Event key as the key is applied after receiving the message from the queue.

In a multi-engine environment, when new messages arrive on the queue, the messages are dispatched among all active listeners in a round-robin fashion. Thus an engine may potentially pick up the message which was intended for some other engine, and later discard the message because of a mismatch in the Event key.

It is recommended that you use the Wait for JMS Queue Message activity with the Message Selector in a multi-engine mode. The Message Selector is applied while browsing the queue before picking up the messages.

Input

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

The input for the activity is the following.

Input Item	Datatype	Description
key	string	The value that is compared to the Candidate Event Key field of the Event tab to determine if this message applies to this process. See Message Event for an example of using the Candidate Event Key field with the key input item.
processTimeout	integer	The time (in milliseconds) to wait for the incoming message. An error is returned if the message is not received in this time limit.

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.
JMSProperties	complex	The message properties for the message. See JMS Properties for more information about message properties.
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.

Error Output

The Error Output tab lists the possible exceptions that can be thrown by this activity. See TIBCO ActiveMatrix BusinessWorks Error Codes for more information about error codes and corrective action to take.

Exception	Thrown When...
ActivityTimedOutException	The activity has reached the event or process timeout.

Copyright © Cloud Software Group, Inc. All Rights Reserved