Service Integration Bus Destination Handler

© Copyright IBM Corp. 2025 All Rights Reserved.

US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with
IBM Corporation.

Index

Overview

This is a tool for the default messaging provider for WebSphere Application Server.
The tool provides the ability to perform various actions on messages in a Service Integration Bus without writing any custom code.

Here is a list of actions that can be performed by the tool, with example scenarios for their use:
These actions can be performed for all messages on a destination, or a subset of messages on destination selected using:
The tool can connect to the default messaging provider using the following interfaces:
A graphical user interface is provided to aid with the following tasks:

Quick start guide

For most users, the quickest way to get started with the tool is via the graphical user interface as described below.
Quick-start instructions are also provided to use the command line interface in the following section.

Quick start using the graphical user interface

Before you start

You need to have an application client environment that is able to display a graphical interface.
If your WebSphere Application Server environment is running on a UNIX, Linux or z/OS system without a display then you have two options:
  1. Run the tool on the target machine, pointing at an X Server on your local machine
    This is often easier in secure environments as the target machine usually has access to the security configuration required to connect to the target environment.
    No special configuration is usually needed for Linux desktop machine connecting to a target machine via SSH with X11 Forwarding enabled.
    However, Windows desktop machines do not have an X Server by default. There are a number of Windows X Server products available, as well as SSH utilities that configure X11 Forwarding.
  2. Run the tool on the local machine, and connect remotely to the target machine
    In a secure environment, you will need to configure your local client environment to be able to connect securely to the target environment.

Running the tool graphically

Follow the steps below to run the graphical user interface, and view the contents of a queue:
  1. Run the following command from the directory containing the JAR file and XML files:
    java -jar SIBDestinationHandler*.jar
  2. The following window should be displayed.
    Click the "Configure..." button in the "Runtime discovery" section.
    Main GUI dialog
  3. The following dialog should be displayed.
    Type in the details to connect to the SOAP_CONNECTOR_ADDRESS of the deployment manager of the cell, or the server in a single-server environment.
    For secure environments, specify a username and password fro the connection.
    Click OK once the details are entered.
    Runtime discovery configuration dialog
  4. Confirm a successful connection has been made to the correct environment, this is displayed in the output panel at the bottom of the window.
    Use the drop-down menus to select the connection information for your chosen bus.
    For secure environment, ensure you select secure connection details for the bootstrap server (with a BoostrapSecureMessaging transport chain) and that the InboundSecureMessaging target transport chain is selected.
    Output panel after configuring configuration discovery
  5. Click the "Test connection" button.
    If there is a problem connecting to the bus, use the details in the exception message to diagnose the issue, as well as any messages printed to the command window used to launch the tool.
  6. Click "Next", or click on "Destination 1-1" in the left pane, to configure the details of the destination.
    Select the queue you wish to view from the "Queue name" drop-down.
    Destination configuration panel
  7. Click "Run"

Quick start using the command line

Follow the steps below to view the available messages on a queue point by running the tool as an application client.
  1. Choose a node with a running application server that is a server or cluster member of the bus.
  2. Transfer (using binary FTP or other transfer method) file sib.desthandler.appclient.ear to a directory on the chosen node
  3. Transfer one of the following XML configuration files (extract from the JAR/samples) to the same directory:
    samples/viewQueuePoint_secure.xml if bus security is enabled
    samples/viewQueuePoint.xml if bus security is not enabled
  4. Edit the XML configuration file in a text editor and replace the following text:
    For viewQueuePoint.xml only:
     For viewQueuePoint_secure.xml only:
  5. Run the following command from the directory containing the ear and XML files:
    java -jar SIBDestinationHandler*.jar viewQueuePoint.xml
For other options of how to run the tool (including considerations when running on a machine that does not host a member of the bus), see the running the tool section.
For other examples of actions that can be performed by the tool, see the examples section.
For full details of the contents of the configuration file, including configuring different types of connection to the bus, see the configuration file section.

Running the tool

The following options are provided for running the tool.
If the tool is run without any arguments in a client environment the graphical user interface is displayed, which can be used to create, test and run configuration files.
The details of the configuration file is documented in the configuration file section.

Running the tool as an application client

Use this approach to run the tool without installing any applications into an application server or cluster.

Binary to use: SIBDestinationHandler*.jar

Command line:
 If CONFIG_FILE is omitted from the command line then the graphical user interface will be started.

Considerations for secure connections

You need to configure SSL on the SOAP/RMI connections used to setup the client container (and any JMX connections used by the tool) separately to SSL for messaging connections.
Review the ssl.client.props client configuration file section of the information center for instructions on configuring SSL for SOAP/RMI connections.

Review the Secure transport considerations section of the information center for instructions on configuring SSL for messaging connections.

Running the tool as a thin application client

Binary to use: SIBDestinationHandler*.jar
Run: java -jar SIBDestinationHandler*.jar
The single, optional application parameter is the configuration file for the tool, and this is omitted then the graphical user interface will be started.

Considerations for secure connections

If messaging connections are to be used by the tool, review the Secure transport considerations section of the information center.
If JMX connections are to be used by the tool to read messages, review the ssl.client.props client configuration file section of the information center.

Configuration file

A single XML configuration file is read each time the tool runs.
The configuration file specifies how the tool connects to buses, the destinations from which to read messages, the rules to apply and the actions to perform.

You can create configuration files in any text or XML editor, or you can use the graphical user interface provided with the tool.

The full list of tags that can be specified are provided in this section.
Examples are provided in the next section.

A copy of the DTD used to validate the XML is supplied in the installation package:
dtd/SIBDesthandler.dtd
Do not specify a DOCTYPE declaration in the configuration file, as this will result in an error. The DTD is enforced within the tool.

Tables of attributes in this section have the following columns
Name
 Required?
 Allowed values
 Description

Masking passwords

All password fields within the configuration file can be masked so that they cannot be seen accidentally when viewing or editing the file.
These fields are masked automatically when a configuration file is created using the graphical user interface.
To mask a password manually, run the following class within the sib.desthandler.jar package with a single argument (from any J2SE / J2EE 1.4 or higher JRE):
com.ibm.ws.sib.desthandler.SIBDestHandlerPwdMask

