JMSReceive node

Use the JMSReceive node to receive messages from JMS queues in the middle of a message flow. JMS queues are accessed through a connection to a JMS provider.

The JMSReceive node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale
Adapter

For more information, see Operation modes.

This topic contains the following sections:

Purpose

The JMSReceive node acts as a JMS message consumer and can receive all six message types that are defined in the Java™ Message Service Specification version 1.1 or 2.0.

The JMSReceive node is contained in the JMS drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:

Using the JMSReceive node in a message flow

The JMSReceive node receives and propagates messages with a JMS message tree. You can use a JMSReceive node in the middle of a message flow, unlike a JMSInput node, which you can use only as the first node in a message flow. The output message tree from a JMSReceive node is constructed by combining the input tree with the result tree from the received JMS message. You can specify which data from the input message is combined with the result tree by using the Result properties panel.

You can set the properties of the JMSReceive node to control the way in which the JMS messages are received.

The JMSReceive node is synchronous and therefore blocks the message flow until it receives a message from the defined JMS queue. If no message is received in the specified timeout period, the input message is propagated to the No Message output terminal. If the value of Timeout is 0, the node does not wait indefinitely to receive a JMS message, and so receives the next message only if one is immediately available.

The JMSReceive node handles messages in the following message domains:

DFDL
XMLNSC
JSON
BLOB
XMLNS
JMSMap
JMSStream
MIME
MRM

Message flows that handle messages that are received from connections to JMS providers can either start with a JMSInput node, or include a JMSReceive node in the middle of the flow. If you include an output node in a message flow that contains a JMSReceive node, it can be any of the supported output nodes (including user-defined output nodes); you do not have to include a JMSOutput node.

The JMSReceive node handles only point-to-point scenarios with JMS queues. To subscribe to a topic, use the JMSInput node.

Making the JMS provider client available to the JMS nodes

Configurable services are defined for a number of JMS providers. You can choose one of the predefined services, or you can create a service for a new provider, or for one of the existing providers. The predefined services are listed in Configurable services properties.

If you want to use the WebSphere® MQ JMS provider, and you have installed WebSphere MQ in the default location on the integration node system, the properties are already set and you do not have to change them.
If you want to use the WebSphere MQ JMS provider, and you have installed WebSphere MQ in a different (nondefault) location, or if you want to use one of the other defined services, you must set the jarsURL property to identify the location of the service JAR files on the integration node system. On Windows, the file location cannot be a mapped network drive on a remote Windows computer; the directory must be local or on a storage area network (SAN) disk.
Use the mqsireportproperties command to view the provider properties, and the mqsichangeproperties command to set or modify the properties.
If no service is defined for your JMS provider, or if you want to create another service for an existing JMS provider, use the mqsicreateconfigurableservice command to identify the new service and to set its properties.
When you configure the node, select the appropriate service from the list of predefined services shown for the JMS provider name property, or type in the name of your required service.
Some JMS providers provide an alternative interface to the standard JMS specification for particular JMS API calls. In these cases, IBM supplies a Java class to interface with that proprietary API. For example, if the JMS nodes use BEA WebLogic as the JMS provider, and the nodes must participate in an XA coordinated message flow, you must modify the configurable services properties that are associated with that vendor. For more information, see Configuring the integration node to enable a JMS provider's proprietary API.

Connecting the terminals

For each message that is received successfully, the JMSReceive node routes the message to the Out terminal. If this action fails, the message is retried. If the retry threshold is reached, the message is routed to the Failure terminal. You can connect nodes to the Failure terminal to handle this condition.

If the node cannot receive a message from the JMS queue within the timeout period specified in the Timeout property, the input message is routed to the No Message terminal.

If processing is not resumed after you restart the integration node or integration server, check the Deployment Log for a cause, such as an incorrect parser being specified in the node properties. Correct the problem and redeploy the message flow. If the message itself is not valid, remove the message from the input queue to resume processing.

Configuring for coordinated transactions

When you include a JMSReceive node in a message flow, the value that you set for Transaction mode defines whether messages are received under sync point. See Configuring JMS and SOAP nodes for local transactions.

Terminals and properties

When you have put an instance of the JMSReceive node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties that do not have a default value defined are marked with an asterisk.

The terminals of the JMSReceive node are described in the following table.

Terminal	Description
Failure	The output terminal to which the message is routed if an error occurs. Even if the Validation property is set, messages that are propagated to this terminal are not validated.
Out	The output terminal to which the message is routed if it is received successfully.
No Message	The output terminal to which the input message is routed if no message is available on the queue. The output message that is propagated to the No Message terminal is constructed from the input message.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The Description properties of the JMSReceive node are described in the following table.

