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
Quick start guide

Using the graphical user interface
Using the command line

Running the tool

as an application client
as a thin client
as a J2SE client
as a web application
as a scheduled task

Configuration file

Masking passwords
SIBDestHandler tag
Connection tags

SIBConneciton tag
JMXConnection tag

FileSystem tag

Destination tags

Queue tag
Subscription tag
RemoteQueuePoint tag
RemotePublicationPoint tag

Folder tag

Rule tag
Match criteria tags

MatchAnyMessage tag
MatchMessageProperty tag
MatchMessageText tag
MatchXPathExpression tag
And tag
Or tag

Comparison tags

ValueIsNull tag
ValueNotNull tag
StringCompare tag
RegexCompare tag
DateCompare tag
DecimalCompare tag

Action tags

MoveAction tag
ResubmitAction tag
DeleteAction tag
CopyAction tag
DumpAction tag
RawDumpAction tag
PrintAction tag
SetPropertyAction tag
IncrementPropertyAction tag
EmailAction tag

Configuration file examples

Example 1: Print all available messages on a queue
Example 2: Print all messages on a queue (including unavailable messages)
Example 3: Print messages on subscriptions within a topic space
Example 4: Print the first 10 'red' messages on a queue
Example 5: Resubmit messages from an exception destination
Example 6: Select a single message using an SQL92 selector and move it to another queue
Example 7: Dump messages to files
Example 8: Restore messages from files
Example 9: Print messages that match a number of nested criteria
Example 10: Move messages between partitioned queue points
Example 11: Example exception destination handling rules

Troubleshooting

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:

Printing a textual representation of the properties and body of messages

searching the contents of a queue for an individual message or group of messages
examining the contents of a message which cannot be processed by an application
gathering a snapshot of the contents of a queue to send to an application developer for investigation

Moving messages to a different queue point

handling a case where a message has been sent to the wrong queue point
moving messages from a queue point where no application is available to consume them
moving messages to a different bus
moving messages that can never be processed from an exception destination to a permanent failure destination

Copying messages to a different destination

copying messages from a production bus to a test bus for investigation

Resubmitting messages from an exception destination back to the exception problem destination

resubmitting messages after restarting a database or other system required to process them

Dumping a copy of the body and properties of messages to files

examining the body of a message using a tool that requires the binary contents
creating a copy of a set of messages sent by an application to use multiple times in testing

Restoring messages from a file to a destination

loading a set of messages onto a destination as the input for a test

Sending an e-mail to an administrator containing properties from messages

configuring an exception destination handler to inform an administrator when certain conditions occur

These actions can be performed for all messages on a destination, or a subset of messages on destination selected using:

An SQL92 selector, evaluated in the messaging engine
Comparison against any of the following items extracted from a message

Message properties
The text body of a message
The result of an XPath expression evaluated against the XML body of a message

The following comparison methods are available:

String comparison

Matching against a regular expression, anywhere in the selected item

Integer comparison

Date comparison, including age

Null/non-null comparison

Nested AND/OR combinations of the above

The tool can connect to the default messaging provider using the following interfaces:

As a messaging application

Only messages available to applications on queue points can be read
Messages are read from an individual queue point on a messaging engine in the bus

Using an administrative Java Management Extensions (JMX) connection

All messages in a bus can be read using this interface, including those contained in unresolved transactions or on subscriptions

For queues, messages are read from all queue points in the bus for which a management bean is accessible
For subscriptions, messages are read from matching subscriptions on all publication points in the bus for which a management bean is available

The tool can be run in any of the following environments to suit the task being performed:

Application Client for WebSphere Application Server V6.0, V6.1 or V7.0
Thin application client for WebSphere Application Server V6.0, V6.1 or V7.0
J2SE application client using the IBM Client for JMS on J2SE with IBM WebSphere Application Server

Administrative (JMX) connections are unavailable in this environment

Web application deployed to WebSphere Application Server V6.0, V6.1 or V7.0
Regularly scheduled Enterprise JavaBean (EJB) task deployed to WebSphere Application Server V6.0, V6.1 or V7.0

A graphical user interface is provided to aid with the following tasks:

Performing individual actions in an interactive way, without needing to write a configuration file. For example:

Viewing the contents of a queue, and saving the output to a file
Moving messages from one destination to another, with a confirmation dialog for each message

Sending messages into the bus to test rules
Building and testing a configuration file for running the tool on the command line, or as a scheduled task
Exploring the runtime environment to determine connection and destination information

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:

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

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
The following window should be displayed.
Click the "Configure..." button in the "Runtime discovery" section.
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.
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.
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.
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.
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.

Choose a node with a running application server that is a server or cluster member of the bus.
Transfer (using binary FTP or other transfer method) file sib.desthandler.appclient.ear to a directory on the chosen node
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
Edit the XML configuration file in a text editor and replace the following text:
- MYBUS - The name of the bus
- MYDESTINATION - The name of the destination
For viewQueuePoint.xml only:
- 7276 - The port of the SIB_ENDPOINT_ADDRESS endpoint of an application server running on the node
For viewQueuePoint_secure.xml only:
- 7286 - The port of the SIB_SECURE_ENDPOINT_ADDRESS endpoint of an application server running on the node
- myusername - The username to use to connect to the bus
- mypassword - The password to use to connect to the bus
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:

Windows:
PROFILE_ROOT\bin\launchClient.bat sib.desthandler.appclient.ear -CCBootstrapHost=SERVER_HOST_NAME -CCBootstrapPort=SERVER_BOOTSTRAP_PORT CONFIG_FILE
Linux, UNIX and z/OS:
PROFILE_ROOT\bin\launchClient.bat sib.desthandler.appclient.ear -CCBootstrapHost=SERVER_HOST_NAME -CCBootstrapPort=SERVER_BOOTSTRAP_PORT CONFIG_FILE

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