Example command line

java -classpath sib.desthandler.jar com.ibm.ws.sib.desthandler.SIBDestHandlerPwdMask mypassword

Example output

X[06121b0a18181c04190f]

SIBDestHandler tag

The XML file contains a single SIBDestHandler tag as the outer-most element, which contains one or more connection tags.

Connection tags

The following tags can be used to establish connections to the bus. Each should contain one or more destination tags.

SIBConnection tag

This tag instructs the tool to connect as a messaging application to a bus.

This tag should contain one or more Queue tags (messages cannot be read from subscriptions or remote queue points using this interface).
For each queue tag within a SIBConnection tag, the tool will read messages from a single queue point.
To view multiple queue points for a destination, create multiple SIBConnection tags (each with a Queue tag) and target each SIBConnection tag at an individual messaging engine in the cluster using the target and targetType attributes (described below).

This tag can only be used to read messages which are available to applications.
All message properties can be read and used in rules.
SQL92 selectors can be used to perform selection of messages within the messaging engine.

Example SIBConnection tag for connecting as web or EJB application

<SIBConnection bus="MYBUS">

Example SIBConnection tag for connecting securely as a web or EJB application

<SIBConnection
  bus="MYBUS"
  targetTransportChain="InboundSecureMessaging"
  username="myuser"
  password="X[06121b0a18181c04190f]">

Example SIBConnection tag for connecting as a client application

<SIBConnection
  bus="MYBUS"
  providerEndpoints="myhost.mydomain.com:7276:BootstrapBasicMessaging"
  targetTransportChain="InboundBasicMessaging">

Example SIBConnection tag for connecting securely as a client application

<SIBConnection
  bus="MYBUS"
  providerEndpoints="myhost.mydomain.com:7286:BootstrapSecureMessaging"
  targetTransportChain="InboundSecureMessaging"
  username="myuser"
  password="X[06121b0a18181c04190f]">

Full list of attributes

bus
 Required
 String
 The name of the bus to connect to.
When the tool runs as a web or EJB application in an application server in the same cell as the bus, and the SIB Service enabled on that server, this is the only attribute required.
See the SIB service settings topic in the information center for details of how to enable the SIB Service.
username
 Optional
 String
 The username used to authorize the tool when bus security is enabled.
password
 Optional
 String
 The password used to authorize the tool when bus security is enabled.
targetTransportChain
 Optional
 String
 The name of a messaging engine inbound transport that is enabled on the server where the messaging engine is running. See the Inbound transport options topic in the information center for more information.
providerEndpoints
 Optional
 String
 The provider endpoints to use when establishing a bootstrap connection from outside the cell to a server inside the cell with the SIB Service enabled. See the Configuring a connection to a non-default bootstrap server topic in the information center for more information.
targetType
 Optional
 BusMember / ME / Custom
 These attributes allow selection (or preference) of an individual messaging engine or bus member to connect to.
This is useful when multiple messaging engines exist in a bus, to allow the tool to connect directly to the messaging engine where messages are located rather than interacting with the queue indirectly via another messaging engine.
When the bus member that hosts the destination is a cluster with multiple messaging engines (hence the destination is partitioned across those messaging engines), these properties can be used to choose which queue point to interact with - see example 10.
See the Configuring the messaging engine selection process for applications topic of the information center for more information.
target
 Optional
 String
targetSignificance
 Optional
 Preferred / Required
connectionProximity
 Optional
 Server / Cluster / Host / Bus
 See the Configuring the messaging engine selection process for applications topic of the information center for more information.

JMXConnection tag

This tag establishes a Java Management Extensions (JMX) administrative connection to the WebSphere Application Server infrastructure.
This tag can be used to read messages on any queue point for a queue, or any subscription on any publication point for a topic space.
This includes messages that are currently allocated to applications or contained within in-flight transactions (hence cannot be read using a SIBConnection tag).

Only a subset of message properties are available using JMX connections. No user defined properties can be viewed or used in rules.
It is possible to delete messages using a JMX connection tag, however actions that move or copy messages cannot be used.
SLQ92 selectors cannot be used with JMX connections.

This tag should contain one or more Queue or Subscription tags.

Example JMXConnection tag using Remote Method Invocation (RMI)

<JMXConnection
  bus="MYBUS"
  connectorType="RMI"
  connectorHost="myhost.mydomain.com"
  connectorPort="2809"
  username="myuser"
  password="X[06121b0a18181c04190f]">

Full list of attributes

bus
 Required
 String
 The name of the bus to connect to.
connectorType
 Required
 RMI / SOAP
 The type of connector to use to establish the JMX connection.
connectorHost
 Required
 String
 The hostname or IP address of the deployment manager, or the application server hosting the messaging engine.
If the connection is made to the deployment manager, messages on all queue and publication points can be read.
If the connection is made to an individual server hosting a messaging engine, messages can only be read from queue and publication points located on that messaging engine.
connectorPort
 Required
 Integer
 The port of the BOOTSTRAP_ADDRESS of the deployment manager or application server. Alternatively specify the port of the ORB_LISTENER_ADDRESS for RMI connections, or the port of the SOAP_CONNECTOR_ADDRESS for SOAP connections.
username
 Optional
 String
 The username to authorize the tool when administrative security is enabled.
password
 Optional
 String
 The password to authorize the tool when administrative security is enabled.
maxMsgSize
 Optional
 Integer
 The maximum payload size, in bytes, to download for each message. The default is 10485760 (10MB)

FileSystem tag

This tag specifies that the tool will read messages previously dumped to files on a filesystem.
This tag should contain one or more Folder tags.
This tag has no attributes, as the path is specified individually for each Folder tag it contains.

Destination tags

The following tags specify the details of destinations that the tool should read messages from.
Each should contain one or more Rule tags.

Queue tag

This tag specifies the name of a queue from which the tool should read messages.
This tag can be used inside SIBConnection or JMXConnection tags.

