IBM WebSphere MQ Output Adapter

Contents

Introduction
IBM MQ Middleware Dependencies
Setting Properties
Using the Adapter in a StreamBase Module
Typechecking and Error Handling
Suspend and Resume Behavior
Related Topics

Introduction

The TIBCO StreamBase® Output Adapter for IBM MQ Series allows a StreamBase application to publish messages to an IBM WebSphere MQ server. Each tuple enqueued to the adapter results in a message sent to the server. The adapter is embedded in the StreamBase application. The adapter can be configured to publish messages via topics or an MQ queue.

The adapter's input port can have at most one string field, which holds the message to be sent to the WebSphere MQ server. In addition, the adapter can be configured to send XML messages, in which case the input port may have one or more top-level tuple fields, each is which is used to send an XML message with a specific top-level XML element. The XML message hierarchy is represented by list and nested tuple fields under the top-level tuple field.

The adapter provides a status output port to convey status and error information to the StreamBase application. For example, when the state of the connection to the MQ server changes, a connection status tuple is emitted from the status output port.

The adapter is configured through several properties set in the adapter's Properties view in StreamBase Studio.

IBM MQ Middleware Dependencies

You must obtain the required IBM MQ Java libraries directly from IBM. The easiest way to make the IBM MQ API accessible to StreamBase is install them as Maven dependencies into your Maven repository.

The IBM MQ sample comes with Studio launch files which perform a Maven install to the local Maven repository to aid in running the sample; simply copy the JAR files into the root of the sample project and run each launch config to install. It is however recommended you install to your main Maven repository to make sure they are available to all machines you may distribute your code to.

Obtain the following required IBM MQ JAR files from an IBM MQ Series 7.0 installation, or from IBM:

com.ibm.mq.commonservices.jar
com.ibm.mq.headers.jar
com.ibm.mq.jar
com.ibm.mq.jmqi.jar
com.ibm.mq.pcf.jar
connector.jar

Setting Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Class name: Shows the fully qualified class name that implements the functionality of this adapter. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this adapter starts.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Adapter Properties Tab

Property Description
Bindings Mode If enabled, the adapter connects directly to a local queue manager rather than communicating through a network. When enabled, the Host Name, Port Number, and Channel Name controls are disabled.
Host Name The hostname or IP address of the IBM WebSphere MQ server.
Port Number The TCP port number of the MQ server.
User ID The IBM WebSphere MQ user name, if your site requires authentication when connecting to the MQ server.
Password Password for User ID
Queue Manager The MQ queue manager name.
Use Topics If enabled, the adapter publishes messages via topics. Otherwise, it publishes messages via the configured MQ queue.
Default Topic When configured to use topics, the topic to publish messages to if not overridden by the input tuple's topic field.
Topic Field Name The name of the input port field used to override the default topic value. If this field is null in an enqueued tuple, the default topic is used.
Queue Name The MQ queue name.
Reply To Queue Manager The MQ queue manager name to which responses should be sent. Can be overridden using the corresponding field in the metadata tuple.
Reply To Queue Name The MQ queue name to which responses should be sent. Can be overridden using the corresponding field in the metadata tuple.
Channel Name The MQ channel name.
Unicode Encoding Specifies which of three encoding formats are used to encode Unicode payloads: UTF-16, UTF-16 Big Endian, or UTF-16 Little Endian.
Generate XML from Tuple Fields If enabled, one or more top-level tuple fields may be present in the adapter's input port schema. When a tuple is enqueued on this port, the adapter finds the non-null input field (at most one non-null input field is allowed), and if the field is of type tuple, walks the field to populate the XML message. If the field is of type string, the message is sent verbatim.
Date/Time Format Used when parsing XML to convert date and time XML elements to timestamps. The format of the format string is described in the java.text.SimpleDateFormat class described in the Oracle Java Platform SE reference documentation. Typical format string values include yyyyMMdd and yyyyMMdd HH:mm:ss.
Metadata Field Name The name of an optional metadata tuple field in the adapter's input schema. Use this field to provide one or more specific metadata values in outgoing MQ messages.
Set Identity Context If enabled, the metadata input schema may contain the following additional fields to set the outgoing MQ message's identity context: AccountingToken, ApplicationIdData, UserId.
Send Publish Acknowledgement If enabled, the adapter emits a tuple on its status port with type=Messsage and action=Published each time an MQ message is successfully queued to the MQ queue.
Put Messages Asynchronously If enabled the messages will be put onto queues and topics asynchronously.
Reconnect Interval The time, in seconds, to wait between attempts to connect to the Wall Street Systems server. The valid range is 1 to 60, inclusive.
Quick Connection-Down Detection If enabled, the adapter polls the base queue periodically to quickly detect connection-down conditions.
SSL Cipher Suite The cipher suite to use when connecting to an MQ sever using SSL, or blank for non-SSL connections. When using SSL connections, a truststore file is specified through JVM parameters in the server configuration file:

<param name="jvm-args" value="-Djavax.net.ssl.trustStore=/etc/truststore.jks -Djavax.net.ssl.trustStorePasswords=truststorepass -Djavax.net.ssl.keyStoreType=JKS"/>

Log Level Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

2Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Using the Adapter in a StreamBase Module

This section discusses how to use the IBM WebSphere MQ output adapter in a StreamBase application. As shown in the diagram below depicting the adapter's sample application, the output adapter (MQOutput) has one no input port and one output port to communicate with the surrounding application.

The IBM WebSphere MQ Output Adapter's ports are used as follows:

  • Input Port 1, SendMessage: Tuples enqueued on this port cause the adapter to send messages to the MQ server. The schema of this port is derived from the upstream operator or stream and may have at most one string field and zero or more top-level tuple fields. A tuple received on the adapter's input port may have at most one non-null, top-level field.

    • string field: Contains the contents of a message to be sent to the MQ server verbatim.

    • optional topic string field: When using topics, contains the name of the topic to publish the message to, or null to use the configured default topic.

    • tuple field(s): Allowed only when the adapter's Generate XML from Tuple Fields property is enabled. Each field contains the contents of an XML message with a specific top-level element. Hierarchy in the XML message is represented by list and nested tuple fields.

    • optional metadata tuple field: This field's name must match the value specified in the adapter's Metadata Field Name property. If present, this tuple field may have one or more of the following sub-fields, each of which provides a specific metadata value:

      • AccountingToken, blob: A token that allows work done as a result of the message to be appropriately charged. This field may be present only when the Set Identity Context property is enabled.

      • ApplicationIdData, string: Used to provide additional information about the message or its originator. This field may be present only when the Set Identity Context property is enabled.

      • CharacterSet, string: The coded character set identifier of character data in the application message data. Valid values include:

        • ASCII

        • ISO ASCII

        • EBCDIC

        • Unicode

        • UTF-8

      • CorrelationId, blob: The correlation identifier of the message.

      • Encoding, tuple: Specifies the representation used for binary, packed decimal and floating point values in the application message.

        • Value, int: The bitmap used to specify all encoding values. TIBCO recommends leaving this field null and instead using following fields to specify the encoding:

        • Binary, tuple: The binary encoding value.

          • Normal, bool: True if normal (big endian) is used for binary values.

          • Reversed, bool: True if reversed (little endian) is used for binary values.

        • PackedDecimal, tuple: The packed decimal encoding value.

          • Normal, bool: True if normal (big endian) is used for packed decimal values.

          • Reversed, bool: True if reversed (little endian) is used for packed decimal values.

        • FloatingPoint, tuple: The floating point encoding value.

          • Normal, bool: True if normal (big endian) is used for floating point values.

          • Reversed, bool: True if reversed (little endian) is used for floating point values.

          • S390, bool: True if S390 (zSeries) is used for floating point values.

      • Expiry, int: The expiry time (in tenths of a second) of the message.

      • Feedback, tuple: The nature of the feedback report, used with a MQ messages of type REPORT to indicate the nature of the report.

        • Value, int: Application-defined feedback value. Use one of the following boolean fields for IBM-defined feedback values:

        • Activity

        • ApplCannotBeStarted

        • ApplTypeError

        • ApplTypeError

        • BufferOverflow

        • ChannelCompleted

        • ChannelFail

        • ChannelFailRetry

        • COA

        • COD

        • DataLengthNegative

        • DataLengthTooBig

        • DataLengthZero

        • Expiration

        • IihError

        • LengthOffByOne

        • MaxActivities

        • Nan

        • None

        • NotDelivered

        • NotForwarded

        • Pan

        • Quit

        • StoppedByMsgExit

        • TmError

        • UnsupportedDelivery

        • UnsupportedForwarding

        • XmitQMsgError

      • Format, string: A name that indicates the nature of the data in the message.

      • GroupId, blob: This identifier of the message group to which the message belongs.

      • MessageFlags, tuple: Flags controlling the segmentation and status of the message.

        • Value, int: The message flags bitmap. TIBCO recommends leaving this field null and instead using following boolean fields to specify the message flags:

        • SegmentationInhibited

        • SegmentationAllowed

        • Segment

        • LastSegment

        • MsgInGroup

        • LastMsgInGroup

      • MessageId, blob: The message identifier of the message.

      • MessageType, string: The type of the message:

        • DATAGRAM

        • REQUEST

        • REPLY

        • REPORT

      • OriginalLength, int: The original length of a segmented message.

      • Persistence, tuple: The message persistence:

        • Value, int: The persistence bitmap. TIBCO recommends leaving this field null and instead using following boolean fields to specify the persistence:

        • Persistent

        • NotPersistent

        • PersistenceAsQDef

      • Priority, int: The message priority

      • ReplyToQueueManagerName, string: The MQ queue manager name to which responses should be sent. Overrides the corresponding adapter property.

      • ReplyToQueueName, string: The MQ queue name to which responses should be sent. Overrides the corresponding adapter property.

      • Report, tuple: Specifies which report messages are required, whether the application message data is to be included in them, and also how the message and correlation ID in the report or reply are to be set.

        • Value, int: The bitmap used to specify all report values. TIBCO recommends leaving this field null and instead using following fields to specify the report value:

        • Exception, tuple: Specifies whether application data is included in exception reports.

          • Basic, bool: True if basic information is included in exception reports.

          • Data, bool: True if partial application data is included in exception reports.

          • FullData, bool: True if partial application data is included in exception reports.

        • Exception, tuple: Specifies whether application data is included in exception reports.

          • Basic, bool: True if basic information is included in exception reports.

          • Data, bool: True if partial application data is included in exception reports.

          • FullData, bool: True if partial application data is included in exception reports.

        • Expiration, tuple: Specifies whether application data is included in expiration reports.

          • Basic, bool: True if basic information is included in expiration reports.

          • Data, bool: True if partial application data is included in expiration reports.

          • FullData, bool: True if partial application data is included in expiration reports.

        • COA, tuple: Specifies whether application data is included in confirmation on arrival reports.

          • Basic, bool: True if basic information is included in COA reports.

          • Data, bool: True if partial application data is included in COA reports.

          • FullData, bool: True if partial application data is included in COA reports.

        • COD, tuple: Specifies whether application data is included in confirmation on delivery reports.

          • Basic, bool: True if basic information is included in COD reports.

          • Data, bool: True if partial application data is included in COD reports.

          • FullData, bool: True if partial application data is included in COD reports.

        • NewMsgId, bool: True to use a new message ID in the report or reply.

        • PassMsgId, bool: True to use the ID from original message in the report or reply.

        • CopyMsgIdToCorrelId, bool: True to use the ID of the original message ID for the correlation ID in the report or reply.

        • PassCorrelId, bool: True to use specified correlation in the report or reply.

        • DealLetterQ, bool: Dispose undelivered messages in the dead letter queue.

        • DiscardMsg, bool: True to discard undelivered messages.

        • PassDiscardAndExpiry, bool: True to pass on discarded and expired messages.

      • UserId, string: Identifies the user that originated the message. This field may be present only when the Set Identity Context property is enabled.

  • Output Port 1, OutputStatus: This output port emits status, information, and error tuples. The OutputStatus port has the following schema:

    • type, string: Contains one of the following values describing the type of event that occurred:

      • Connection - A connection to the MQ server has gone up or down.

      • User Input - An input tuple used to send an MQ message was rejected.

      • Suspend/Resume - The adapter has been suspended or resumed.

      • Message - The adapter enqueued a message to the MQ queue.

    • object, string: The name of the object related to the event:

      • Connection - The configured IBM WebSphere MQ server, including the host name, port number, the queue manager name, queue name, and channel name.

      • User Input - The contents of the rejected input tuple.

      • Suspend/Resume - The adapter's name on the canvas.

      • Message - The tuple used to generated the message that was enqueued to the MQ queue.

    • action, string: The action associated with the event

      • Connection - Up or Down

      • User Input - Rejected or Accepted With Warning

      • Suspend/Resume - Suspending or Resumed

      • Message - Published

    • message, string: A human-readable description of the event

    • userInput, tuple: A copy of the tuple processed by the adapter when type type is User Input or null otherwise