The inserts are as follows:

SERVER_HOST_NAME
The host name or IP address of any application server in the cell. This is used to setup the client container.
SERVER_BOOTSTRAP_PORT
The port associated with the BOOTSTRAP_ADDRESS endpoint of the server specified in SERVER_HOST_NAME
CONFIG_FILE
The configuration file for the tool.

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:

xmlconfig - required
The XML configuration, which is parsed in UTF-8 character set.
username and password - optional
The default username and password, which can be overridden in the XML configuration
printconfig - optional
If set to "true" the configuration is printed as well as the output from the tool

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:

samples/create_task.jacl
Example script to schedule the Service Integration Bus destination handler to run on a schedule
Edit the file to specify the server name where the EJB is deployed, the JNDI name of the scheduler and how often the tool should run.
samples/list_tasks.jacl
Example script to list and cancel Service Integration Bus destination handler tasks currently scheduled

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

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

Example SIBConnection tag for connecting as a client application

Example SIBConnection tag for connecting securely as a client application

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)

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

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

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


<MatchXPathExpression expression="RootTag/InnerTag/attribute::myattr = 'myvalue'">
<StringCompare operation="equals" matchString="true"/>
</MatchXPathExpression>


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

Without a SIBTargetConnection tag - see example 6.
Any of the methods described in the running the tool section can be used.
The same connection is used to consume the message from the source queue point and to send it to the target queue point.
A transaction is used to ensure that both the consume from the source queue and the delivery to the target queue are performed, or neither are performed.
With a SIBTargetConection tag - see example 10.
The application must be run within an application server as an EJB or web application.
Two separate connections are used to consume and send the message.
This allows the message to be moved between buses, or between individual queue points for a partitioned destination.
A global transaction is used to coordinate the two connections, using the WebSphere Application Server transaction manager.

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

00000000 is the index of the message as read by the tool during in individual run, starting with 0.
This prefix allows the tool to restore messages to a destination in the same order they were read from a queue.
SI_SYSTEM_MESSAGE_ID is the system message id of the message read by the tool.
extension is one of the following:

props.xml
An XML dump of the properties for the message body with the corresponding name before the extension.
emptymsg
An empty file representing the empty body of a generic JMS Message.
bytesmsg
The binary body of a JMS BytesMessage.
textmsg
The UTF-8 encoded body of a JMS TextMessage.
mapmsg
A UTF-8 encoded summary of the body of a JMS MapMessage. This cannot be used to copy the message from the filesystem to a destination.
mapmsg
A UTF-8 encoded summary of the body of a JMS StreamMessage. This cannot be used to copy the message from the filesystem to a destination.
objectmsg
The binary body of a JMS ObjectMessage containing a single serialized Java object.
sdomsg
The binary body of a Service Data Objects datagraph message.
unknownmsg
An empty file representing the body of a message type that is not understood by the tool.

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.

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>

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

<JMXConnection
    bus="SOURCE_BUS"
    connectorType="RMI"
    connectorHost="dmgr.mydomain.com"
    connectorPort="9809">
    <Subscription
      topicSpace="Default.Topic.Space"
      id="*"> 
      <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.

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.

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.

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.

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

<SIBConnection bus="SOURCE_BUS">
    <Queue name="SOURCE_QUEUE">
      <Rule>
        <And>
          
          <MatchMessageProperty name="JMSCorrelationID">
        <ValueNotNull />
          </MatchMessageProperty>
          
          <MatchMessageProperty name="JMS_IBM_ExceptionReason">
        <ValueIsNull />
          </MatchMessageProperty>
          
          <MatchMessageProperty name="SI_Format">
        <StringCompare operation="contains" matchString="object" ignoreCase="true" />
          </MatchMessageProperty>
          
          <Or>
            
            <MatchMessageProperty name="orderid">
            <RegexCompare regex="[abc].*" ignoreCase="true"/>
          </MatchMessageProperty>
            
            <MatchMessageProperty name="productcode">
            <RegexCompare regex=".*\d" />
          </MatchMessageProperty>
          </Or>
        </And>
        
        <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>

<SIBConnection
     bus="MYBUS"
     targetType="ME"
     target="MyCluster.000-MYBUS"
     targetSignificance="Required">
    <Queue name="MYQUEUE">
      <Rule>
        <MatchAnyMessage />
        <MoveAction targetDestination="MYQUEUE">
          
          <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>

<SIBConnection bus="SOURCE_BUS">
    <Queue
      name="EXCEPTION_DESTINATION"
      continueAfterFailure="true"> 
      
      <Rule>
        <Or>
          
          <MatchMessageProperty name="JMS_IBM_ExceptionProblemDestination">
            <ValueIsNull />
          </MatchMessageProperty>
          
          <And>
      <MatchMessageProperty name="ResubmitCount">
       <DecimalCompare operation="greaterThanOrEqual" matchValue="5" />
            </MatchMessageProperty>
            <MatchMessageProperty name="JMS_IBM_ExceptionReason">
              <DecimalCompare operation="equals" matchValue="35" />
            </MatchMessageProperty>
          </And>
        </Or>
        
        <MoveAction targetDestination="PERMANENT_FAILURE_QUEUE" />
        
        <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>
        
      <MatchMessageProperty name="JMS_IBM_ExceptionReason">
          <DecimalCompare operation="equals" matchValue="35" />
      </MatchMessageProperty>
        
        <IncrementPropertyAction name="ResubmitCount"/>
        
        <PrintAction>ResubmitCount=%ResubmitCount% for message %SI_SystemMessageID%. Arrival timestamp: %MEArrivalTimestamp%</PrintAction>
        
         <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.