When used within a SIBConnection tag, the tool uses the name specified in the tag to access a single queue point in the bus.
The name of an alias destination can be used, as long as it resolves to a queue point in the same bus the tool connects to.

When used within a JMXConnection tag, the tool uses the name specified in the tag to lookup all SIBQueuePoint management beans active for that queue destination.

Example Queue tag

<Queue name="_SYSTEM.Exception.Destination.MyNode.MyServer-MyBus">

Full list of attributes

name
 Required
 String
 The name of the destination.
continueAfterFailure
 Optional
 true / false
 Whether the tool should continue processing rules for an individual message after an exception is encountered in a rule. The default is false.
See the Rule tag for details.
selector
 Optional
 String
 An SQL92 selector string which is evaluated in the messaging engine before messages are sent to the tool. It overrides any selection criteria specified within the rules for this destination tag. This attribute is ignored for JMX connections.

Subscription tag

This tag specifies a subscription, or set of subscriptions, on a topic space from which the tool should read messages.
This tag can be used inside a JMXConnection tag (it cannot be used inside a SIBConnection tag).

Example Subscription tag

<Subscription topicSpace="Default.Topic.Space" id="MyClientId##MySubId">

Full list of attributes

topicSpace
 Required
 String
 The name of the topic space.
id
 Required
 String
 The subscriber identifier. JMS durable subscribers have an identifier made up of the Client ID configured on the connection factory and the Subscription ID specified by the application, separated by '##'. For message-driven beans, both the Client ID and Subscription ID are specified on the activation specification.
A single '*' can be specified at the end of the attribute to match all subscription starting with a particular string.
continueAfterFailure
 Optional
 true / false
 Whether the tool should continue processing rules for an individual message after an exception is encountered in a rule. The default is false.
See the Rule tag for details.

RemoteQueuePoint tag

This tag specifies the tool should read messages from remote queue points for a particular queue.
By default messages from all remote queue points active in the bus will be read.
This tag can be used inside a JMXConnection tag (it cannot be used inside a SIBConnection tag).

Full list of attributes

name Required
 String
 The name of the queue.
messagingEngine
 Optional
 String
 If specified, only messages on the remote queue point in the specified messaging engine are read by the tool.

RemotePublicationPoint tag

This tag specifies the tool should read messages from remote publication points for a particular topic space.
By default messages from all remote publication points active in the bus will be read.
This tag can be used inside a JMXConnection tag (it cannot be used inside a SIBConnection tag).

Full list of attributes

name Required
 String
 The name of the topic space.
messagingEngine
 Optional
 String
 If specified, only messages on the remote publication point in the specified messaging engine are read by the tool.

Folder tag

This tag specifies a folder that contains messages previously dumped using a RawDumpAction tag.
This tag can be used inside a FileSystem tag.

Only the following JMS message types will be read from the folder:
Message, TextMessage, BytesMessage, ObjectMessage
Other message types will be ignored.

Example Folder tags

Windows:
<Folder path="c:\location\of\raw\dump">
UNIX, Linux or z/OS:
<Folder path="/location/of/raw/dump">

Full list of attributes

path
 Required
 String
 The path of the folder containing messages previously dumped using a RawDumpAction.
continueAfterFailure
 Optional
 true / false
 Whether the tool should continue processing rules for an individual message after an exception is encountered in a rule. The default is false.
See the Rule tag for details.

Rule tag

Multiple rule tags can be specified within each destination tag.
These will be evaluated (in the order they are defined in the configuration file) independently for each message read from the destination.

This tag contains exactly one match criteria tag (which may contain nested conditions) followed by one or more action tag which will be performed for each message that the criteria matches.
If an individual action within a rule fails, that rule will not perform any further actions on that message.
However, later rules within the destination will be executed if the continueAfterFailure attribute on the destination tag is set to true (the default is false).
The tool will continue to process the next message on the destination regardless of any failure.

See the examples section for examples of how rules can be used and combined.

Full list of attributes

skipMessages
 Optional Integer The number matching messages to skip, before any actions are called. The default is 0 (do not skip any messages).
maximumMessages
 Optional
 Integer
 The maximum number matching messages to call actions for. The default is 0 (unlimited).

Match criteria tags

The following tags can be used to build the match criteria for a rule.

MatchAnyMessage criteria tag

This criteria is true for any message.
This tag has no attributes or children.
See example 1.

MatchMessageProperty criteria tag

This criteria is true for messages where the specified message property matches the comparison tag it contains.
This tag should contain exactly one comparison tag.
See example 4.

Full list of attributes

name
 Required
 String
 The name of the message property to apply the comparison to.
To review the available message properties for a message, use the DumpMessage action to print a textual representation of the message.
Properties will always be compared in the form they are dumped by the tool, including in cases where this is different to the raw form which would be used in an SQL92 selector.

MatchMessageText criteria tag

This criteria is true for messages where the text body of the message matches the comparison tag it contains.
This criteria can only be used with binary (BytesMessage) or text (TextMessage) messages.
This tag should contain exactly one comparison tag.

Full list of attributes

charSet
 Optional
 String
 The Java character set to use to construct a text representation of a binary message before performing the comparison.

MatchXPathExpression criteria tag

This criteria is true for messages where result of the specified XPath expression, evaluated against the text body of the message, matches the comparison tag it contains.
This criteria can only be used with binary (BytesMessage) or text (TextMessage) messages.
This tag should contain exactly one comparison tag.

This tag can only be used in J2SE / JEE 5.0 and higher runtime environments.

Example MatchXPathExpression tags

<!-- Using an XPath expression with a boolean result -->
<MatchXPathExpression expression="RootTag/InnerTag/attribute::myattr = 'myvalue'">
  <StringCompare operation="equals" matchString="true"/>
</MatchXPathExpression>

<!-- Using an XPath expression with a text result -->
<MatchXPathExpression expression="RootTag/InnerTag/attribute::myattr">
  <StringCompare operation="equals" matchString="myvalue"/>
</MatchXPathExpression>

Full list of attributes

charSet
 Optional
 String
 The Java character set to use to construct a text representation of a binary message before performing the comparison.

And criteria tag

