JMSOutput node

This topic contains the following sections:

Purpose

Use the JMSOutput node to send messages to JMS destinations. The JMSOutput node acts as a JMS message producer and can publish all six message types that are defined in the Java Message Service Specification, version 1.1. Messages are published by using method calls, which are described in the JMS specification.

The JMSOutput node is represented in the workbench by the following icon:

JMSOutput node icon

Using the JMSOuput node in a message flow

The JMS Nodes sample sample contains a message flow in which the JMSOutput node is used. Refer to this sample for an example of how to use the JMSOutput node.

Message flows that handle messages received from connections to JMS providers must always start with a JMSInput node. If you include the JMSOutput node in a message flow, you do not need to include a JMSInput node, but if you do not include a JMSInput node, you must include the MQJMSTransform node to transform the message to the format that is expected by the JMSOutput node.

If you are propagating JMS messages and creating a message flow to use as a subflow, you must use an instance of the JMSOutput node as the last node in order to create an out terminal for the subflow.

Making the JMS Provider client available to the JMS Nodes

For distributed systems, copy the java .jar files and any native libraries for the JMS provider client into the broker shared-classes directory. For example, on Windows, C:\Documents and Settings\All Users\Application Data\IBM\MQSI\shared-classes. This ensures that the java class path for the JMS nodes is set correctly.

For z/OS, there is no shared-classes directory. Instead, perform this procedure:
  1. Specify each JMS provider java .jar file in the class path in the BIPPROF member of the broker’s Partitioned Data Set (PDS).
  2. Update the LIBPATH with any native libraries.
  3. Submit the BIPGEN JCL job to update the broker ENVFILE.
Start of change

Using the Message Destination Mode

The JMSOutput node acts as a message producer and supports the following message scenarios:

Sending a datagram message

A datagram is a self-contained, independent entity of data that carries sufficient information to be routed from the source to the destination computer without reliance on earlier exchanges between the source and destination computer and the transporting network. The following instructions describe how to send a datagram message:
  1. In the Request folder, set the Destination Mode attribute to Destination Name.
  2. Set the message destination depending on the message model that is being used. Set one of the following attributes to a valid JNDI administered object name:
    • The Publication Topic in the Pub/Sub folder
    • The Destination Queue in the Point to Point folder
  3. Set the value of the Reply To Destination attribute under the Request folder to blank.
The node resolves the name of the JNDI administered object, which is supplied in either Publication Topic or Destination Queue, and sends the message to that JMS Destination.

Sending a reply message

In some cases a message producer might want the consumer to reply to the message. In this case, the JMSOutput message can treat the outgoing message as a reply, and route it according to the value obtained from the JMSReplyTo property from the request message. The following instructions describe how to send a reply message:
  1. In the Request folder, set the Destination Mode attribute to Reply To Destination.
  2. You can modify the value of the JMSReplyTo property in the MbMessage for instances using a Compute node or a JavaCompute node. This allows dynamic routing of messages from the JMSOutput node.
The node sends the message to the JMS Destination name that is set in the JMSReplyTo field of the MbMessage Tree.
The JMSReplyTo value in the MbMessage Tree represents the name of the JMS Destination that is resolved from JNDI. For example:
queue://QM_mn2/myJMSQueue4
In this case, the value is the JMS provider specific representation of a JMS Destination for the WMQSeries JMS Provider.
If you do not want to specify a resolved JMS destination name, the JMSOutput node can also accept a JNDI administered object name in theJMSReplyTo field. However, it is necessary to resolve an administered object name through JNDI before the node can route the message to the underlying JMS Destination. In this case, the value in the JMSReplyTo field should be prefixed with the string: jndi:\\; for example:
jndi:\\jmsQ4
where jmsQ4 is the name of the JNDI administered object.

There is a slight performance overhead using this method because of the need to look up the administered object in JNDI.

Sending a request message

The JMSOutput node can send a message to a JMS Destination with the expectation of a response from the message consumer that processes the request. The following instructions describe how to send a request message:
  1. Set the message destination depending on the message model that is being used. Set one of the following attributes to a valid JNDI administered object name:
    • The Publication Topic in the Pub/Sub folder
    • The Destination Queue in the Point to Point folder
  2. In the Request folder, set the Destination Mode attribute to Destination name.
  3. The JMSReplyTo destination in the outgoing message can be derived from the JMSReplyTo field of the MbMessage Tree passed to the node. Alternatively, this value can be overridden by a JNDI Administered object name set in the Reply To Destination node attribute.

    If the intention is to allow the JMSOutput node to set the JMSReplyTo property dynamically in the outgoing message, leave the Reply To Destination attribute blank, and set the JMSReplyTo value in the MbMessage using a Compute node or a JavaCompute node.

