Service Integration Bus Destination Handler

© Copyright IBM Corp. 2008, 2009 All Rights Reserved.

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

Index

Overview

This is a tool for the default messaging provider for WebSphere Application Server V6.0, V6.1 and V7.0.
The tool provides the ability to perform various actions on messages in a Service Integration Bus without writing any custom code.
These actions can be run once to perform an individual task, or the tool can be deployed as a WebSphere Application Server scheduler task to regularly check the contents of an exception destination and provide appropriate handling of messages based on the set of rules configured.

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:
The tool can be run in any of the following environments to suit the task being performed:
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
    This requires a WebSphere Application Server client (or server) installation on your local machine.
    In a secure environment, you will also 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 ear and XML files:
    UNIX: PROFILE_ROOT/bin/launchClient.sh sib.desthandler.appclient.ear -CCBootstrapHost=localhost -CCBootstrapPort=9809
    Windows: PROFILE_ROOT\bin\launchClient.bat sib.desthandler.appclient.ear -CCBootstrapHost=localhost -CCBootstrapPort=9809
    Substitute the following text:
    localhost - the hostname of an application server, or deployment manager, running in the target environment
    9809 - the port of the BOOTSTRAP_ADDRESS endpoint of the chosen server
  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 to the same directory:
    examples/viewQueuePoint_secure.xml if bus security is enabled
    examples/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:
    UNIX: PROFILE_ROOT/bin/launchClient.sh sib.desthandler.appclient.ear -CCBootstrapPort=9809 viewQueuePoint.xml
    Windows: PROFILE_ROOT\bin\launchClient.bat sib.desthandler.appclient.ear -CCBootstrapPort=9809 viewQueuePoint.xml
    Substitute the following text:
    PROFILE_ROOT - The root directory of the profile for the node
    9809 - The port of the BOOTSTRAP_ADDRESS endpoint of an application server running on the node
    viewQueuePoint.xml - The XML configuration file edited above
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 on a machine with a WebSphere Application Server client or server installation, without installing any applications into an application server or cluster.

Binary to use: sib.desthandler.appclient.ear

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

The inserts are as follows:

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.
Please also note APAR PK47134 for WebSphere Application Server V6.1.

Running the tool as a thin application client

This method requires a WebSphere Application Server client or server installation, but does not establish a bootstrap connection to an application server to set up the client container.
If security is enabled and the tool will only create messaging connections to the bus (rather than administrative JMX connections), this avoids needing to perform two sets of security configuration.

Binary to use: sib.desthandler.jar

Review the Running Thin application client code section of the information center for instructions to set up the thin application client environment.
The sib.desthandler.jar archive must be included in the classpath on the command line.
The fully qualified class name to run is com.ibm.ws.sib.desthandler.SIBDestHandlerCmdLine
The single 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.
Please also note APAR PK47134 for WebSphere Application Server V6.1.

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.

Running the tool as a J2SE application

Use this approach if you are running the tool on a machine without a WebSphere Application Server client or server installation.
This approach can only be used for messaging connections (SIBConnection tags). JMX connections cannot be established with this approach.


Binary to use: sib.desthandler.jar

Ensure that the appropriate IBM Client for JMS on J2SE with IBM WebSphere Application Server libraries for your Java Runtime Environment (JRE) are included on the classpath.
The sib.desthandler.jar archive must be included in the classpath on the command line.
The fully qualified class name to run is com.ibm.ws.sib.desthandler.SIBDestHandlerCmdLine The single application parameter is the configuration file for the tool.

Example:
java -classpath sibc.jms.jar:sibc.jndi.jar:SIBusDestinationHandler.jar com.ibm.ws.sib.desthandler.SIBDestHandlerCmdLine CONFIG_FILE

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

Considerations for secure connections

Please review the readme for the IBM Client for JMS on J2SE with IBM WebSphere Application Server for details of how the JSSE provider for your JRE can be configured to provide SSL security on messaging connections.

Running the tool as a web application

Use this approach if you use the tool regularly, as it simplifies the amount of connection information which needs to be provided in the configuration file.

Binary to use: sib.desthandler.web.war

Deploy the application to a deployment target in your cell, specifying a context root.
Review the Installing J2EE application files section of the information center for detailed deployment instructions.

Communication with a messaging engine will be most efficient if the application is deployed to an application server or cluster that is a member of the bus.

If deploying to an application server or cluster that is not a member of the bus, you are recommend to enable the SIB service on the application servers.
See the SIB service settings section of the information center for detailed instructions.

A single web module will be installed called SIBDestHandlerWeb.
This contains one Servlet called SIBDestHandlerServlet and a HTML file called located in the top-level of the context root.

The destination handler can then be run either using the input box on the HTML page to input a configuration file, or by using invoking the Servlet directly.

The SIBDestHandlerServlet Servlet has the following parameters:
Either GET or POST can be used to invoke the Servlet.

Considerations for secure connections

The security of network connections to the HTML page and servlet are based on the transport security for the web container of the application server.

If the application can run in a server without a messaging engine for the bus, you may need to consider security of messaging connections created by the tool.
In most cases no special configuration will be required, as long as the SIB service is enabled and a suitable targetTransportChain is specified in the SIBConnection tag.

If a special SSL configuration is needed for messaging connections created by the tool, you will need to configure how the server should establish Service Integration Bus client network connections.
In WebSphere Application Server V6.0 the SSL configuration for messaging connections is described in the Secure transport considerations section of the information center.
In WebSphere Application Server V6.1 and V7.0 the SSL configuration can be customized using the "Bus client" outbound endpoint for the server. See the Manage endpoint security configurations section of the information center for more information.

Installing the tool as a WebSphere Application Server scheduler task

