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, which handle messages that are 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 have to include an JMSInput node. However, 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 platforms, copy the java .jar files and any native libraries for the JMS provider client into a 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 you must specify each JMS provider java .jar file in the class path in the BIPPROF member of the broker’s PDS (Partitioned Data Set). Then update the LIBPATH with any native libraries, and submit the BIPGEN JCL job to update the broker ENVFILE.

Configuring the JMSOutput node

When you have put an instance of the JMSOutput node into a message flow, you can configure it. Right-click the node in the editor view and click 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.

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.

    • Enter 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 JMSInput 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 JMSInput 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.

    • Enter a Connection Factory Name. The connection factory name is used by the JMSInput node to create a connection to the JMS provider. This name must already exist in the bindings file.
  2. If the JMSOuput node is to be used to subscribe to 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.
  3. If the JMSOutput node is to be used to receive 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 from the Transaction Mode drop-down list. You can choose one of the following options:
      • Select none if the outgoing message is to be treated as non persistent. In this case the message will be 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. In this case the node will use a transacted JMS Session.
      • Select global if the JMSOutput node should participate in a global message flow transaction that will be 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. In this case, any messages received by the node will be 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. You can choose from:
      • 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 Description in the properties dialog navigator to enter a short description, a long description, or both.
  7. 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 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 this 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

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

  • If you set it to global, the message is received 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 it 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 it 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 (non z/OS) platforms, the WebSphere MQ JMS provider supplies an extra jar file com.ibm,mqetclient.jar. This jar 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 platforms, 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, values are configured under the WebSphere MQ Services Resource properties tab. Refer to the WebSphere MQ System Administration Guide for more information.
      Set the SwitchFile property to the following value:
      <Broker Installation Path>/bin/ JMSSwitch.dll  
      XAOpenString=<Initial Context >,<location JNDI>, <Optional>
      ThreadOfControl=THREAD 
    • On distributed platforms (not Windows) 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=/<Broker Installation Path>/bin/ JMSSwitch.so
      XAOpenString=<Initial Context >,<location JNDI>, <Optional>
      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 FixPack 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.

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 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 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.