The node looks first for a value in the JMSReplyTo field of the MbMessage. If it finds it, it passes this value into the JMSReplyTo field of the outgoing message. However, if the Reply To Name field of the Request folder has been specified, this value overrides anything that is set previously in the JMSReplyTo property of the outgoing message, after first resolving the name of the JNDI administered object .

The node resolves the name of the JNDI administered object that is supplied in either Publication Topic or Destination Queue, and sends the message to that JMS Destination.

End of change

Configuring the JMSOutput node

When you have put an instance of the JMSOutput node into a message flow, you can configure it by right-clicking the node in the editor view and clicking Properties. The node's basic properties are displayed in the properties dialog.

All mandatory properties that do not have a default value defined are marked with an asterisk on the properties dialog box.

Configure the JMSOutput node as follows:

  1. Select Basic in the properties dialog navigator and complete the following properties:
    • Enter an Initial Context Factory value. A JMS application uses the initial context to obtain and look up the JNDI administered objects for the JMS provider. The default value is

      com.sun.jndi.fscontext.RefFSContextFactory, which defines the file-based initial context factory for the WebSphere MQ JMS provider.

      To identify the name of the Initial Context Factory for the JMS provider, refer to the JMS provider documentation.

    • Start of changeEnter a value for the Location JNDI Bindings. This value specifies either the file 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 JMSOutput node.

      When you enter a value for Location JNDI Bindings, ensure that it is compliant with the following instructions:

      • Construct the bindings file before you deploy a message flow that contains a JMSOutput node.
      • Do not include the filename of the bindings file in this field.
      • If you have specified an LDAP location that requires authentication, you must configure separately both the LDAP principal (userid) and LDAP credentials (password). These values are configured at broker level. For information on configuring these values, refer to the mqsicreatebroker and mqsichangebroker commands.
      • The string value should include the leading keyword, which is one of the following: file:/ , iiop:/, or ldap:/.

      For information about constructing the JNDI administered objects bindings file, refer to the documentation that is supplied with the JMS provider.

      End of change
    • Enter a Connection Factory Name. The connection factory name is used by the JMSOutput node to create a connection to the JMS provider. This name must already exist in the bindings file.
  2. Start of changeIf the JMSOuput node is to be used to publish a topic, select Pub/Sub in the properties dialog navigator.
    • Enter the name of the Publisher Topic.
      • If this property is configured, the node operates only in the publish/subscribe message domain.
      • This property is mutually exclusive with Destination Queue in the Point to Point properties section.
      • The Publisher Topic name must conform to the standards of the JMS provider that is being used by the node.
    End of change
  3. If the JMSOutput node is to be used to send point to point messages then select Point to Point in the properties dialog navigator.
    • Enter the Destination Queue name for the JMS queue name that is listed in the bindings file.
  4. Select Request in the properties dialog navigator and complete the following properties:
    • Select an option from the Destination Mode drop-down list.
      • The default value is Destination Name. It this is selected, the message is treated as a request of a datagram and it targets either the Publication Topic or the Destination Queue .
      • If the message is to be treated as a reply, select Reply Destination Name. The JMS provider is supplied with the JMSReplyTo value from the JMSTransport_Header_values section of the message tree.
    • Enter a value for Reply To Destination. You can enter a JMS destination, which can be either a subscription queue or a destination topic. The Reply To Destination is the name of the JMS destination to which the receiving application should send a reply message. For a reply message to be returned to this JMS destination, the JMS destination name must be known to the domain of the JMS provider that is used by the receiving client.

      The default value is blank, in which case the JMS output message can be regarded as a datagram. If the field is blank, the JMSOutput node does not expect a reply from the receiving JMS client.

  5. Select Advanced in the properties dialog navigator.
    • If a New Correlation ID is required, select the check box.
    • To define the transactional characteristics of how the message is handled, select the Transaction Mode:
      • Select none if the outgoing message is to be treated as non persistent. If you select this value, the message is sent using a non transacted JMS Session that is created using the Session.AUTO_ACKNOWLEDGE flag.
      • Select local if the input node that received the message should coordinate the commit or roll back of JMS messages that have been sent by the JMSOutput node, along with any other resources such as DB2 or WebSphere MQ that perform work within the message flow. If you select this value, the node uses a transacted JMS Session.
      • Select global if the JMSOutput node should participate in a global message flow transaction that is managed by the broker’s external syncpoint coordinator. The syncpoint coordinator is the broker’s queue manager on distributed platforms and RRS (Resource Recovery Services) on z/OS. If you select this value, any messages received by the node are globally coordinated using an XA JMS Session.
    • You can set the persistence of the outgoing JMS message by using the Delivery Mode property. Select and option from the drop-down list:
      • Non Persistent to indicate to the JMS provider that the message should be treated as non persistent.
      • Persistent to mark messages as persistent to the JMS provider and that they should be preserved until successfully delivered to a receiving JMS client application.
    • Enter a value for Message Expiration to request that the JMS provider keeps the output JMS message for a specified time.

      Enter a value in milliseconds to specify how long the message will be kept by the JMS provider. The default value 0 is used to indicate that the message should not expire.

    • To assign a relative importance to the message, select an option from the Message Priority drop-down list. This value can be used for message selection by a receiving JMS client application or a JMSOutput node.

      Enter a value, where valid values for message priority are from 0 (lowest) to 9 (highest). The default value is 4, which indicates medium priority. Priorities in the range 0 to 4 relate to normal delivery. Priorities in the range 5 to 9 relate to graduations of expedited delivery.

  6. Select Validation in the properties dialog navigator to set the node properties that relate to output message validation.
    • Select an option from the Validate drop-down list:
      • None
      • Content and Value
      • Content
      • Inherit
      If you select Content and Value or Content, select aFailure Action from the drop-down list:
      • User Trace
      • Local Error Log
      • Exception (default value)
      • Exception List

    For more details, refer to Validating messages and Validation properties for messages in the MRM domain.

  7. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  8. Click Apply to make the changes to the JMSOutput node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog box and discard all the changes that you have made to the properties.