Add an instance of the adapter to a new StreamBase application as follows:

  1. In StreamBase Studio, create a project an EventFlow diagram to host the adapter.

  2. Drag an instance of the IBM WebSphere MQ output adapter from the Operators and Adapter drawer in the Palette view to the canvas.

  3. Select or double-click the adapter icon. In the Properties view, select the Adapter Properties tab and fill in values for the IBM WebSphere MQ server host, port, queue manager name, queue name, and channel name.

  4. Connect Input and Output streams to the adapter input and output ports.

  5. If send MQ messages verbatim, add a string field to the input stream connected to the adapter's input port. If generating XML messages, add or more tuple fields with the name(s) of the top-level XML elements to the input stream.

Typechecking and Error Handling

The IBM WebSphere MQ Output adapter generates the following typecheck messages to help you configure the adapter in your StreamBase application:

  • An invalid port number is provided.

  • The queue manager name is missing.

  • The queue name is missing.

  • The channel name is missing.

  • A non-string or -tuple field is present in the stream feeding the adapter's input port.

  • Two or more string fields are present in the stream feeding the adapter's input port.

  • The adapter is not configured to generate XML, but two or more top-level tuples fields are present in the stream feeding its input port.

  • The adapter is configured to generate XML, but no top-level tuples fields are present in the stream feeding its input port.

  • The reconnection interval is invalid (not between 1 and 60 seconds, inclusive).

The adapter emits tuples on the status port during runtime under various conditions:

  • A connection to the IBM WebSphere MQ server goes up or down.

  • An input tuple used to publish an MQ message is rejected.

  • The adapter is suspended or resumed.

Suspend and Resume Behavior

When suspended, the IBM WebSphere output adapter stops processing input tuples.

When resumed, the adapter begins processing input tuples again.

Related Topics