Wall Street Systems Output Adapter

Contents

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

Introduction

The TIBCO StreamBase® Output Adapter for Wall Street Systems allows a StreamBase application to publish messages to a Wall Street Systems 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 Wall Street Systems 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 Wall Street Systems 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 to copy the required API JARs into the StreamBase installation in the lib/ext directory.

If copying the JAR files to lib/ext is impractical, then for running IBM MQ adapter applications in StreamBase Studio, you must add the IBM MQ JARs to the Java Build Path. For running IBM MQ adapter applications from the command line, you must add the IBM MQ API JARs to the server's CLASSPATH, either by setting an environment variable, or via the <java-vm> element of the server configuration file.

Obtain the following required IBM MQ JAR files from an IBM MQ Series 7.0 installation, or directly 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

Adapter Properties

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 Wall Street Systems server.
Port Number The TCP port number of the Wall Street Systems server.
User ID The IBM WebSphere MQ user name, if your site requires authentication when connecting to the Wall Street Systems server.
Password Password for User ID
Queue Manager The 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 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 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 (as 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.
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.
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, and ALL.

Using the Adapter in a StreamBase Application

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

The Wall Street Systems 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 Wall Street Systems 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 Wall Street Systems 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. This 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 Wall Street Systems server has gone up or down

      • User Input - An input tuple used to send a 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 Wall Street Systems 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

      • 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 Wall Street Systems 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, click the Adapter Properties tab and fill in values for the Wall Street Systems 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 sending 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 Wall Street Systems 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 Wall Street Systems server goes up or down.

  • An input tuple used to publish a message is rejected.

  • The adapter is suspended or resumed.

Suspend and Resume Behavior

When suspended, the Wall Street Systems output adapter stops processing input tuples.

When resumed, the adapter begins processing input tuples again.

Related Topics