This criteria is true if all criteria tags inside it are true.
This tag should contain one or more criteria tags.
This tag has no attributes.
See example 9.

Or criteria tag

This criteria is true if any criteria tags inside it are true.
This tag should contain one or more criteria tags.
This tag has no attributes.
See example 9.

Comparison tags

One of the following tags can be used within a MatchMessageProperty tag to apply a comparison to the message property.

ValueIsNull comparison tag

This comparison is true if the message property or other item being compared is unset (has a null value), optionally also returns true for an empty string.
This tag has no children.
See example 9.

Full list of attributes

matchEmptyString
 Optional
 true / false
 Whether an empty string is considered a null value. Default is false.

ValueNotNull comparison tag

This comparison is true if the message property is set to any value, by default returns true for an empty string.
This tag has no children.
See example 9.

Full list of attributes

matchEmptyString
 Optional
 true / false
 Whether an empty string is considered a non-null value. Default is false.

StringCompare comparison tag

This comparison uses the specified operation to compare the value (when represented in text form) with the match string.
This tag has no children.
See example 4.

Full list of attributes

matchString
 Required
 String
 The match string to compare to.
operation
 Required
 contains
 The value contains the match string
equals
 The value equals the match string.
greaterThan
 The value is lexicographically greater than the match string.
greaterThanOrEqual
 The value is lexicographically greater than the value or equal to the match string.
lessThan
 The value is lexicographically less than the match string.
lessThanOrEqual
 The value is lexicographically less than the value or equal to the match string.
ignoreCase
 Optional
 true / false
 Whether the comparison should be case insensitive. Default is false.

RegexCompare comparison tag

This comparison is true if specified regular expression can be matched against the value (when represented in text form).
This tag has no children.
See example 9.

Full list of attributes

regex
 Required
 String
 The regular expression. The syntax is described in the Java 2 Platform javadoc for the java.util.regex.Pattern class.
matchWhole
 Optional
 true / false
 Whether the whole string must match the regular expression. Default is false (the regular expression can be contained at any point in the value).
ignoreCase
 Optional
 true / false
 Whether the comparison should be case insensitive. Default is false.

DateCompare comparison tag

This comparison uses the specified operation to compare the value (converted into a date) with the match date.
This tag has no children.
See example 11.

Full list of attributes

matchDate
 Required
 String
 The match string to compare to.
matchDateFormat
 Optional
 String If the special value epoch is used, the matchDate attribute is interpreted as a long value containing the number milliseconds since the epoch. This is the default.
If the special value age is used, the matchDate attribute is interpreted as a long value containing an age in milliseconds. The age is calculated as the current time when the rule is run minus the time in the specified property of the message - see example 11.
Any other string is used as a date format to interpret the matchDate attribute. The syntax is described in the Java 2 Platform javadoc for the java.text.SimpleDateFormat class.
valueDateFormat
 Optional
 String
 If the special value epoch is used, the value is interpreted as a long value containing the number milliseconds since the epoch. This is the default.
Any other string is used as a date format to interpret the value. The syntax is described in the Java 2 Platform javadoc for the java.text.SimpleDateFormat class.
operation
 Required
 equals
 The value equals the match date.
greaterThan
 The value is later than the match date.
greaterThanOrEqual
 The value is later than or equal to the match date.
lessThan
 The value is earlier than the match date.
lessThanOrEqual
 The value is earlier than or equal to the match date.

DecimalCompare comparison tag

This comparison uses the specified operation to compare the value (converted into a 64bit signed decimal value) with the match value.
This tag has no children.
See example 11.

Full list of attributes

matchValue
 Required
 Integer
 The match value to compare to.
operation
 Required
 equals
 The value equals the match value.
greaterThan
 The value is greater than the match value.
greaterThanOrEqual
 The value is less than or equal to the match value.
lessThan
 The value is less than the match value.
lessThanOrEqual
 The value is less than or equal to the match value.

Action tags

Specify one or more of the following tags within each rule tag.

MoveAction action tag

This action can only be used in rules that are inside a SIBConnection tag.
It moves a message from one queue point to another queue point.

Optionally it can contain a single SIBTargetConnection tag with details of the connection to use to send messages.
The attributes of the SIBTargetConnection tag are the same as the SIBConnection tag, and the SIBTargetConnection tag has no children.
The behavior depends on the existence of a SIBTargetConnection tag as follows:
Some message properties will be altered in the message when it arrives on the target destination as a new SIBus message.
For example a new SI_SystemMessageID (JMS_IBM_System_MessageID) will be generated by the bus.
Application properties, such as the JMS message identifier, correlation identifier and user properties are maintained.

If a previous MoveAction, ResubmitAction or DeleteAction has been performed for the message within this rule or a previous rule, the action will be skipped without an error occurring.

Full list of attributes

targetDestination
 Required
 String
 The name of the target destination.
targetBus
 Optional
 String
 The target bus name. This is only required if the bus is defined as a foreign bus in the bus the tool connects to, using the source connection or the SIBTargetConnection tag (if specified).

ResubmitAction action tag

This action can only be used in rules that are inside a SIBConnection tag.
It moves the message to the destination specified in the SI_ExceptionProblemDestination (JMS_IBM_ExceptionProblemDestination) message property.
The same connection is used to consume the message from the source queue point and to send it to the target queue point.

If the message does not have an exception problem destination set then the action will fail, and the message will remain on the source destination.
This case can be handled by inserting an earlier rule with criteria that match messages with a null SI_ExceptionProblemDestination property and moves them to another destination.

Some message properties will be altered in the message when it arrives on the target destination as a new SIBus message.
For example a new SI_SystemMessageID (JMS_IBM_System_MessageID) will be generated by the bus.
Application properties, such as the JMS message identifier, correlation identifier and user properties are maintained.

If a previous MoveAction, ResubmitAction or DeleteAction has been performed for the message within this rule or a previous rule, the action will be skipped without an error occurring.

This tag has no attributes or children.

See example 11.

DeleteAction action tag

This action can be used in any rule.
For rules inside SIBConnection and JMXConnection tags, the message is removed from the queue.
For rules inside Folder tags, the files containing the body and properties of the message are deleted from the file system.