Property	M	C	Default	Description
Node name	No	No	The node type, JMSReceive	The name of the node.
Short description	No	No		A brief description of the node.
Long description	No	No		Text that describes the purpose of the node in the message flow.

The Basic property of the JMSReceive node is described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Source queue	No	Yes	Selected	The name of the queue from which the node receives incoming messages.	sourceQueueName

The JMS Connection properties of the JMSReceive node are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
JMS provider name	Yes	No	WebSphere MQ	Select a JMS vendor name from the list, or enter a name of your choice. When you select a name from the list, the Initial context factory property is updated automatically with the relevant Java class. If you enter your own JMS provider name, you must also enter a value for the Initial context factory The name must match the name of a configurable service that is defined for the integration node to which you deploy the message flow. Alternatively, you can specify the JMSProviders configurable service.
Initial context factory	No	Yes	com.sun.jndi.fscontext. RefFSContextFactory	The starting point for a JNDI namespace. A JMS application uses the initial context to obtain and look up the connection factory and queue or topic objects for the JMS provider. If you select a JMS provider name from the list in JMS provider name, the Initial context factory property is updated automatically with the relevant Java class. If you enter your own JMS provider name, you must also enter a value for the Initial context factory. The default value is `com.sun.jndi.fscontext.RefFSContextFactory`, which defines the file-based Initial context factory for the WebSphere MQ JMS provider. If the node is set to use your own JMS Provider, and the corresponding Configurable services property of the mqsichangeproperties definition has the `InitialContextFactory` attribute set, this attribute overrides the setting on the node.	initialContextFactory
Location JNDI bindings	No	Yes		The system path or the LDAP location for the bindings file. The bindings file contains definitions for the JNDI administered objects that are used by the JMSReceive node. When you enter a value for Location JNDI bindings, ensure that it complies with the following instructions: Construct the bindings file before you deploy a message flow that contains a JMSReceive node. Do not include the file name of the bindings file in this field. If you have specified an LDAP location that requires authentication, configure the LDAP principal (user ID) and LDAP credentials (password) separately. These values are configured at integration node level. For information about configuring these values, see mqsicreatebroker command and mqsichangebroker command. The string value must include a supported URL prefix that has a URL handler that is available on the class path. For information about constructing the JNDI administered objects bindings file, see the JMS provider documentation. If the node is set to use your own JMS Provider, and the corresponding Configurable services property of the mqsichangeproperties definition has the `jndiBindingsLocation` attribute set, this attribute overrides the setting on the node.	locationJndiBindings
Connection factory name	No	Yes		The name of the connection factory that is used by the JMSReceive node to create a connection to the JMS provider. This name must exist in the bindings file.	connectionFactoryName
Timeout	Yes	Yes	2000	The maximum time, in milliseconds, to wait for the JMSReceive node to consume a message from the JMS queue. Set the Timeout property to specify how many milliseconds to wait for a message to be received. The Timeout value cannot be negative. A value of 0 means the node does not wait for a message to be available, and receives the next message only if one is immediately available. If you do not provide a value, the default value of 2000 milliseconds is used.	receiveTimeout

The JMSReceive node Response Message Parsing properties for the XMLNSC, JSON, XMLNS, MIME, BLOB, XML, and MRM domains are described in the following table.

Property	M	C	Description
Message domain	No	No	The domain that is used to parse the message from the supplied bit stream of the external resource.
Message model	No	No	The name or location of the message model schema file in which the response message is defined.
Message	No	No	The name of the response message.
Physical format	No	No	The name of the physical format of the response message.

The properties of the Parser Options for the JMSReceive node are described in the following table.

Property	M	C	Default	Description
Parse timing	Yes	No	On Demand	This property controls when a response message is parsed. Valid values are: On Demand Immediate Complete
Build tree using XML schema data types	Yes	No	Cleared	This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML schema. You can select this property only if you set Validate to Content or Content and value.
Use XMLNSC compact parser for XMLNS domain	Yes	No	Cleared	This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the response message data is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Input Message Parsing properties Message domain is XMLNS.
Retain mixed content	Yes	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in a response message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created.
Retain comments	Yes	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in a response message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created.
Retain processing instructions	Yes	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in a response message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements	No	No	Blank	This property is used to specify a list of elements in the input message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled.

The Message Selectors properties of the JMSReceive node are described in the following table. Set these properties to filter messages. For a description of how to construct the JMS message selector, see JMS message selector.