Use this approach if you are configuring the tool to run at regular intervals against destinations in a bus, or if you wish to invoke the tool with a preset configuration via an EJB interface.

Binary to use: sib.desthandler.taskejb.ear

Deploy the application to a deployment target in your cell.
Review the Installing J2EE application files section of the information center for detailed deployment instructions.

Communication with the messaging engine will be most efficient if the application is deployed to the application server or cluster that hosts the messaging engine that owns the destinations.

If deploying to an application server or cluster that is not a member of the bus, you are recommend to enable the SIB service on the application servers where the application will be hosted to simplify configuration.
See the SIB service settings section of the information center for detailed instructions.

The EJB implements the com.ibm.websphere.scheduler.TaskHandler interface, which allows it to be registered as a WebSphere Application Server scheduler task.
When the process method on the EJB is invoked, the tool runs once against a predefined configuration file and logs output to a predefined location.

A null TaskStatus object can safely be passed to the tool if it is invoked directly by an application using the TaskHandler interface.

A property file is used to specify where the configuration file is located, and how the output from the tool is logged.
Create a file called sib.desthandler.properties in the PROFILE_ROOT/properties directory of the profile on all nodes where the tool can run.
The deployment descriptor of the EJB contains an environment entry called sib.desthandler.property.file which can be used to change the name of the property file looked for by the tool.

An example property file is as follows:
# Change this property to the location of the configuration file for the tool
# Note that Windows paths must use '/' or '\\' path separators
configurationFile=c:\\sibdesthandler\\sib.desthandler.config.xml

# Change this property to the directory where log files from the tool should be written
# Note that Windows paths must use '/' or '\\' path separators
logDirectory=c:\\sibdesthandler\\log

# Uncomment and change this property to
customise the prefix for log files written by the tool
#logPrefix=sib.desthandler

# Uncomment and change this property to
customise the size of each log file in KB
#logFileSize=512

#
Uncomment and change this property to customise the number of log files
#logFileCount=3

# Uncomment and change this property to customise the timestamp prefix printed on each line of the log
# The syntax is described in the Java 2 Platform javadoc for the java.text.SimpleDateFormat class
#logDateFormat=
[yyyy.MM.dd kk:mm:ss:SSS z]

The following example wsadmin scripts are provided in the installation package to schedule, list and cancel Service Integration Bus destination handler tasks:
Review the Developing and scheduling tasks section of the information center for detailed instructions on scheduling an EJB to run as a scheduled task.

Considerations for secure connections

If the application can run in a server without a messaging engine for the bus, you may need to consider security of messaging connections created by the tool.
In most cases no special configuration will be required, as long as the SIB service is enabled and a suitable targetTransportChain is specified in the SIBConnection tag.

If a special SSL configuration is needed for messaging connections create by the tool, you will need to configure how the server should establish Service Integration Bus client network connections.
In WebSphere Application Server V6.0 the SSL configuration for messaging connections is described in the Secure transport considerations section of the information center.
In WebSphere Application Server V6.1 and V7.0 the SSL configuration can be customized using the "Bus client" outbound endpoint for the server. See the Manage endpoint security configurations section of the information center for more information. 

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

ConnectorException using JMXConnection with a J2SE client

If you are running the tool as a J2SE application and you see this error:

Exception in thread "main" java.lang.NoClassDefFoundError: com/ibm/websphere/management/exception/ConnectorException
at com.ibm.ws.sib.desthandler.SIBDestHandler.init(SIBDestHandler.java:178)
at com.ibm.ws.sib.desthandler.SIBDestHandler.init(SIBDestHandler.java:75)
at com.ibm.ws.sib.desthandler.SIBDestHandler.init(SIBDestHandler.java:67)
at com.ibm.ws.sib.desthandler.SIBDestHandlerCmdLine.main(SIBDestHandlerCmdLine.java:65)

This is because JMXConnection tags cannot be used in a J2SE environment.

Solution:
Run the tool as an application client.

ServiceUnavailableException followed by CWSIJ0032E error

If you are running the tool as an application client, and you see this error:

[03/10/08 10:33:21:437 BST] 0000000a E UOW=null source=com.ibm.ws.sib.utils.ras.SibMessage org=IBM prod=WebSphere component=Application Server thread=[P=399154:O=0:CT] [:] CWSIJ0032E: An internal error occurred. An object of class com.ibm.ws.buffermgmt.impl.WsByteBufferPoolManagerImpl cannot be created because of exception: javax.naming.ServiceUnavailableException: A communication failure occurred while attempting to obtain an initial context with the provider URL: "corbaloc:iiop:hostname:2809". Make sure that any bootstrap address information in the URL is correct and that the target name server is running. A bootstrap address with no port specification defaults to port 2809. Possible causes other than an incorrect bootstrap address or unavailable name server include the network environment and workstation network configuration.

This is followed by this error:

ERROR for connection [SIBConnection[connProps={providerEndpoints=hostname:7276:BootstrapBasicMessaging, targetTransportChain=InboundBasicMessaging,busName=bus1},username=]]: com.ibm.ws.sib.desthandler.SIBDestHandlerException: Failed to create connection ([connProps={providerEndpoints=hostname:7276:BootstrapBasicMessaging, targetTransportChain=InboundBasicMessaging, busName=bus1},username=])
at com.ibm.ws.sib.desthandler.impl.CoreSPIConnection.establishConnection (CoreSPIConnection.java:80)

This means the application client container could not be created, resulting in connections failing because container managed infrastructure is not available.
 
Solution:
Use the -CCBootstrapHost and -CCBootstrapPort parameters of the launchClient command to change how the application client connects to an application server to establish the client container.
Alternatively run the tool as a thin client.