Connecting the terminals

Connect the in terminal of the JMSOutput node to the node from which outbound messages are routed.

Connect the out terminal of the JMSOutput node to another node in the message flow if you want to process the message further, to process errors, or to send the message to an additional destination.

Configuring for coordinated transactions

Start of change

When you include a JMSOutput node in a message flow, the value that you set for Transaction Mode defines whether messages are sent under syncpoint.

  • If you set the Transaction Mode to global, the message is sent under external syncpoint coordination; that is, within a WebSphere MQ unit of work. Any messages subsequently sent by an output node in the same instance of the message flow are put under syncpoint, unless the output node has explicitly overridden this.
  • If you set the Transaction Mode to local, the message is sent under the local syncpoint control of the JMSOutput node. Any messages subsequently sent by an output node in the flow are not put under local syncpoint, unless an individual output node has specified that the message must be put under local syncpoint.
  • If you set the Transaction Mode to none, the message is not sent under syncpoint. Any messages subsequently sent by an output node in the flow are not put under syncpoint, unless an individual output node has specified that the message must be put under syncpoint.

The JMS provider can supply additional jar files that are required for transactional support. Refer to the JMS provider documentation. For instance, on distributed systems, the WebSphere MQ JMS provider supplies an extra jar file com.ibm,mqetclient.jar, which must also be added to the broker shared_classes directory. Refer to Making the JMS Provider client available to the JMS Nodes in this topic.