If a previous MoveAction, ResubmitAction or DeleteAction has been performed for the message within this rule or a previous rule, the action will be skipped without an error occurring.

This tag has no attributes or children.

CopyAction action tag

This action can only be used in rules that are inside a SIBConnection or Folder tag.
It cannot be used within a JMXConnection tag, as only a subset of messages properties are available in the message so a copy of the message cannot be made.
This action establishes a new connection (which can be to a different bus) and sends a copy of the message to the target destination.

Is must contain a SIBTargetConnection tag with details of the connection to use to send messages.
The attributes of the SIBTargetConnection tag are the same as the SIBConnection tag, and the SIBTargetConnection tag has no children.

Some message properties will be altered in the message when it arrives on the target destination as a new SIBus message.
For example a new SI_SystemMessageID (JMS_IBM_System_MessageID) will be generated by the bus.
When restoring a message from a file a new JMS message identifier will also be generated.
Application properties, such as the JMS correlation identifier and user properties are maintained when copying a message from one destination to another.

See example 8.

Full list of attributes

targetDestination
 Required
 String
 The name
targetBus
 Optional
 String
 The target bus name. This is only required if the bus is defined as a foreign bus in the bus the tool connects to using the SIBTargetConnection tag.
destinationType
 Optional
 Queue / TopicSpace
 The type of destination. Default is Queue.
topicName
 Optional
 String
 The topic to publish on, when sending to a topic space.

DumpAction action tag

This action prints a textual summary of the message to the output location of the tool (the console for example).
The messages remain unchanged on the destination.

See example 1.