Property	M	C	Default	Description
Application property	No	No		The message selector that filters messages according to the application property value. If the JMS provider is required to filter messages, based on message properties that are set by the originating JMS client application, enter a selector string for Application property, specifying both the property name and the selection conditions; for example, `OrderValue > 200`. Leave Application property blank if you do not want the node to make a selection based on application property.
Timestamp	No	No		The message selector that filters messages according to the JMSTimestamp. If the JMS provider is required to filter messages that have been generated at specific times, enter a selector string for Timestamp, where the value is an unqualified Java millisecond time; for example, `105757642321`. Qualify the selector with operators, such as `=`, `BETWEEN` or `AND`. Leave Timestamp blank if you do not want the node to make a selection based on the JMSTimeStamp.
Delivery mode	No	No	All	The message selector that filters messages according to the message delivery mode. If the JMS provider is required to filter messages based on the JMSDeliveryMode header value in the JMS messages, select an option for Delivery mode from the list: Select Non Persistent to receive messages that are marked as nonpersistent by the originating JMS client application. Select Persistent to receive messages that are marked as persistent by the originating JMS client application. Select All to receive both persistent and nonpersistent messages. (This value is the default.)
Priority	No	No		The message selector that filters messages according to the message priority. If the JMS provider is required to filter messages based on the JMSPriority header value in the JMS message, enter a selector string for Priority. Valid values for Priority are from 0 (lowest) to 9 (highest). For example, enter `= 5` to receive messages of priority 5, `> 4` to receive messages with a priority greater than 4, or `BETWEEN 4 AND 8` to receive messages with a priority in the range 4 - 8. Leave Priority blank if you do not want the node to make a selection based on the JMSPriority.
Message type	No	No		The message selector that filters messages according to the message type. If the JMS provider is required to filter messages based on the JMSType header value in the JMS message, enter a selector string for Message type. Valid values for Message type are: Message BytesMessage TextMessage StreamMessage MapMessage ObjectMessage Leave Message type blank if you do not want the node to make a selection based on the JMSType.
Message ID	No	No		The message selector that filters messages according to the message ID. If the JMS provider is required to filter messages based on the JMSMessageID header, enter a selector string for Message ID. For example, enter `> WMBRK123456` to return messages where the Message ID is greater than `WMBRK123456`. Leave Message ID blank if you do not want the node to make a selection based on JMSMessageID.
Redelivered	No	No		If the JMS provider is required to filter messages based on the JMSRedelivered header, enter a selector string for Redelivered: Enter = FALSE if the input node accepts only messages that have not been redelivered by the JMS provider. Enter = TRUE if the input node accepts only messages that have been redelivered by the JMS provider. Leave Redelivered blank if you do not want the node to make a selection based on JMSRedelivered.
Correlation ID	No	No		The message selector that filters messages according to the correlation ID. If the JMS provider is required to filter messages based on the JMSCorrelationID header, enter a selector string for Correlation ID. For example, `= WMBRKABCDEFG` returns messages with a Correlation ID that matches this value. Leave Correlation ID blank if you do not want the node to make a selection based on JMSCorrelationID.

The Transactionality property of the JMSReceive node is described in the following table.

Property	M	C	Default	Description
Transaction mode	Yes	No	Automatic	This property controls whether the message is output under a JMS transaction. Valid values are Yes, No, and Automatic. Select No to output the message using a non-transactional JMS session. Select Yes to output the message using a transactional JMS session. The JMS transaction can be either local or XA coordinated. To use an XA coordinated transaction, using an XA JMS session, you must also select the message flow property Coordinated Transaction in the BAR file properties. Select Automatic if you want the message transactionality to be inherited from the Transaction mode setting on the Input node at the start of the flow. See Configuring for coordinated JMS transactions.

Property

Default

Description

Transaction mode

Yes

Automatic

This property controls whether the message is output under a JMS transaction. Valid values are Yes, No, and Automatic.

Select No to output the message using a non-transactional JMS session.

Select Yes to output the message using a transactional JMS session. The JMS transaction can be either local or XA coordinated. To use an XA coordinated transaction, using an XA JMS session, you must also select the message flow property Coordinated Transaction in the BAR file properties.

Select Automatic if you want the message transactionality to be inherited from the Transaction mode setting on the Input node at the start of the flow.

See Configuring for coordinated JMS transactions.

The properties of the Request panel for the JMSReceive node are described in the following table.

Property	M	C	Default	Description
Browse Only	No	No	Cleared	This boolean property controls whether messages are consumed or browsed. If the messages are browsed, the node reads the message but does not remove it from the queue. If this property is selected, Transaction Mode is disabled and transactionality is not used for browsing.
Reset Browse	No	No	Cleared	This boolean property determines the browsing behavior of the JMSReceive node. If this property is selected, the node browses messages from the start of the queue. If this property is cleared, the node browses messages from its current position in the queue. Reset the browse location in the queue. If this property is cleared, subsequent browse actions browse the next message in the queue. If this property is selected, the node browses from the front of the queue, browsing the same message as would be consumed from the queue.