When messages are to be received under external syncpoint, additional configuration steps are required. These steps need only be applied the first time that a JMSOutput or JMSInput is deployed to the broker for a particular JMS provider:
  • On distributed systems, the external syncpoint coordinator for the broker is WebSphere MQ. Before you deploy a message flow where the Transaction Coordination is set to Global, modify the queue manager .ini file to include extra definitions for each JMS provider Resource Manager that participates in globally coordinated transactions.
    • On Windows:
      • If you have WebSphere MQ Version 5.0 installed, start WebSphere MQ Services and right-click the queue manager name. Select Properties and click the Resource properties tab.
      • If you have WebSphere MQ Version 6.0 installed, start WebSphere MQ Explorer and right-click the queue manager name in the left pane. Select Properties and select XA resource managers in the left pane. Refer to the WebSphere MQ System Administration Guide for more information.
        Set the SwitchFile property to the following value:
        install_dir/bin/ JMSSwitch.dll  
        XAOpenString=Initial Context,location JNDI,Optional_parms
        ThreadOfControl=THREAD 
    • On Linux and UNIX systems, add a stanza to the queue manager ini file for each JMS provider. Refer to the WebSphere MQ System Administration Guide for more information.
      For example:
      XAResourceManager:
      Name=Jms_Provider_Name 
      SwitchFile=/install_dir/bin/ JMSSwitch.so
      XAOpenString=Initial Context,location JNDI,Optional_parms
      ThreadOfControl=THREAD
      Where

      Name is an installation defined name that identifies a JMS provider Resource Manager.

      SwitchFile is the file system path to the JMSSwitch library that is supplied in the bin directory of the broker.

      The values for XAOpenString are as follows:
      • Initial Context is the value that is set in the JMSInput node basic property Initial Context Factory.
      • location JNDI is the value that is set in the JMSInput node basic property Location of JNDI. This value should include the leading keyword file:/, iiop:/ or ldap:/
      The following parameters are optional:
      • LDAP Principal, which matches the value that is set for the broker by using the mqsicreatebroker or mqsichangebroker commands.
      • LDAP Credentials, which matches the value that is set for the broker by using the mqsicreatebroker or mqsichangebroker commands.
      • Recovery Connection Factory Name, which is the JNDI administered connection factory that is defined in the bindings file. If a value is not specified, a default value for recoverXAQCF must be added to the bindings file. In either case, the Recovery Connection Factory should be defined as an XA Queue Connection Factory for the JMS provider that is associated with the Initial Context Factory.

      The optional parameters are comma separated and are positional. Therefore, any parameters that are missing must be represented by a comma.

      1. Update the Java CLASSPATH environment variable for the broker's queue manager to include a reference to xarecovery.jar. For example,
        <Broker Installation Path>/classes/xarecovery.jar
      2. Update the Java PATH environment variable for the broker's queue manager to point to the bin directory, which is where the switch file is located. For example,
        <Broker Installation Path>/bin

      XA cannot use the same queue manager for both the broker and the provider until WebSphere MQ Version 5.3, CSD12 and WebSphere MQ Version 6.0 Fix Pack 1.

    • On z/OS, the external syncpoint manager is Resource Recovery Services (RRS). The only JMS provider that is supported on z/OS is WebSphere MQ JMS. The only Transport option that is supported for WebSphere MQ JMS on z/OS is the Bind option.

      Syncpoint control for the JMS provider is managed with RRS syncpoint coordination of the queue manager of the broker. You do not need to modify the .ini file.

End of change

Terminals and properties

The terminals of the JMSOutput 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 propagated to this terminal are not validated.
Out The output terminal to which the message is routed if it is successfully retrieved from the WebSphere MQ queue.
Catch The output terminal to which the message is routed if an exception is thrown downstream and caught by this node.

The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog 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 Basic properties of the JMSOutput node are described in the following table.

Property M C Default Description
Initial Context Factory Yes   com.sun.jndi.fscontext.RefFSContextFactory This is the starting point for a JNDI name space. A JMS application uses the initial context to obtain and look up the connection factory and queue or topic objects for the JMS provider.

The default value is that which is used when WebSphere MQ Java is used as the JMS provider.

Location JNDI Bindings No     The system path or the LDAP location for the bindings file.
Connection Factory Name No     The name of the connection factory that is used by the JMSOutput node to create a connection to the JMS provider.

The publish/subscribe properties of the JMSOutput node are described in the following table.

Property M C Default Description
Publisher Topic No     The name of the topic from which the node receives published messages.

The Point to Point properties of the JMSOutput node are described in the following table.

Property M C Default Description
Destination Queue No     The name of the queue to which the node publishes outgoing messages.

The Request properties of the JMSOutput node are described in the following table.

Property M C Default Description
Destination Mode No   Destination Name This property is used to determine whether the message is to be treated as a request of a datagram or to be treated as a reply.
Reply To Destination No     This value is the name of the JMS destination to which the receiving application should send a reply message. For a reply message to be returned to this JMS destination, the JMS destination name must be known to the domain of the JMS provider that is used by the receiving client.

The Advanced properties of the JMSOutput node are described in the following table.

Property M C Default Description
New Correlation ID No     This property is selected if a New Correlation ID is required.
Transaction Mode Yes No None This property is to determine whether the incoming message is received under syncpoint. Valid values are None, local, and global.
Delivery Mode No   Non Persistent Message selector that will filter messages according to the message delivery mode.
Message Expiration No   0 This property value is to request that the JMS provider keeps the output JMS message for a specified time.

Values are in milliseconds and the default value 0 is used to indicate that the message should not expire.

Message Priority No   4 This property value assigns relative importance to the message. This value can be used for message selection by a receiving JMS client application or a JMSOutput node.

The Validation properties of the JMSOutput node are described in the following table.

Refer to Validation properties for messages in the MRM domain for a full description of these properties.
Property M C Default Description
Validate Yes Yes None This property determines whether validation takes place. Valid values are None, Content, and Content And Value.
Failure Action Yes No Exception This property determines 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, and Exception List.
Include All Value Constraints Yes No Selected This property cannot be edited. The default action, indicated by the check box being selected, is that basic value constraint checks are included in Content and Value validation.
Fix Yes No None This property cannot be edited.

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

Property M C Default Description
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.