Example output from a DumpAction tag within a SIBConnection tag for a JMS ObjectMessage:
================= com.ibm.ws.sib.mfp.impl.JsJmsObjectMessageImpl =================
Bus:                           Bus1
Destination:                   _SYSTEM.Exception.Destination.MyNode.server1-Bus1
MessagingEngine:               MyNode.server1-Bus1
SI_Reliability:                ExpressNonPersistent
SI_TimeToLive:                 12345678
RemainingTimeToLive:           12345678
SI_Priority:                   0
SI_ReplyPriority:              3
SI_ReplyReliability:           ExpressNonPersistent
SI_ReplyTimeToLive:            12345678
ReverseRoutingPath:            [dest][name]MyReplyQueue[/name][bus]ReplyBus[/bus][/dest]
SI_RedeliveredCount:           0
JMSMessageID:                  ID:8a45a71e4bef98171c1ead86110a134f0000000000000005
JMSDestination:                queue://Q1?busName=Bus1&readAhead=AlwaysOn&priority=5
JMSReplyTo:                    queue://MyReplyQueue?busName=ReplyBus&deliveryMode=NonPersistent&readAhead=AlwaysOn&timeToLive=12345678&priority=3
JMSDeliveryMode:               1 (NON_PERSISTENT)
JMSTimestamp:                  1227010566312 (18 November 2008 12:16:06 GMT)
JMSExpiration:                 1227022911990
JMSRedelivered:                false
JMSPriority:                   0
JMSXUserID:                   
JMSXAppID:                     Service Integration Bus
JMS_IBM_System_MessageID:      D36A04A3DF0580E7_40500905
JMS_IBM_ExceptionMessage:      CWSIK0035E: A message cannot be delivered to destination Q1 on messaging engine MyNode.server1-Bus1 because it has rolled back more times than its redelivery threshold.
JMS_IBM_ExceptionReason:       35
JMS_IBM_ExceptionTimestamp:    1227010566375 (18 November 2008 12:16:06 GMT)
JMS_IBM_ExceptionProblemDestination: Q1
JMS_IBM_MsgType:               1
JMS_IBM_Report_PAN:            0
JMS_IBM_Report_NAN:            0
JMS_IBM_Report_Pass_Msg_ID:    0
JMS_IBM_Report_Pass_Correl_ID: 0
JMS_IBM_Report_Discard_Msg:    0
------------------------ Body: Object Message (124Bytes) -------------------------
object.toString(): "TestBucket$MySimpleClass@363b5371[My string value/12345/9223372036854775807]"
Serialized object bytes:
0x0000  aced0005 73720018 54657374 4275636b  |....sr..TestBuck|
0x0010  6574244d 7953696d 706c6543 6c617373  |et$MySimpleClass|
0x0020  acc76515 8d2820ec 02000349 00056d79  |..e..( ....I..my|
0x0030  496e744a 00066d79 4c6f6e67 4c00086d  |IntJ..myLongL..m|
0x0040  79537472 696e6774 00124c6a 6176612f  |yStringt..Ljava/|
0x0050  6c616e67 2f537472 696e673b 78700000  |lang/String;xp..|
0x0060  30397fff ffffffff ffff7400 0f4d7920  |09........t..My |
0x0070  73747269 6e672076 616c7565           |string value    |

Example output from a DumpAction tag within a JMXConnection tag for a JMS ObjectMessage:
=============== com.ibm.websphere.sib.admin.SIBQueuedMessageDetail ===============
Bus:                           Bus1
Destination:                   _SYSTEM.Exception.Destination.MyNode.server1-Bus1
MessagingEngine:               MyNode.server1-Bus1
AdminId:                       81001402
State:                         UNLOCKED
SI_Reliability:                ExpressNonPersistent
SI_TimeToLive:                 12345678
SI_Priority:                   0
SI_ReplyPriority:              3
SI_ReplyReliability:           ExpressNonPersistent
SI_ReplyTimeToLive:            12345678
ApproximateLength:             514
MessageWaitTime:               0
MEArrivalTimestamp:            1227010568640 (18 November 2008 12:16:08 GMT)
SI_RedeliveredCount:           0
SI_UserID:                    
SI_Format:                     JMS:object
JMSMessageID:                  ID:153b9322797476af1f64ae8b110a134f0000000000000005
JMSDestination:                queue://Q1?busName=Bus1&readAhead=AlwaysOn&priority=5
JMSReplyTo:                    queue://MyReplyQueue?busName=ReplyBus&readAhead=AlwaysOn&deliveryMode=NonPersistent&timeToLive=12345678&priority=3
JMSDeliveryMode:               1 (NON_PERSISTENT)
JMSTimestamp:                  1227010568594 (18 November 2008 12:16:08 GMT)
JMSExpiration:                 1227022914272 (18 November 2008 15:41:54 GMT)
JMSRedelivered:                false
JMSPriority:                   0
JMSXDeliveryCount:             1
JMSXUserID:                   
JMSXAppID:                     Service Integration Bus
JMS_IBM_System_MessageID:      D36A04A3DF0580E7_40500911
------------------------ Body: Object Message (124Bytes) -------------------------
object.toString(): "TestBucket$MySimpleClass@6b715373[My string value/12345/9223372036854775807]"
Serialized object bytes:
0x0000  aced0005 73720018 54657374 4275636b  |....sr..TestBuck|
0x0010  6574244d 7953696d 706c6543 6c617373  |et$MySimpleClass|
0x0020  acc76515 8d2820ec 02000349 00056d79  |..e..( ....I..my|
0x0030  496e744a 00066d79 4c6f6e67 4c00086d  |IntJ..myLongL..m|
0x0040  79537472 696e6774 00124c6a 6176612f  |yStringt..Ljava/|
0x0050  6c616e67 2f537472 696e673b 78700000  |lang/String;xp..|
0x0060  30397fff ffffffff ffff7400 0f4d7920  |09........t..My |
0x0070  73747269 6e672076 616c7565           |string value    |

Full list of attributes

maximumMessages
 Optional
 Integer
 The maximum number of messages to print. The default is 0 (unlimited).
Message limiting is also available on all actions within a rule, using properties on the rule tag.
dumpBody
 Optional
 true / false
 Whether to output the body of the message. The default is true.
dumpProperties
 Optional
 true / false
 Whether to output the message headers and properties. The default is true.
deserializeObjects
 Optional
 true / false
 Whether to attempt to de-serialize objects in JMS ObjectMessage messages, in order to call Object.toString(). Default is true.
maximumLength
 Optional
 Integer
 Limit the amount of body data output for each message.
For stream and map messages this limit may be exceeded if individual items in the stream/map are long.
For object messages no limit is placed on the toString output.
For hex dumps of bodies the limit is placed on the number of bytes, not the number of characters produced by the hex dump.
For character dumps of bodies the limit is placed on the number of characters.
The default is 0 (unlimited).

RawDumpAction action tag

This action dumps the body of each message in raw bytes form to an individual file at the location specified.
The messages remain unchanged on the destination.
It also creates a corresponding XML file containing the message properties.

The files can be used to inspect the body of the messages in binary format, and can later be used to used to send a copy the messages to another destination.
See example 7.

If this tag is used within a JMXConnection tag, be aware that not all message properties can be read from the message.
This means that if the files are used to send a copy of the message to a queue, these message properties will be missing.

The files created by this action have the following filename structure:
00000000.SI_SYSTEM_MESSAGE_ID.extension

Full list of attributes

path
 Required
 String
 The path in which the output files should be created.
dumpProperties
 Optional
 true / false
 Whether to create .props.xml file for each message, containing an XML representation of the message properties. The default is true.

PrintAction action tag

This action can be used within any connection type, and prints the text contained within the body of the tag to the output location of the tool.
Message properties can be inserted using '%' characters around the name.

See example 11.

This tag has no attributes or children.

Example PrintAction tag

<PrintAction>Message %JMSMessageID% is %color%</PrintAction>

SetPropertyAction action tag

This action can only be used within rules that are inside a SIBConnection or Folder tag (it cannot be used within a JMXConnection tag).
It sets a property on in-memory copy of the message held by the tool.
If a subsequent MoveAction or CopyAction tag is used within the rule (or a subsequent rule), the new message sent to the destination includes the modified property.
When used on its own, this action has no affect on the message on the destination.

See example 6.

Full list of attributes

name
 Required String
 The name of the message property to set.
value
 Required
 String
 The value to set. An empty value results in the property being set to null.
Existing message properties can be inserted into the value using '%' characters around the name.

IncrementPropertyAction action tag

This action can only be used within rules that are inside a SIBConnection or Folder tag (it cannot be used within a JMXConnection tag).
It increments a numeric property on in-memory copy of the message held by the tool.
If a subsequent MoveAction or CopyAction tag is used within the rule (or a subsequent rule), the new message sent to the destination includes the modified property.
When used on its own, this action has no affect on the message on the destination.

If the property does not have an existing value, the action sets the value to 1.
If the property has an existing value which cannot be parsed as an integer, the action fails.

See example 11.

Full list of attributes

name
 Required String
 The name of the message property to set.

EmailAction action tag

This action uses a JavaMail session to send an e-mail containing a user-defined block of output for each message which matches the rule.
One e-mail is sent per run, if one or more messages match the rule.

If the tool is scheduled to run unattended, this can be used to send an e-mail to an administrator if an unexpected condition is found.
See example 11.

The body of the tag contains the block of text that is appended to the e-mail each time a message matches the rule (including any newline characters).
Message properties can be inserted using '%' characters around the name.

Example EmailAction tag

<EmailAction
  mailSession="MyMailSession"
  address="user1@mydomain.com"
  from="NOREPLY@mydomain.com"
  subject="Messages found on queue"
  maxMsgsPerMail="50"
>%JMSMessageID% (CorrelId %JMSCorrelationID%) sent at %JMSTimestamp%</EmailAction>

Example e-mail sent by the tool with the above tag:
Date: Tue, 23 Sep 2008 18:04:38 +0100
From: NOREPLY@mydomain.com
Sender: NOREPLY@mydomain.com
Reply-To: NOREPLY@mydomain.com
To: user1@mydomain.com
Subject: Messages found on queue
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

ID:ddbef8712a23487be470655f110a134f0000000000000004 (CorrelId null) sent at 1222189381250 (23 September 2008 17:03:01 GMT)
ID:ddbef8712a23487be470655f110a134f0000000000000002 (CorrelId null) sent at 1222189381234 (23 September 2008 17:03:01 GMT)
ID:ddbef8712a23487be470655f110a134f0000000000000003 (CorrelId null) sent at 1222189381234 (23 September 2008 17:03:01 GMT)
ID:ddbef8712a23487be470655f110a134f0000000000000001 (CorrelId null) sent at 1222189381218 (23 September 2008 17:03:01 GMT)
ID:ddbef8712a23487be470655f110a134f0000000000000005 (CorrelId null) sent at 1222189381265 (23 September 2008 17:03:01 GMT)
5 messages matched rule (output suppressed for 0 messages)

Full list of attributes

mailSession
 Required String
 The JNDI name of a JavaMail session that has been configured in WebSphere Application Server.
address
 Required
 String
 A comma or semi-colon separated list of e-mail addresses to send the e-mail to.
from
 Required
 String
 The address to place in the sender and reply-to fields of the e-mail.
subject
 Required
 String
 The subject for the e-mail.
maxMsgsPerMail
 Required
 Integer
 The maximum number of messages for which the body of the tag should be appended to the e-mail.
A summary line is included at the bottom of the e-mail to show the total number of messages which matched the rule.

Configuration file examples

This section gives example configuration files that can be used as a starting point for performing tasks with the tool.

Please refer back to the Running the tool and Connection tags sections for important information on how to run the tool, and specify connection information for the bus.

Example 1: Print all available messages on a queue

This example demonstrates how to use the tool to browse a queue point, using a messaging connection to a bus.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes
       required in a client environment (or when running in
       a server without the SIB Service enabled) -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue name="SOURCE_DESTINATION">
      <Rule>
        <MatchAnyMessage/>
        <DumpAction/>
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 2: Print all messages on a queue (including unavailable messages)

This example demonstrates how to use the tool to browse the messages on all queue points for a queue, using an administrative JMX connection to the deployment manager of the cell.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See JMXConnection section for other connection attributes -->
  <JMXConnection
    bus="SOURCE_BUS"
    connectorType="RMI"
    connectorHost="dmgr.mydomain.com"
    connectorPort="9809">
    <Queue name="SOURCE_DESTINATION">
      <Rule>
        <MatchAnyMessage/>
        <DumpAction/>
      </Rule>
    </Queue>
  </JMXConnection>
</SIBDestHandler>

Example 3: Print messages on subscriptions within a topic space

This example demonstrates how to use the tool to browse the messages on all active (or durable) subscriptions using an administrative JMX connection to the deployment manager of the cell.
Subscriptions on all publications points for the topic space will be read.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See JMXConnection section for other connection attributes -->
  <JMXConnection
    bus="SOURCE_BUS"
    connectorType="RMI"
    connectorHost="dmgr.mydomain.com"
    connectorPort="9809">
    <Subscription
      topicSpace="Default.Topic.Space"
      id="*"> <!-- To browse an individual subscription use id="clientID##subName" -->
      <Rule>
        <MatchAnyMessage/>
        <DumpAction/>
      </Rule>
    </Subscription>
  </JMXConnection>
</SIBDestHandler>

Example 4: Print the first 10 'red' messages on a queue

This example demonstrates a simple rule that selects a set of messages based on a user property called 'color', as well as limiting the number of messages output by the tool.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes
       required in a client environment (or when running in
       a server without the SIB Service enabled) -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue name="SOURCE_DESTINATION">
      <Rule>
        <MatchMessageProperty name="color">
          <StringCompare operation="equals" matchString="red"/>
        </MatchMessageProperty>
         <DumpAction maximumMessages="10" />
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 5: Resubmit messages from an exception destination

This example demonstrates how to resubmit all messages on an exception destination back to the individual exception problem destinations.
Note that the messages are placed at the tail of the exception problem destination queue, and may be interleaved with new messages arriving on the queue from other producers.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes
       required in a client environment (or when running in
       a server without the SIB Service enabled) -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue name="EXCEPTION_DESTINATION">
      <Rule>
        <MatchAnyMessage />
        <ResubmitAction/>
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 6: Select a single message using an SQL92 selector and move it to another queue

This example demonstrates a how to use SQL92 selection within the messaging engine to filter the messages read by the tool - in this case selecting an individual message.
It also demonstrates how a message property can be altered on the moved message. Here the original system message identifier is saved for future reference.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes
       required in a client environment (or when running in
       a server without the SIB Service enabled) -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue
      name="SOURCE_DESTINATION"
      selector="SI_SystemMessageID in ('D36A04A3DF0580E7_32501597')">
      <Rule>
        <MatchAnyMessage/>
        <SetPropertyAction name="OriginalSystemMessageID" value="%SI_SystemMessageID"/>
        <MoveAction targetDestination="TARGET_DESTINATION"/>
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 7: Dump messages to files

This example demonstrates how to dump the messages on a queue point into individual files.
Note that the body of JMS Map and Stream messages is summarized, and cannot be used to restore the message back to a queue.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes
       required in a client environment (or when running in
       a server without the SIB Service enabled) -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue name="SOURCE_DESTINATION">
      <Rule>
        <MatchAnyMessage/>
        <RawDumpAction path="c:\my\output\path"/>
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 8: Restore messages from files

This example demonstrates how to restore JMS generic/bytes/text/object messages, previously dumped to files using a RawDumpAction, to a queue.
Note that the copy of the message will have a new JMS Message ID, JMS Timestamp and other system generated properties.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <FileSystem>
    <Folder path="c:\my\output\path">
      <Rule>
        <MatchAnyMessage/>
        <CopyAction
          targetDestination="TARGET_DESTINATION">        
          <!-- See SIBConnection section for other connection attributes
               (that can be added to a CopyAction tag) and are
               required in a client environment. -->
          <SIBTargetConnection bus="TARGET_BUS" />
        </CopyAction>
       </Rule>
    </Folder>
  </FileSystem>
</SIBDestHandler>

Example 9: Print messages that match a number of nested criteria

This example demonstrates how to perform selection of messages based on a combination of different match criteria.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue name="SOURCE_QUEUE">
       <Rule>
        <And>
          <!-- The correlation id is not null  -->
          <MatchMessageProperty name="JMSCorrelationID">
            <ValueNotNull />
          </MatchMessageProperty>
           <!-- ... and the exception reason is null  -->
          <MatchMessageProperty name="JMS_IBM_ExceptionReason">
            <ValueIsNull />
          </MatchMessageProperty>
          <!-- ... and the format contains 'object' (case insensitive) -->
          <MatchMessageProperty name="SI_Format">
            <StringCompare operation="contains" matchString="object" ignoreCase="true" />
          </MatchMessageProperty>
          <!-- and either ... -->
           <Or>
            <!-- The user property 'orderid' starts with a, b, c, A, B or C -->
             <MatchMessageProperty name="orderid">
              <RegexCompare regex="[abc].*" ignoreCase="true"/>
            </MatchMessageProperty>
             <!-- ... or the user property 'productcode' ends with a number -->
             <MatchMessageProperty name="productcode">
              <RegexCompare regex=".*\d" />
            </MatchMessageProperty>
           </Or>
        </And>
        <!-- Then print out the headers of the message, and up to 100bytes of the body -->
         <DumpAction maximumLength="100"/>
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 10: Moving messages between partitioned queue points

This example shows how the tool can be used to move messages from one queue point for a partitioned destination to another.
The connection used to consume the message and the connection used to send the message are coordinated using the transaction manager of the application server.
This means the tool must be deployed as a web or EJB application to use this example.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes.
       Note that we are connecting to an individual messaging engine in the cluster. -->
   <SIBConnection
     bus="MYBUS"
     targetType="ME"
     target="MyCluster.000-MYBUS"
     targetSignificance="Required">
    <Queue name="MYQUEUE">
       <Rule>
        <MatchAnyMessage />
         <MoveAction targetDestination="MYQUEUE">
          <!-- Specify a target connection to point at another messaging engine in the cluster -->
          <SIBTargetConnection
            bus="MYBUS"
            targetType="ME"
            target="MyCluster.001-MYBUS"
            targetSignificance="Required" />
        </MoveAction>
       </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Example 11: Example exception destination handling rules

This example demonstrates one type of processing you may wish to perform on an exception destination, as well as showing how multiple rules can be combined.
The example looks for messages on an exception destination which have failed because an MDB has rolled them back to the queue point more times than the maximum failed deliveries.
This could be because of a temporary issue, such as a database being restarted, or it could be because these message can never be processed (due to bad data within the message).

The example takes the following approach, to automatically retry messages to cope with temporary failures as well as attempting to remove messages which can never be processed:
Each time the tool runs (every hour for example) messages which have failed are resubmitted back to the exception problem destination.
Messages are updated with a property to track how many times the message has been resubmitted.
If a message is resubmitted 5 times, it is assumed that there is a problem with the message itself, and it is moved to a permanent failure queue.
An administrator is notified with an e-mail when messages are moved to the permanent failure queue, as manual action will be required to allow them to be processed.

This example is intented to be run as a scheduled task.
Note that the resubmitted messages would be reprocessed out of order from new messages arriving on the queue.

<?xml version="1.0" encoding="UTF-8"?>
<SIBDestHandler>
  <!-- See SIBConnection section for other connection attributes
       required in a client environment (or when running in
       a server without the SIB Service enabled) -->
  <SIBConnection bus="SOURCE_BUS">
    <Queue
      name="EXCEPTION_DESTINATION"
      continueAfterFailure="true"> <!-- Continue to next rule if we fail -->
      <!-- Rule 1 to move messages that appear will never work -->
      <Rule>
        <Or>
          <!-- If there is no exception problem destination set -->
          <MatchMessageProperty name="JMS_IBM_ExceptionProblemDestination">
            <ValueIsNull />
          </MatchMessageProperty>
          <!-- Or we have reached the maximum number of resubmits for
               a message which could not be processed (CWSIK0035E). -->
          <And>
             <MatchMessageProperty name="ResubmitCount">
               <DecimalCompare operation="greaterThanOrEqual" matchValue="5" />
            </MatchMessageProperty>
            <MatchMessageProperty name="JMS_IBM_ExceptionReason">
              <DecimalCompare operation="equals" matchValue="35" />
            </MatchMessageProperty>
          </And>
        </Or>
        <!-- Move the message to a permanent failure queue -->
        <MoveAction targetDestination="PERMANENT_FAILURE_QUEUE" />
        <!-- Send an e-mail to an administrator, as these messages need
             manual intervention (list all messages that are moved in e-mail).
             As this action is after the move action, it will only occur
             if the move is successful, and a failure to send the e-mail
             would not stop the move from completing. -->
        <EmailAction
          mailSession="mail/MyMailSession"
          address="user@mydomain.com"
          from="NOREPLY@mydomain.com"
          subject="Messages moved to permanent failure queue"
          maxMsgsPerMail="0"
        >%JMSMessageID% (CorrelId %JMSCorrelationID%) sent at %JMSTimestamp%</EmailAction>
      </Rule>
      <!-- Rule 2 resubmit messages in case a temporary system outage has been resolved -->
      <Rule>
        <!-- This rule is for messages which failed because they met the
              max redelivery threshold of the queue (CWSIK0035E). -->
        <MatchMessageProperty name="JMS_IBM_ExceptionReason">
          <DecimalCompare operation="equals" matchValue="35" />
        </MatchMessageProperty>
        <!-- Increment a property to keep track of the number of resubmits -->
        <IncrementPropertyAction name="ResubmitCount"/>
        <!-- Print a line for this message in the log -->
        <PrintAction>ResubmitCount=%ResubmitCount% for message %SI_SystemMessageID%. Arrival timestamp: %MEArrivalTimestamp%</PrintAction>
        <!-- Try and re-submit the message.
             Note that if Rule 1 had already removed the message from the
             queue, this action would not occur, as the tool knows the
             message is no longer available. -->
         <ResubmitAction />
      </Rule>
    </Queue>
  </SIBConnection>
</SIBDestHandler>

Troubleshooting