Property

Default

Description

Browse Only

Cleared

This boolean property controls whether messages are consumed or browsed. If the messages are browsed, the node reads the message but does not remove it from the queue.

If this property is selected, Transaction Mode is disabled and transactionality is not used for browsing.

Reset Browse

Cleared

This boolean property determines the browsing behavior of the JMSReceive node. If this property is selected, the node browses messages from the start of the queue. If this property is cleared, the node browses messages from its current position in the queue.

Reset the browse location in the queue. If this property is cleared, subsequent browse actions browse the next message in the queue. If this property is selected, the node browses from the front of the queue, browsing the same message as would be consumed from the queue.

The properties of the Result panel for the JMSReceive node are described in the following table.

Property	M	C	Default	Description
Output data location	No	No	$OutputRoot	The location on the output message tree to which the JMSReceive node sends output. The input root is first copied to the output root, and then the result data is copied to the location on the output tree specified by Output data location. The default value, $OutputRoot, replaces the copied message tree with the result data, and propagates none of the input message. For example, a value of $OutputRoot/XMLNS/MyData inserts the result message data into the output message tree, by merging or overwriting the message tree. You can specify Output data location as an ESQL or an XPATH expression. See Combining a result message with an input message when fetching data from external systems.
Result data location	No	No	$ResultRoot	The location in the message received from the JMS queue that is copied to the Output data location field in the output message. For example, the default, $ResultRoot, inserts the result message into the output tree at the location specified by the Output data location. A value of $ResultRoot/JMSMap/map/MyMapItem puts only MyMapItem from a JMSMap message into the location specified by the Output data location. You can specify Result data location as an ESQL or an XPATH expression. See Combining a result message with an input message when fetching data from external systems.
Copy local environment	No	No	Selected	This property specifies whether the local environment is copied to the output message. If Copy local environment is selected, a new copy of the local environment is created in the tree, and it is populated with the contents of the local environment from the preceding node. Therefore, if a node changes the local environment, those changes are not visible to the upstream nodes in the event of a message rollback, because they have their own copies. This value is the default. If Copy local environment is cleared, the node does not generate its own copy of the local environment, but uses the local environment that is passed to it by the preceding node. Therefore, if a node changes the local environment, the changes are reflected by the upstream nodes in the event of a message rollback.

Property

Default

Description

Output data location

$OutputRoot

The location on the output message tree to which the JMSReceive node sends output. The input root is first copied to the output root, and then the result data is copied to the location on the output tree specified by Output data location. The default value, $OutputRoot, replaces the copied message tree with the result data, and propagates none of the input message.

For example, a value of $OutputRoot/XMLNS/MyData inserts the result message data into the output message tree, by merging or overwriting the message tree.

You can specify Output data location as an ESQL or an XPATH expression.

See Combining a result message with an input message when fetching data from external systems.

Result data location

$ResultRoot

The location in the message received from the JMS queue that is copied to the Output data location field in the output message.

For example, the default, $ResultRoot, inserts the result message into the output tree at the location specified by the Output data location.

A value of $ResultRoot/JMSMap/map/MyMapItem puts only MyMapItem from a JMSMap message into the location specified by the Output data location.

You can specify Result data location as an ESQL or an XPATH expression.

See Combining a result message with an input message when fetching data from external systems.

Copy local environment

Selected

This property specifies whether the local environment is copied to the output message.

If Copy local environment is selected, a new copy of the local environment is created in the tree, and it is populated with the contents of the local environment from the preceding node. Therefore, if a node changes the local environment, those changes are not visible to the upstream nodes in the event of a message rollback, because they have their own copies. This value is the default.
If Copy local environment is cleared, the node does not generate its own copy of the local environment, but uses the local environment that is passed to it by the preceding node. Therefore, if a node changes the local environment, the changes are reflected by the upstream nodes in the event of a message rollback.

The Validation properties of the JMSReceive node are described in the following table. For more details, see Validating messages and Validation properties.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Validate	Yes	Yes	None	This property controls whether validation takes place. Valid values are: None Content and Value Content Inherit	validateMaster
Failure action	No	No	Exception	This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are: User Trace Local Error Log Exception (the default value) Exception List

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.

Local environment overrides

You can dynamically override values in the local environment in the same way as setting values in other elements of a message. See Local environment overrides for the JMSReceive node.