webspheremq bridge

8/6/2019 Webspheremq Bridge

1/70

SonicMQV5 Bridge for WebSphere MQ Users Guide


2/70

SonicMQ V5 Bridge for WebSphere MQ Users Guide

Copyright 2003 Sonic Software Corporation. All rights reserved.

The Sonic Software products referred to in this document also are copyrighted, and all rights are reserved by Sonic

Software Corporation. This manual may not, in whole or in part, be copied, photocopied, translated, or reduced to

any electronic medium or machine-readable form without prior consent, in writing, from Sonic Software

Corporation.

The information in this manual is subject to change without notice, and Sonic Software Corporation assumes noresponsibility for any errors that may appear in this document. The references in this manual to specific platforms

supported are subject to change.

SonicMQ is a registered trademark of Sonic Software Corporation in the U.S. and other countries. Progress is a

registered trademark of Progress Software Corporation in the U.S. and other countries. Java and all Java-based

marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other

trademarks or service marks contained herein are the property of their respective owners.

June 2003


3/70

SonicMQ V5 Bridge for WebSphere MQ Users Guide 3

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

How the Bridge for WebSphere MQ Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Sending Data from a SonicMQ Domain to a WebSphere MQ Domain . . . . . . . . . . . . . . . . . . 11

Sending Data from a WebSphere MQ Domain to a SonicMQ Domain . . . . . . . . . . . . . . . . . . 13

Message Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Mapping Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Map and Stream Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Handling JMS Message Types in WebSphere MQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

TextMessage and XMLMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 2: Installing SonicMQ Bridge for WebSphere MQ . . . . . . . . . . 19Deployment Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

SonicMQ Broker and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

WebSphere MQ Server and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

The Bridge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20


4/70

Contents

4 SonicMQ V5 Bridge for WebSphere MQ Users Guide

Installation and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

SonicMQ Broker and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

WebSphere MQ Server and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Server Configuration for a QueueManager for the Samples . . . . . . . . . . . . . . . . . . . . . . 22

WebSphere MQ Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

SonicMQ Bridge for WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Bridge Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Sample Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Startup Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Chapter 3: Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27About the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Structure of the Sample Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

General Instructions for Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

Starting the SonicMQ message broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

Gathering Information from the SonicMQ message broker . . . . . . . . . . . . . . . . . . . . . .30

Starting the WebSphere MQ Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Setting Up the SonicMQ Bridge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Modifying the Configuration File for SonicMQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Modifying the Scripts for SonicMQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Modifying the Scripts for WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Review of the Set Up for Each Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Running the Talk Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Running the Order Inventory Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35Running the Chat Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Chapter 4: Configuring the Bridge for WebSphere MQ . . . . . . . . . . . . . . . 41Overview of the Bridge Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Specifying WebSphere MQ Bridge Configuration Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

Bridge Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44

Bridge Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Bridge Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Resource Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

Destinations for the Bridge from SonicMQ to WebSphere MQ . . . . . . . . . . . . . . . . . . . 48

Destinations for the Bridge from WebSphere MQ to SonicMQ . . . . . . . . . . . . . . . . . . . 52

Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Connection Factory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57


5/70


Contents

Validators and Mappers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Message Mapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Inbound Message Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Outbound Message Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Administering the Bridge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Managing Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Managing Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Security Using TCP/IP Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Security Using Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Managing Quality of Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Setting Parameters on WebSphere MQ Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Getting Messages from a WebSphere MQ Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Putting Messages on a WebSphere MQ Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Message Level Quality of Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

SonicMQ Messages Transforming to WebSphere MQ Messages . . . . . . . . . . . . . . . . . 66

WebSphere MQ Messages Transforming to SonicMQ Messages . . . . . . . . . . . . . . . . . 68

Connection Level Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70WebSphere MQ Side Transaction Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70


6/70

Contents



7/70


Preface

About This ManualSonicMQ is a fast, flexible, scalable e-business messaging server designed to simplify the

development and integration of todays highly distributed enterprise applications and

Internet-based business solutions. SonicMQ is a complete implementation of the JavaMessage Service specification Version 1.0.2b, an API for accessing enterprise messaging

systems from Java programs.

The SonicMQ Bridges integrate the SonicMQ e-business messaging server with a family

of SonicMQ Bridges to provide a comprehensive and transparent solution for integrating

your existing computing resources. This document introduces the concept of bridging

between the SonicMQ message broker and an IBM's WebSphere MQ queue manager.

This book consists of four chapters:

Chapter 1, Overview, provides an introduction to the SonicMQ Bridge for

WebSphere MQ and an explanation of how the Bridge for WebSphere MQ works.

Chapter 2, Installing SonicMQ Bridge for WebSphere MQ, tells how to install the

Bridge for WebSphere MQ and its associated components.

Chapter 3, Running the Samples,describes how to run the samples that come with

the Bridge for WebSphere MQ.

Chapter 4, Configuring the Bridge for WebSphere MQ, shows the techniques used

to configure and administer the Bridge for WebSphere MQ and how to manage

security and Quality of Service.


8/70

Preface


Worldwide Technical SupportSonic Softwares support staff maintains a wealth of information at

http://www.sonicsoftware.comto assist you with resolving any technical problems that

you encounter when installing or using the SonicMQ V5 Bridges.

From the Sonic Software home page, click on Developers Exchange to take advantage of

resources for developers such as forums, downloads, tips, white papers, and code

snippets.

When contacting Technical Support, please provide the following information: The release version number and serial number of the SonicMQ broker that you are

using. This information is listed on the license addendum; it is also at the top of the

SonicMQ Broker console window and might appear as follows:

SonicMQ Enterprise Edition [Serial Number 25677051]Release nnn Build Number nnn Protocol nnnCopyright (c) 2003 Sonic Software Corporation. All Rights Reserved.

The release version number and serial number of the SonicMQ V5 Bridges that you

are using. This information is in the product.properties file in the install directory.

(Additional build and version information is in _version.txt in the products JAR

file.)

The platform on which you are running the SonicMQ V5 Bridge, as well as any other

environment information you think might be relevant.

The Java Virtual Machine (JVM) you are using.

Your first and last name. Your company name.

Phone and fax numbers for contacting you.

Your e-mail address.
http://sonicsoftware.com/http://sonicsoftware.com/


9/70


Chapter 1 Overview

This chapter provides an introduction to the SonicMQ Bridge for WebSphere MQ in these

three sections:

Introduction

How the Bridge for WebSphere MQ Works Message Mapping

For general information on the SonicMQ Bridges, see the SonicMQ V5 Bridges Startup

Guide.

For information on SonicMQ, see the SonicMQ documentation, listed in the Preface of

the SonicMQ V5 Bridges Startup Guide.


10/70

Chapter 1: Overview


Introduction

Many implementers find it necessary to integrate their new messaging applications withlegacy systems based on IBM WebSphere MQ. The SonicMQ Bridge for

WebSphere MQ provides an easy-to-use solution to implement this difficult integration.

Once configured, the Bridge seamlessly routes message traffic between a JMS messaging

domain (SonicMQ) and a WebSphere MQ domain.

The SonicMQ Bridge for WebSphere MQ establishes connections with both SonicMQ

and WebSphere MQ and facilitates bidirectional messaging between the two messaging

servers. The SonicMQ Bridge for WebSphere MQ is completely transparent to client

applicationsyou do not have to change your SonicMQ or WebSphere MQ applications

to exchange messages between the two architectures.

The SonicMQ Bridge for WebSphere MQ communicates with:

SonicMQ message brokers as a standard SonicMQ client that can access topics and

established queues

WebSphere MQ queues through the WebSphere MQ Java client APIs

On the WebSphere MQ side of the Bridge, queued MQMessages are completely native.

The WebSphere MQ side of the Bridge uses the client and connector libraries without the

additional JMS libraries, eliminating the overhead of the WebSphere MQ JMS proxy

server in the WebSphere MQ domain. Intelligent message mapper techniques on the

Bridge make it possible to package all the JMS message typesText, XML, Bytes, Map,

Stream, and Objectinto WebSphere MQ types. WebSphere MQ applications can use the

same techniques when writing messages to create message layouts and identifiers thatwill transform MQMessages into JMS Map or Stream messages.

On the SonicMQ side of the Bridge, the SonicMQ client libraries enable all the features

of JMS messaging with low overhead. Messages that originate in WebSphere MQ are

evaluated on the Bridge to extract application identifiers and message layouts that enable

the message to be transformed into JMS message types that are not native to WebSphere

MQ and then sent to a queue or published to a topic.

The SonicMQ Bridge for WebSphere MQ provides administrative tools, security,

performance, and straightforward implementation to integrate WebSphere MQ messaging

with JMS messaging.

Note As stated by IBM, WebSphere MQ V5.3 now includes MQSeries classes for Java and

JMS. The use of the MA88 SupportPac that was required in MQSeries 5.2 and earlier is

not supported. The MA88 level of Java client can continue to be used with the MQ V5.3

server, but it is recommended that you use the V5.3 level of client classes.


11/70


How the Bridge for WebSphere MQ Works


The Overview section of the SonicMQ V5 Bridges Startup Guide describesthe generalSonicMQ Bridge architecture. The following sections provide an overview of how the

Bridge for WebSphere MQ transfers messages between the SonicMQ and WebSphere

MQ domains.

Sending Data from a SonicMQ Domain to a WebSphere MQ Domain

Figure 1 provides a graphic overview of how a native WebSphere MQ client can receiveSonicMQ messages.

Figure 1. Bridging a SonicMQ Message to a WebSphere MQ MQMessage

WebSphere

MQ

QueueManager

WebSphere

MQ

Channel

Connection

Bridge Descriptor

SonicMQ

Message

Broker

Resource Connector

Bridge Application

JMS

Physical

Connection

Bridge

Resource Connector

Destination

Role is CONSUMER

Destination

Role is PRODUCER

Bridge Admin ConnectionConnectionFactory

SonicMQClient

ConnectionJMS message

ConnectionFactoryDestination --->

Connection

ConnectionFactoryWebSphere MQ messageValidate and Map

WebSphere

MQClient


12/70

Chapter 1: Overview


The flow of a message from a SonicMQ domain to WebSphere MQ in Figure 1 starts on

the left:

1. At startup, the Bridge Server reads in the configuration file that defines the connection

and destination parameters for each side of the Bridge.

2. Each message that initiates in a SonicMQ client application is staged at a declared

destination on a SonicMQ message broker.

3. When a Bridge resource connector is actively connected to that message broker, it

declares the destinations from which it intends to consume messages. If a message is

available for receipt, the Bridges consumer on that destination receives the message.

4. The consumer destination associates with a producer destination, typically in another

resource connectors scope. In this case, a destination of a SonicMQ resource

connector binds itself to a queue destination of a WebSphere MQ resource connector.

5. As the message moves to the producer destination, it can be validated both before and

after it is mapped to the WebSphere MQ message type and layout. Any rejected

messages and their unacceptable data conditions are recorded in the Bridge log. If theconfiguration has defined a primary and backup Dead Message Queue and the DMQ

is active, the messages will be transferred to the DMQ.

6. The transformed message is sent to the specified queue in the WebSphere MQ Queue

Manager.


13/70



Sending Data from a WebSphere MQ Domain to a SonicMQ Domain

Figure 2 provides a graphic overview of how the SonicMQ Bridge for WebSphere MQlets a SonicMQ client receive a WebSphere MQ message.

The flow of the message in Figure 2 starts on the right:

1. At startup, the Bridge Server reads in the configuration file that defines the connection

and destination parameters for each side of the Bridge. The resource for connecting

to the WebSphere MQ realm is the Java-based (but not JMS) libraries that enable the

Bridge to act as a WebSphere MQ client, connecting to the queues, channels, and

queue manager defined in the Bridge configuration.

2. A WebSphere MQ native client application sends a message to a defined

WebSphere MQ queue.

3. The Bridge resource connector is a WebSphere MQ queue consumer actively

connected to the WebSphere MQ Queue Manager, which regularly polls that Queue

to receive messages. When it consumes a message from the Queue Manager queue, it

passes a canonical form of the received message along with its name to the specifiedproducer on the SonicMQ side of the Bridge.

Figure 2. Bridging a WebSphere MQ MQMessage to a SonicMQ Message

WebSphereMQ

QueueManager

WebSphereMQ

Client

Bridge Descriptor

SonicMQ

Message

Broker

Resource Connector

WebSphere

MQ

Channel

Connection

Bridge Application

JMS

Physical

Connection

Bridge

Resource Connector

Destination

Role is PRODUCER

Destination

Role is CONSUMER

Bridge Admin ConnectionConnectionFactory

SonicMQClient

JMS message ConnectionFactory


14/70

Chapter 1: Overview


4. As the message moves to the producer destination, it can be validated both before and

after it is mapped into a JMS message type with appropriate JMS metadata and

payload packaging. Any rejected messages and their unacceptable data conditions are

recorded in the Bridge log. If the configuration has defined a primary and backup

Dead Message Queue and the DMQ is active, the messages is transferred to the DMQ.

5. The SonicMQ JMS resource connectors producer sends the message to the

appropriate SonicMQ topic or queue.

6. A SonicMQ client receiving on that SonicMQ queue or topic receives the message.

Message MappingThe SonicMQ Bridge for WebSphere MQ supports the transfer of all JMS message types

to and from the WebSphere MQ domain as shown in Table 1. WebSphere MQ allows user-

defined formats or application-specific formats.

The WebSphere MQ message format is a fixed-length string of eight characters. If the

message format string is omitted, it is assumed to be a bytes message.

Mapping Process

The SonicMQ Bridge for WebSphere MQ sets the message type in the message header

format field when it receives a message from SonicMQ before sending the message to

WebSphere MQ.

Table 1. Mapping of Message Types Between SonicMQ and WebSphere MQ

Sonic MQMessage Type

WebSphere MQ MQMessage Encoding and FormatField Setting that Defines the Type

TextMessage or

XMLMessage

MQMessagewith the message format field set to the constant

MQC.MQFMT_STRING

BytesMessage MQMessage with the message format field set to Bytes or if the

msg.format is null or missing

MapMessage Encoded MQMessagewith the message format field set to Map

StreamMessage Encoded MQMessagewith the message format field set to Stream

ObjectMessage MQMessagewith the message format field set to Object.


15/70


Message Mapping

WebSphere MQ clients can specify the message type in the WebSphere MQ format field

when the message is created in that domain. The Bridge can map that into the appropriate

JMS message type when it receives messages from WebSphere MQ.

Map and Stream Messages

When the message type is a MapMessageor StreamMessage, it is expected that the WebSphere

MQ message has the message layout string prepended to the original MQMessage.

When a message is received from WebSphere MQ, the message format field is examined

and the following occurs:

If the format field is set to one of the values (Map, Stream, Object, Bytes) that specifies

a SonicMQ message type, then the corresponding JMS message type is created.

Ifmsg.format = MQC.MQFMT_STRING, a JMS TextMessage is created.

If the value is null, a JMS BytesMessage is created.

The data types that are supported in a MapMessageor StreamMessage are those specified for

JMS 1.0.2 boolean, byte, short,char, int, long, float, double, String, and byte[ ].

Handling JMS Message Types in WebSphere MQ

When messages flow between SonicMQ and WebSphere MQ, the WebSphere MQMessage

is distinguished settings in the format field as shown in Table 1

TextMessage and XMLMessageA JMS TextMessage flows smoothly across the Bridge. While an XMLMessage is sent as a

TextMessage, there is no correspondent typing of an MQMessagewith XML identifiers as an

XMLMessage.

Bridge to WebSphere MQ A Bridge producer to WebSphere MQ maps a

SonicMQ TextMessage (or a SonicMQ derivative, XMLMessage) to an MQMessage with

the format field set to MQSTR by specifying the constant MQC.MQFMT_STRING.

For example:

MQMessage msg = new MQMessage();

msg.format = MQC.MQFMT_STRING;

WebSphere MQ to the Bridge When the Bridge consumes a WebSphere MQ

message where the format is the constant MQC.MQFMT_STRING, the message is mapped

to a JMS TextMessage.


16/70

Chapter 1: Overview


BytesMessage

There is no distinct byte message class in WebSphere MQ so a best effort is made tohandle a JMS BytesMessage sent into a WebSphere MQ domain.

Bridge to WebSphere MQ A Bridge producer to WebSphere MQ maps a

SonicMQ bytesMessageby setting the MQMessage format field to Bytes to indicates that

the message body contains a byte stream.

MQMessage msg = new MQMessage();

msg.format = Bytes;

and then written in the WebSphere MQ domain with:msg.write(data.getBytes());

WebSphere MQ to the Bridge When the Bridge consumes a WebSphere MQ

message where msg.format = Bytes, the message is mapped to a JMS

BytesMessage.

MapMessage

A JMS MapMessagehas a body that consists of name-value pairs where each value is stored

as a specified data type. As there is no equivalent message type in WebSphere MQ, the

Bridge implements a mechanism that embeds the length and content of the message

format layout before the actual message body. When the message format is Map, the

message format layout is extracted and then used as the template to identify the intended

name-value pairs that comprise the remainder of the message body. When a name-value

pair is typed and created, the corresponding string segment is placed as its value. The

string value is coerced into the specified type.

The WebSphere MQ message layout in Figure 3 describes how the WebSphere MQ

encoded message is defined for a MapMessage where the MQMessage is:

As shown in Figure 3, the beginning of the message body is used to construct the message

layout that will enable name-value pairing of map data into correct data types.

59,Name,String,16,Account,Integer,Balance,Float,Active,BooleanJohn Dow 3224 9543.211

Figure 3. Example of Message Layout and Map Data


17/70


Message Mapping

The first four bytes are evaluated as an integer. This integer specifies how far to go into

the string to evaluate the layout.

The message layout delimiter value is fixed to comma. Each layout string has two

delimited parts for each name-value pair:

The name of the item.

The data type of the value associated with the name.

A name-value of a String or byte array type has an additional delimited part:

The length of the String or byte array.After the message layout is evaluated, the remainder of the message is divided into the

defined string lengths, one byte for Boolean, and the appropriate byte size for the numeric

data types.

For each direction of this mapping:

Bridge to WebSphere MQ A Bridge producer to WebSphere MQ transforms a

SonicMQ MapMessage by setting the msg.format field to Map and then encoding the

message content into the message layout.

WebSphere MQ to the Bridge A Bridge consumer from WebSphere MQ reads

the msg.format field, andif it happens to be Mapuses the encapsulated message

layout to marshal the message content into name-value pairs in a SonicMQ message

body.

For example:

msg.format = "Map";HashMap map = new HashMap();map.put("Name","John Dow ");map.put("Account",new Integer(3224));map.put("Balance", new Float(9543.21));map.put("Active", new Boolean(true));Set keys = map.keySet();MapMessageHolder mapholder = new MapMessageHolder(keys,map);mapholder.createMessageLayout();mapholder.createMQMessage(msg);

StreamMessage

There is no equivalent message type in WebSphere MQ for a StreamMessage. These

messages are converted into encoded WebSphere MQ byte messages. The start portion of

the message is embedded (using WebSphere MQ MQMessages API) with the length and

content of the message layout string that will enable the remainder of the message to be

interpreted. The length of the message is extracted by the readInt() call ofMQMessage.


18/70

Chapter 1: Overview


The WebSphere MQ message layout in Figure 4 describes how the WebSphere MQ

encoded message is defined for a StreamMessagewhere the MQMessage is:

31,String,16,Integer,Float,BooleanJohn Dow 3224 9543.211

As shown in Figure 4, the message length field delimits the message layout string. The

message layout string parts are delimited by commas. Each part of the layout string

describes a type of value andfor string and byte array data the length of the value

field. The delimiter value is fixed to comma.

For each direction of this mapping:

Bridge to WebSphere MQ A Bridge producer to WebSphere MQ transforms a

SonicMQ StreamMessage by setting the msg.format field to Stream.The mapper does all the work: it builds a layout string as the data is flowed into the

MQMessage body, evaluates the length of the layout string it constructed, prepends the

message with the layout string and then finally prepends the message with an integer

value that is the length of the message layout string.


the msg.format field, andif it happens to be Streamuses the encapsulated message

layout to marshal the message content into value types of specified lengths in aSonicMQ message body.

ObjectMessage

WebSphere MQ supports the Java object type for Java clients, a situation that might

prohibit non-Java WebSphere MQ applications from accessing data that is a Java object.

For each direction of this mapping: Bridge to WebSphere MQ A Bridge producer to WebSphere MQ transforms a

SonicMQ ObjectMessage by setting the msg.format field to Object and then encoding

the object as a byte stream into the message.


the msg.format field, andif it happens to be Objectmarshals the byte stream into

a serializable Java object which is then written as the message body of a JMS

ObjectMessage.

Figure 4. Example of a Message Layout and Stream Data


19/70


Chapter 2 Installing SonicMQ Bridge for

WebSphere MQ

This chapter provides the following installation information for the Bridge for WebSphere

MQ:

Deployment Considerations

Installation and Setup

Startup Procedures

See the document install.htm and SonicMQ V5 Bridges Startup Guide in the Bridges

docs directory for the general system and software requirements and installation

procedures for the SonicMQ Bridges.

See the SonicMQ V5 Bridges Release Notes for specific release and version information.

Important Control codes are required for each Bridge you install. Contact your SonicMQ

representative to get valid control codes before you start the installation procedure.


20/70

Chapter 2: Installing SonicMQ Bridge for WebSphere MQ


Deployment Considerations

You can set up the Bridge for WebSphere MQ on a single system or locate the componentsin a distributed computing environment, as shown in Figure 5.

SonicMQ Broker and Clients

The Bridge for WebSphere MQ depends on access to an installation of SonicMQ to

provide the JMS message broker processes, JMS behaviors, and persistent data stores.

The samples in Chapter 3 assume that you have installed SonicMQ and default

configuration of the nonsecurity evaluation database with its sample queues. You can

choose to enable security and, in addition, use SSL support but you will need to provide

valid usernames and their respective passwords in each application. See the SonicMQ V5

Bridges Startup Guide for more information about SonicMQ installation and setup.

SonicMQ libraries need to be installed on:

The system where the SonicMQ client applications will run. The system where the SonicMQ Bridge for WebSphere MQ will run the bridge server.

WebSphere MQ Server and Clients

The Bridge for WebSphere MQ requires access to a WebSphere MQ Server with the

appropriate release patches installed. See the SonicMQ V5 Bridges Release Notes and the

IBM Web site for details about WebSphere MQ. The WebSphere MQ Java client libraries

need to be copied to:

The system where the WebSphere MQ native client applications will run.

The system where the SonicMQ Bridge for WebSphere MQ will run the bridge server.

The Bridge

The bridge is installed on a system where its bridge server will be supported by a

SonicMQ client installation and a WebSphere MQ client installation.

Figure 5. Components in the Distributed Bridge Topology

SonicMQClient

WebSphere MQClient

Bridge forWebSphere MQ

SonicMQBroker

WebSphereMQ QueueManager


21/70




You must install and set up the software for SonicMQ, WebSphere MQ, and the SonicMQBridge for WebSphere MQ.

SonicMQ Broker and Clients

Install SonicMQ V5 on each system that needs its resources. While you can achieve this

goal by performing a Typical installation on each system, the actual requirements are:

Server A SonicMQ Broker system consisting of a broker (a Broker and a Container,and if there is no previously set up Domain Manager, a DirectoryService). Add SSL

Support, if required. You could also choose to install a JMS Client.

Bridge On the system that will host the bridge, the JMS Clientand SSL Support if

required.

Client On the system that will run the SonicMQ client applications, the JMS Client

and SSL Supportif required.

WebSphere MQ Server and Clients

Install the WebSphere MQ V5.3 software recommended by IBM for your implementation

platform. The requirements for the bridge are:

Server Install a WebSphere MQ Server, and then configure a Queue Manager for

the samples. Also install SSL support if required.

Bridge On the system that will host the bridge, the libraries com.ibm.mq.jar andconnector.jar are required. Also install SSL support if required.

Client On the system that will run the WebSphere MQ client applications, the

libraries com.ibm.mq.jar and connector.jar are required. Also install SSL support if

required. An appropriate Java Runtime Environment must be available.


22/70



Server Configuration for a QueueManager for the Samples

After installing and setting up a WebSphere MQ server, you need to either set up therecommended queue manager, queues and channel or modify the configuration file. The

instructions outlined below set up the recommended configuration:

A Queue Manager named progress.

Two queues in the progress Queue Manager, queue1 and queue2.

A channel preset to the samples queues, mychannel.

To accomplish these tasks, refer to WebSphere MQ documentation. The following

procedure describes the general concepts of the required configuration.

To add the configured sample queue manager to the WebSphere MQ installation:

1. Use the WebSphere MQ management console to choose the QueueManager folder

then right click to select the New > Queue Manager command. The SonicMQ Bridge

for WebSphere MQ samples require that you name this progress and use the port

assignment 1414 (the Listen on port number parameter on step 4 of the wizard.)

2. Choose the Queue Managers and then select the Queue Manager you created

(progress). Expand its tree then select its Queues folder. In the right panel, right click

to select the New > Local Queue command. The SonicMQ Bridge for WebSphere MQ

samples require that you name it queue1. Repeat this procedure and add queue2.

3. Choose the Advanced folder of the progressQueueManager. Right click on the right

panel to select the New > ServerConnectionChannel command. The SonicMQ

Bridge for WebSphere MQ samples require that you name it mychannel.

WebSphere MQ Client

The required libraries for WebSphere MQ clients are accessible in the server installation.

The required WebSphere MQ classes for Java are com.ibm.mq.jar and connector.jar.

If you are running on the same system as the server you can just indicate the location of

the libraries on the clients CLASSPATH. Otherwise, copy the client libraries to the clientsystem (the bridge or the client application system) then modify the bridge or application

CLASSPATH to include these libraries. You also need to have an appropriate Java Runtime

Environment available for the client on that system.

The native client connection does not use the JMS libraries (com.ibm.mqjms.jar).

Note When the Bridge server system has a CLASSPATH pointer to its WebSphere MQ \Java\lib

directory, it avoids the Unable to load message catalog -mqji alert at Bridge startup.


23/70



SonicMQ Bridge for WebSphere MQ

Install the bridge from the media or download by running the setup script at the root ofthe installation software. You must have a control key for this bridge to proceed through

the installation. The installer will tailor scripts to point to the host port of SonicMQ broker

you specify and the location of the local SonicMQ Client libraries that the bridge will use.

While the tailoring intends to define install locations and host port designations

completely, you might need to adjust the scripts.

Bridge EnvironmentThe file bridges_install_dir\bin\setenv is called by the bridge server, bridge

administrator, and bridge explorer scripts.

Changes that might be needed in this file are:

set SONICMQ_BRIDGES_HOME=bridges_install_dir

set SONICMQ_HOME=sonicmq_install_dir

set CLASSPATH=.;webspheremq_install_dir\com.ibm.mq.jar;

webspheremq_install_dir\connector.jar

All references to installation directories must be absolute paths.

Sample Files

Each sample file set contains an XML-based configuration and a launch script for each of

the sample applications.

Bridge Server

On the bridge server system:

Verify that the sample script bridge in each sample folder correctly designates its

installation location in the statement:

set SONICMQ_BRIDGES_HOME=bridges_install_dir

Modify the sample configuration BridgeConfig.xml to set:

The appropriate usernames and password on connection parameters if

authentication is enabled on either server.

The connectionFactory to indicate the host port of each of the messaging servers

and administrative connections.


24/70



SonicMQ Client Applications

While you could install the bridge server on the target client system, you can provide just

what is required by copying the samples for the SonicMQ client to the system where you

installed the SonicMQ JMS Client and its Java runtime.

For example, the sample bridges_install_dir\samples\WebSphereMQBridge\Talkcan be

copied to the SonicMQ client system by copying Talk*.*. Then modify the script

(Talk.bat for Windows; Talk.sh for UNIX/Linux) to call the

sonicmq_install_dir\bin\setenv script that will locate the libraries and the JRE.

WebSphere MQ Client Applications

You can copy WebSphere MQ native applications to the system where the

WebSphere MQ client libraries com.ibm.mq.jar and connector.jar were copied.

For example, the sample bridges_install_dir\samples\WebSphereMQBridge\Talkcan be

copied to the WebSphere MQ client system by copying MQNativeTalk*.*.

Then modify the script (MQNativeTalk.bat for Windows; MQNativeTalk.sh forUNIX/Linux) to either:

Call the sonicmq_install_dir\bin\setenv script to locate the libraries and the JRE if

SonicMQ is installed on this system.

Set the variable JAVA to the Java home you want to use and set the CLASSPATH to include

the WebSphere MQ client libraries and the Java libraries.

A client sends messages to a destination on its message broker. The Bridge consumes

from that designated destination, transforms the messages, and produces the messages to

the other server. The client of that server consumes from that servers destination.


25/70


Startup Procedures

Startup Procedures

The following steps provide a brief outline of the procedures for running the componentsafter you have performed the specified installations and set ups and then tuned the

references to host ports, Java, local installation locations, and CLASSPATH statements.

To run the components in a distributed Bridge deployment:

1. SonicMQ Brokersystem Run the startcontainer script.

2. WebSphere MQ Queue Manager system Start the WebSphere MQ service then

start the progress Queue Manager.

3. Bridge for WebSphere MQ system In a console window located in a sample

applications folder, run its bridge script.

4. WebSphere MQ Clientsystem In a console window, run the WebSphere MQ

sample applications script and pass it the required parameters.

5. SonicMQ Clientsystem In a console window, run the SonicMQ sample

applications script and pass it the required parameters.

When all the components are running, a client sends messages to a destination on its

message broker. The Bridge consumes from that designated destination, transforms the

messages, and produces the messages to the other server. The client of that server

consumes from that servers destination.

Note The samples for the SonicMQ Bridge for WebSphere MQ are preconfigured to use port

1414 on the Queue Manager progress that you define. Because a typical WebSphere MQinstallation guides you to set up a Queue Manager on port 1414 named QM_computername.,

you might experience error 2009 when trying to connect the sample applications because

of this port overloading.

You can resolve the situation by opening the WebSphere MQ Services tool (rather than

the WebSphere MQ Explorer) and then right-clicking on the default Queue Manager

QM_computername, choosing Properties, choosing the TCP tab and then changing the

Queue Managers TCP Port number to another value. Then use the WebSphere MQ

Explorer to restart both Queue Managers.


26/70




27/70


Chapter 3 Running the Samples

This chapter provides the following information on the samples that come with the Bridge

for WebSphere MQ:

About the Samples

Structure of the Sample Folders

General Instructions for Running the Samples

Running the Talk Sample

Running the Order Inventory Sample

Running the Chat Sample

Ch R i h S l


28/70

Chapter 3: Running the Samples


About the Samples

The SonicMQ V5 Bridge for WebSphere MQ sample files send messages between aSonicMQ message broker and a WebSphere MQ QueueManager running nativewithout

using the WebSphere MQ JMS API.

After you set up SonicMQ, WebSphere MQ, and the Bridge, three samples are presented

in detail:

Talk shows how messages created in the JMS Point-to-point messaging model in

SonicMQ can be received by the Bridge where each message is transformed into a

compatible WebSphere MQ message.

OrderInventory provides basic processing of order-entry requests. The InventoryHost

reads and writes on WebSphere MQ Native Queues while a client sends to and

receives from SonicMQ Queues. The order-entry client requests are in XML format

conforming to a DTD.

Chat demonstrates transitioning queued messages in the WebSphere MQ domain to

published JMS messages and, conversely, receiving messages on a subscribed topic

and enqueuing them in the WebSphere MQ domain

St t f th S l F ld


29/70




Each of the sample folders provides a set of files that might be disbursed in actualdeployment. In a sample folder you will find:

Bridge configuration A configuration file (.xml)

Bridge Startup script A bridge.bat file and similar bridge.sh file

Application startup scripts One or more Windows batch files (.bat) and similar

UNIX/Linux scripts (.sh)

Sample source and compiled files One or more Java source files (.java) and at

least as many related class files (.class)

General Instructions for Running the SamplesAll the samples use the components described Chapter 2, Installing SonicMQ Bridge for

WebSphere MQ. First, start the SonicMQ broker and WebSphere MQ Queue Manager.

Then start the Bridge, which will then establish its connection to the SonicMQ messagebroker and the WebSphere MQ Queue Manager. The client applications then run, one

connecting to the SonicMQ message broker and the other connecting to the WebSphere

MQ Queue Manager.

Starting the SonicMQ message broker

If the message broker is not already running, start the SonicMQ message broker.

Starting the message broker process from the Windows Start menu:

Choose Start > Programs > Sonic Software > SonicMQ > SonicMQ Container1

Alternately, in a new console window set to the SonicMQ install directory, type

./startcontainer.bat and press Enter.

Starting the message broker process from a UNIX/Linux console window:

In a new console window set to the SonicMQ install directory, type

./startcontainer.sh and press Return.

The console window is dedicated to the process and displays a message similar to:

[date-time] TCP_ACCEPTOR: accepting connections on tcp://mySystem:2506

Warning You can minimize the SonicMQ message broker console window. Closing the window,however, will stop the message broker.



30/70



Gathering Information from the SonicMQ message broker

The samples in this guide are targeted at a standard, local SonicMQ message broker

installation. The settings and parameters of the SonicMQ broker might require you to

adjust the configuration of the Bridge.

The Bridge for WebSphere MQ samples use the SonicMQ message broker default

settings:

Host and port The standard installation is to port 2506. If the SonicMQ

installation is on the same system as the component referencing it (the Bridge

installation or the SonicMQ client), it can be referred to as localhost. Queues When a SonicMQ message broker is installed it creates the sample queues

(SampleQ1, SampleQ2, SampleQ3, and SampleQ4). You can assume that these queues exist

unless you explicitly re-created the database. If you want to specify the names of other

queues that you know exist, you need to substitute those queue names in sample

scripts.

If you want to check on the existence of these sample queues or specify other queues,

refer to Getting Started with SonicMQ V5 or SonicMQ V5 Configuration andManagement Guide for information on setting up queues.

Security Broker security is, by default, not enabled. As a result, there is no

authentication or authorization of user names and passwords shown in the samples.

Refer to the SonicMQ V5 Configuration and Management Guide for instructions on

setting up user names and passwords. When security is inactive, any user can read

from or write to any destination.

If you do have security enabled on the SonicMQ message broker, you need to ensurethat references to user names can be authenticated and that sample destinations are

accessible to those users.

Starting the WebSphere MQ Queue Manager

Start your WebSphere MQ server and ensure that the Queue Manager you want to use is

started and connected.

To start the WebSphere MQ service and the QueueManager:

1. On Windows, open the Control Panel for Services. If WebSphere MQ is not running,

start it.

2. In the WebSphere MQ Explorer, choose the QueueManagers and then check to see

that the QueueManager you are using is started and connected.



31/70



Setting Up the SonicMQ Bridge

To configure a SonicMQ Bridge for WebSphere MQ for your environment, edit theconfiguration file you want to use to define the environment, connection factories, and

destinations that the Bridge will use. While the Bridge has settings you can customize to

specify administration and features such as the Dead Message Queue, the samples only

require that you set up the connections on either end of the Bridge.

The Bridge needs SonicMQ client libraries and WebSphere MQ client libraries. See

Chapter 2, Installing SonicMQ Bridge for WebSphere MQ, for information about the

required libraries.

Modifying the Configuration File for SonicMQ

The default configuration variables are preset to coordinate with the samples and do not

need modification if you are using the preset host, port, queues, and security options for

the SonicMQ message broker. See Chapter 4, Configuring the Bridge for WebSphere

MQ,for details about changing the configuration file.

Modifying the Scripts for SonicMQ

If you changed any configuration settings for the SonicMQ side connection, you need to

make corresponding edits to the SonicMQ client application scripts. For example, in the

Talk sample the Talk scriptthe script that runs the SonicMQ client application for the

samplehas the following command line:

call "%JAVA%" Talk -b localhost:2506 -u Sonic -bean Queue-ds SampleQ1 -dr SampleQ2

The parameters in most SonicMQ sample command lines are listed in Table 2.

Table 2. Parameters in the command line of the SonicMQ samples

Parameter Description

-b (broker) The host:port of the SonicMQ message broker.

-u (username) The authorized user when the SonicMQ message broker is security enabled.

-p (password) An authorized users password.

-bean (Sonic domain) MessagingBean to implement. TOPIC for Pub/Sub, QUEUE for Point-to-point.

-ds (send destination) SonicMQ producer destination for send (queue) or publish (topic).

-dr (receive destination) SonicMQ consumer destination for receive (queue) or subscribe (topic).



32/70



Specifying the Broker

The default port for a SonicMQ message broker is 2506 and localhost expresses that the

application is running on the same system as the message broker. If the system where the

message broker is running were Eagle, listening on port 2345, you would need to modify

the script command to:

call "%JAVA%" Talk -b Eagle:2345 -u Sonic -bean Queue-ds SampleQ1 -dr SampleQ2

Specifying an Authorized User

If you are using security, enter an authentic user and add the password with the -p

parameter. For example:

call "%JAVA%" Talk -b localhost:2506 -u user -p password -bean Queue-ds SampleQ1 -dr SampleQ2

Modifying the Scripts for WebSphere MQ

If you changed any configuration settings for the WebSphere MQ connection, you needto make corresponding edits to the application scripts. If you changed the host and port in

the configuration file, change it in the WebSphere MQ client script as well. For example,

in the Talk sample the MQNativeTalkscriptthe script that runs the WebSphere MQ client

application for the samplehas the following command line:

call "%JAVA%" MQNativeTalk -qm progress -p 1414 -ch mychannel-h localhost -ds queue1 -dr queue2

The parameters in most WebSphere MQ sample command lines are listed in Table 3.

Table 3. Parameters in the command line of the SonicMQ samples


-qm (Queue Manager) The Queue Manager of the WebSphere MQ queues.

-p (port) The port on the host where the Queue Manager is listening. The authorized user

when the SonicMQ message broker is security enabled.

-ch (channel) The server connection channel to the Queue Manager. Note that this parameter is

requiredalthough not evaluatedif the connection mode is BINDINGS.



33/70


g p

The default port for a WebSphere MQ Queue Manager is 1414 and localhost expresses

that the application is running on the same system as the QueueManager. If the system

where the message broker is running were Hawk, listening on port 1515, you would need tomodify the script command to:

call "%JAVA%" MQNativeTalk -qm progress -p 1515 -ch mychannel-h Hawk -ds queue1 -dr queue2

Review of the Set Up for Each Sample Application

When the servers are setup and running, and the bridge, the clients, and the applicationsare distributed, you can run the samples. The bin/setenv script with correct path and

classpath statements will be called by all samples. In each sample folder you must:

1. Edit each client script to be sure it has:

Correct path statements

The correct host port for the client

If security is enabled, a valid username and the added -p password parameter.2. Edit the server script to be sure it has:

Correct path statements.

The correct name of the configuration file.

3. The XML configuration file to be sure that it has:

Correct host port designations in all the connectionFactory elements

If security is enabled, valid usernames and passwords in the connection elements.

-h (host) Host system. localhost denotes that the Queue Manager resides on the same

system as the console window that will run the sample.

Note that localhostmakes BINDINGS possible but does not implicitly implement

it. The option ofTCPIP or BINDINGS is defined in the configuration file element for

the WebSphere MQ connectionFactory in the connectionType parameter

reference. See Managing Connectivity on page 61and Connection Factory on

page 57 for information about these parameters.

-ds (send queue) WebSphere MQ queue to which messages will be sent.

-dr (receive queue) WebSphere MQ queue from which messages will be received.

Table 3. Parameters in the command line of the SonicMQ samples (continued)




34/70


Running the Talk Sample

The sample files send messages between a WebSphere MQ Queue Manager and aSonicMQ message broker.

To run the Talk sample:

1. Open three console windows, changing to the samples directory:

cd bridges_install_dir\WebSphereMQBridge\samples\Talk

2. In the first console window, enter:

bridge

The Bridge server startup sets the environment, reads in the configuration file, and

then starts this Bridge server instance.

3. In the second console window, enter:

talk

A SonicMQ PTP messaging session starts.

4. In the third console window, enter:MQNativeTalk

A WebSphere MQ messaging session starts.

5. In the Talk window, type some text; for example, Hello WebSphere MQ.

Press Enter. The text is sent as a TextMessage from the SonicMQ client to the

SonicMQ broker, through the SonicMQ Bridge to the WebSphere MQ queue. The

message is received by the WebSphere MQ client and the text is displayed in the

MQNativeTalk client window

6. In the MQNativeTalk window, type some text; for example, Hello SonicMQ. Press

Enter. The text is sent from the WebSphere MQ client to the queue on the

WebSphere MQ Queue Manager. The message is transported and mapped across the

bridge to the specified queue on the SonicMQ broker queue. The message is received

by the SonicMQ client and the text is displayed in the Talk client window.



35/70



The OrderInventory sample is a host application that services order-entry requests.InventoryHostwrites to and reads from WebSphere MQ Queues while the corresponding

client writes to and reads from SonicMQ Queues. The Bridge allows messaging between

the two different messaging systems.

The order-entry client sends requests and gets replies in XML format conforming to

SampleOrderEntry.dtd. The XML is passed in text messages to and from JMS queues.

These JMS Queues are bridged to WebSphere MQ queues on the other side of the

Bridge, which are serviced byInventoryHost. The order-entry client is a Java GUIapplication, which connects to the SonicMQ broker and sends and receives messages on

a queue.

The Order-entry client has three operationslist, order, and inStock:

list operation lists the entries in the inventory host.

order allows a customer to order an item from the inventory table.

inStock looks up requested quantities to conform whether they are available.

Some special fields and files are used in this sample:

The customerID uniquely identifies an Inventory client.

Inventory.tsv (tab separated values) is a simulated inventory database.

OrderNoCounter.txt keeps track of the last orderNo assigned.

Inventory.propertiesmaintains settings.

SampleOrderEntry.dtddescribes the format of messages passed between order-entryclient and InventoryHost.

The screens that accompany the procedures choose to focus on one inventory line item as

shown inFigure 6. You can choose an item and quantities that you prefer when you run

the sample.

To run the Order Inventory sample:

1. Open three console windows, changing to the sample directory:

cd bridges_install_dir\WebSphere MQBridge\samples\OrderInventory

2. In the first console window, enter: bridge

Figure 6. Inventory Item



36/70


3. The bridge server starts as shown in Figure 7.

4. In the second console window, enter: server

The Order Inventory Server for the sample starts.

5. In the third console window, enter: client

The sample application starts and open its Inventory Client window.6. Select the List option.

The Inventory Client window lists the inventory in a table, as shown in Figure 8.

Figure 7. Bridge Server for the Order Inventory Sample

Figure 8. Order Inventory List



37/70


7. Select the Order option.

a. The Input window opens where you enter an integer quantity such as 14, as

shown in Figure 9.

b. When you clickOK, the Total PRICE of the Order Placed window extends the

product price with the requested quantity, as shown in Figure 10.

c. When you clickOK, the Order Status window registers the order and states the

orders assigned order number, as shown in Figure 11.

d. ClickOK to finish the order processing.

Figure 9. Order Inventory Ordered Quantity

Figure 10. Order Inventory Ordered Amount

Figure 11. Order Inventory Order Completion



38/70


8. On the Inventory Client window, select the InStock option.

a. The Input window opens where you enter an integer quantity such as 12, as

shown in Figure 12.

b. The Order Status window displays whether inventory does or does not have the

requested quantity in stock., as shown in Figure 13.

c. ClickOK to finish the query processing.

Figure 12. Order Inventory InStock Quantity

Figure 13. Order Inventory InStock Status



39/70



The sample files are in:bridges-install-dir\WebSphereMQBridge\samples\Chat

To run the Chat sample:

1. Start three console windows, changing to the sample directory:

cd bridges_install_dir\WebSphereMQBridge\samples\Chat

2. In the first console window, enter:

bridgeThe Bridge server startup sets the environment, reads in the configuration file, and

then starts this Bridge server instance.

3. In the second console window, enter:

chat

A SonicMQ Pub/Sub messaging session starts for the SonicMQ topic-based

application named Talk. Messages can be entered into the console window and sent

by pressing Enter. Messages received are displayed in the console window.

4. In the third console window, enter:

MQNativeTalk

A queue session starts for a native WebSphere MQ client.

5. In the chat window, type some text; for example, Hello WebSphere MQ.

Press Enter. A message containing the text is sent from the SonicMQ client to the

SonicMQ broker then through the WebSphere MQ Bridge to the WebSphere MQ

queue. The message is received and its text is displayed in the MQNativeTalk client

window.6. In the MQNativeTalk window, type some text; for example, Hello SonicMQ. Press

Enter. A message containing the text is sent from the WebSphere MQ client to the

WebSphere MQ Queue Manager then mapped across the WebSphere MQ Bridge to

the SonicMQ broker topic. The message is received by the SonicMQ client and its text

is displayed in the chat client window.

Note Native WebSphere MQ does not support the notion of an MQNativeChat. You can see

how the Pub/Sub concepts for WebSphere MQ work when you use the MQSeries

Publish/Subscribe Broker, a feature of WebSphere MQ JMS. See the SonicMQ V5Bridge for JMS Users Guide for details about this functionality as well as an example.



40/70



41/70


Chapter 4 Configuring the Bridge for WebSphere MQ

This chapter provides the following management information on the Bridge for

WebSphere MQ:

Overview of the Bridge Configuration File

Specifying WebSphere MQ Bridge Configuration Information

Administering the Bridge

Managing Connectivity

Managing Security

Managing Quality of Service

Chapter 4: Configuring the Bridge for WebSphere MQ


42/70


Overview of the Bridge Configuration File

Whenever an instance of a Bridge server starts, its configuration file determines theconnections and objects that are used on each side of the Bridge.

Figure 14 presents a detailed description of the contexts in the configuration file for one

of the samples you will be running.

A resource connector can have several destinations in its scope. Each destination binds to

a connection, and each connection binds to a connection factory.

See SonicMQ V5 Bridges Startup Guide for general Bridge configuration information.

Figure 14. Configuration of Resources for a Two-way SonicMQ Bridge for WebSphere MQ

SonicMQ

Physical

Connection

localhost

2506

Admin

password

Bridge Descriptor MQSeriesQueueBridgeSample validated by: ../../dtd/bridgedescriptor.dtd

SonicMQ

Broker

WebSphere

MQ Queue

Manager

Resource ConnectorSonic:ResourceConnector

WebSphereMQ

Channel

Connection

localhost

1414

progress

mychannel

Bridge ApplicationMQSeriesBridgeOrderInventoryApp

SonicMQ

PhysicalConnection

localhost

2506

user

password

BridgeMQBridge

Resource ConnectorMQ:ResourceConnector

Destination Sonic:fromSonicQ

Role is CONSUMER from QUEUE SampleQ1

DestinationMQ:fromSonicQ

Role is PRODUCER to queue2 syncPoint

InboundMessageValidator

MQMessageMapper

OutboundMessageValidator

DestinationSonic:toSonicQ Role is PRODUCER to QUEUESampleQ2

OutboundMessageValidator

MQMessageMapper

InMessageValidator

DestinationMQ:toSonicQ Role is CONSUMER fromqueue1syncPoint, wait, 10000

Bridge AdminBridgeAdministrator Connection Sonic:adminConnection administratorConnectionFactory Sonic:adminCF

WebSphere MQ message received from queue1SonicMQ message sent to SampleQ2

SonicMQ message received from SampleQ1 MQSeries message sent to queue2 .

ConnectionFactory MQ:cF

Destination MQ:fromSonicQ

Destination Sonic:toSonicQ

ConnectionFactory MQ:cF

Connection Sonic:connection aUser

ConnectionFactory Sonic:cF

Connection Sonic:connection aUser

ConnectionFactory Sonic:cF



43/70


Specifying WebSphere MQ Bridge Configuration

InformationThe following sections describe configuration information for the Bridge for WebSphereMQ. The configuration information for the Bridge for WebSphere MQ is in an XML file,

which is loaded at run time. The SonicMQ V5 Bridges Startup Guide describes the

elements and attributes in the configuration file as required by bridgedescriptor.dtd, the

DTD file for all of the Bridges configuration files.

As described in the SonicMQ V5 Bridges Startup Guide, the DTD file requires one

bridgeDescriptor, the root element, and a series of elements and attributes in a specifiedorder. In addition, the elements can have resourceRef elements with name and type

attributes and parameterRef elements with name and value attributes. Within an element,

all resourceRef elements must appear before all parameterRef elements.

The following sections provide specific details for defining the XML configuration

elements and attributes for the Bridge for WebSphere MQ. This file is the configuration

file for the Order Inventory sample.

The tables of attributes list the available attributes as well as the resource references and

parameter references expressed for the element. These referential attributes are listed in

the configuration file in the form:

and are presented in the tables of attributes as:

Note The Bridge Dead Message Queue elementsbridgeDMQ, destination for the bridgeDMQ,

and committed connection and connectionFactory referencesare not described in this

chapter. These elements are consistently applied in all Bridges and are discussed in the

SonicMQ V5 Bridges Startup Guide.

resourceRef

type

name of the element oftypethat is referenced

parameterRef

name

value options for the parameter



44/70


Bridge Descriptor

The header of the configuration file includes the name identifier of this Bridge Server in

a bridgeDescriptor element, and the assigned DTD file that will validate the file:

The rest of the configuration file

Table 4 describes the configuration information for defining the bridgeDescriptor

element.

Bridge Administrator

This bridgeAdmin section of the configuration XML file defines the Bridge Administrator

and references its connection:

Table 5 describes the configuration information for defining the bridgeAdmin element.

Table 4. bridgeDescriptor Element Attributes

Attribute Description

name Unique logical name of the Bridge Descriptor.

Table 5. bridgeAdmin Element Attributes


name Unique logical name of the bridgeadmin element.

resourceRef

connection

Logical name of a connection that defines the SonicMQ

broker for administering the Bridge server, Bridge

applications, and Bridges.



45/70


Bridge Application

The bridgeApplication section of the configuration file defines the Bridge application:

Table 6 describes the configuration information for defining a bridgeApplication

element.

Table 6. bridgeApplication Element Attributes


name Unique logical name of the Bridge Application.

startOption ONCREATION (the default) or ONCOMMAND.

resourceRef

bridge

Names of the Bridge elements in the Bridge application.


B id


46/70


Bridge

The bridge section of the configuration XML file defines one or more Bridges and

references each Bridges two resource connectors. There is a SonicMQ resource

connector on one side and a WebSphere MQ resource connector on the other side:

Table 7 describes the configuration information for defining a bridge element.

Table 7. bridge Element Attributes


name Unique logical name of the Bridge.

class Class implementing this Bridge.

startOption ONCREATION (the default) or ONCOMMAND.

resourceRef

resourceConnector

Logical name of the resourceConnector elements that

define the two ends of the Bridge.


Reso rce Connector


47/70


Resource Connector

The resourceConnector section of the configuration file defines a WebSphere MQ and a

SonicMQ resourceConnector element. Each resource connector element binds to

destination elements.

As the samples exhibit simple back and forth data transfers, each resource connector has

two destinations: one that consumes data and one that produces data:

Table 8 describes the configuration information for defining a resourceConnectorelement.

Table 8. resourceConnector Element Attributes


name Unique logical name of the resource connector.

class Class implementing this resource connector.

resourceRef

destination

Logical names of the destinations used within the

resource connector.


Destinations


48/70


Destinations

The destination elements in the sample configuration file define four destinations: a

consumer and a producer on each side of the Bridge.

The SonicMQ side is set up with SampleQ1 and SampleQ2. The WebSphere MQ side is set

up with queue1 and queue2. The mapping between them is:

Consume from SonicMQ SampleQ1 and produce to WebSphere MQ queue2

Consume from WebSphere MQ queue1 and produce to SonicMQ SampleQ2

Destinations for the Bridge from SonicMQ to WebSphere MQ

To bridge from SonicMQ to WebSphere MQ, a SonicMQ consumer destination is defined

that calls a WebSphere MQ producer destination.

SonicMQ Consumer Destination

A SonicMQ consumer destination is a client consumer of messages from a SonicMQ

message broker location. The type in this example declares Point-to-point messaging anda queue name is designated.

The destination section of the configuration file defines one or more destination

elements, and each destination element can have resourceRef and parameterRef

elements:


Table 9 describes the elements and attributes for defining a destination element


49/70


Table 9 describes the elements and attributes for defining a destination element.

Table 9. SonicMQ Consumer destination Element Attributes


name Unique logical name for this destination.

role CONSUMER Receives messages from the SonicMQ

message broker.

destination The name of the physical SonicMQ queue or topic, in thisexample, one of the SonicMQ default queues.

type TOPIC or QUEUE.

In this example, a queue.

resourceRef

destination

The element that defines the target destination in the

WebSphere MQ domain.

In this example, the target destination is MQ:fromSonicQ.

resourceRef

connection

The element that defines the JMS connection.

In this example, the JMS connection is

Sonic:connection.

parameterRef

TransactedSesion

A JMS session parameter, the value is either true or

false. The default value is false.

parameterRef

SessionAckMode

A JMS session parameter. The value of this parameter is

one of the following:

AUTO_ACKNOWLEDGE (default)

CLIENT_ACKNOWLEDGE

DUPS_OK_ACKNOWLEDGE


WebSphere MQ Producer Destination


50/70


WebSphere MQ Producer Destination

The SonicMQConsumer Destination declared that this destination was its target. The

producer destination references the validators and mappers that check and transform thedata into the target paradigm then uses the parameter list to specify values unique to the

target domain:

The message mapper resource reference marshals the SonicMQ message data into the

appropriate WebSphere MQ data elements. Inbound and outbound validators could

accompany the mapper to add tighter control over data.

See Message Mapping on page 14for information on data type mapping.

a WebSphere MQ producer specifies a syncPointparameterRef element to specify the

acknowledgement mode.


Table 10 describes the configuration information for a WebSphere MQ producer


51/70


g p Q p

destination element.

Table 10. WebSphere MQ Producer destination Element Attributes


name Unique logical name of the destination.

role PRODUCER Sends messages to the WebSphere MQ

messaging domain.

destination a WebSphere MQ queue.

type QUEUE

resourceRef

connectionFactory

The name of the connection factory element that defines

the WebSphere MQ Queue Manager connection.

In this example, the WebSphere MQ connection is

MQ:cF.

parameterRef

syncPoint

Specifies client acknowledgement or a transaction. This

value is either true or false.

resourceRef

inboundMessage

Validator

The logical name of the inbound message validator. This

value is optional, and is not used in the example.

resourceRef

messageMapper

The logical name for the message mapper element that

defines how to map messages between the SonicMQ and

WebSphere MQ domains.

In this example, the message mapper is

MQMessageMapper.

resourceRef

outboundMessage

Validator

The logical name of the outbound message validator. Thisvalue is optional, and is not used in the example.


Destinations for the Bridge from WebSphere MQ to SonicMQ


52/70


g p

To bridge from WebSphere MQ to SonicMQ, a WebSphere MQ consumer destination is

defined that declares a SonicMQ producer destination.

WebSphere MQ Consumer Destination

A WebSphere MQ consumer destination is a client consumer of messages from a

WebSphere MQ queue manager:

A WebSphere MQ consumer has parameterRef elements to specify Quality of Service(QoS) parameters.


Table 11 describes the configuration information for a WebSphere MQ consumer


53/70


destination element.

Table 11. WebSphere MQ Consumer destination Element Attributes


name Unique logical name of the destination.

role CONSUMER Receives messages from the WebSphere

MQ messaging domain.

destination A WebSphere MQ queue.

type QUEUE

resourceRef

destination

The element that defines the target destination in the

SonicMQ domain.

In this example, the target destination is

Sonic:toSonicQ.

resourceRef

connectionFactory

The name of the connection factory element that defines

the WebSphere MQ Queue Manager connection.

In this example, the WebSphere MQ connection is

MQ:cF.

parameterRef

wait

Specifies whether the resource connector should wait for

messages to arrive on a destination. This value is eithertrue or false.

parameterRef

waitInterval

Specifies how long to wait on a destination to retrieve

messages. It is the maximum time that an MQQueue.get

call waits for a suitable message to arrive.

A non-negative value represents the wait interval in

milliseconds. For example, 10000 is ten seconds.

Also can be set to -1 to cause the Bridge to wait

indefinitely.

parameterRef

syncPoint

QoS: Specifies client acknowledgement of each message

(false) or a transaction (true).


SonicMQ Producer Destination


54/70


A SonicMQ Producer destination is a producer of a message to the stated type of

destination on a SonicMQ message broker, TOPIC or QUEUE. The type in this exampledeclares Point-to-point messaging and a queue name is designated.

The message mapper that the producer destination references marshals the WebSphere

MQ message data into the appropriate SonicMQ JMS metadata, message type, and

payload. Inbound and outbound validators could accompany the mapper to add tighter

control over data.

See Message Mapping on page 14for information on data type mapping.


Table 12 describes the elements and attributes for defining a destination element.


55/70


Table 12. SonicMQ Consumer destination Element Attributes


name Unique logical name for this destination.

role PRODUCER sends messages to the SonicMQ message

broker.

destination The name of the physical SonicMQ queue or topic, in thisexample, one of the SonicMQ default queues.

type TOPIC or QUEUE. In this example, a queue.

resourceRef

connection

The element that defines the JMS connection.

In this example, the JMS connection is

Sonic:connection.

resourceRef

inboundMessage

Validator

The logical name of the inbound message validator. This

value is optional, and is not used in this example.

resourceRef

messageMapper

The logical name for the message mapper element that

defines how to map messages between the SonicMQ and

WebSphere MQ domains.

In this example, the message mapper is

MQMessageMapper.

resourceRef

outboundMessage

Validator

The logical name of the outbound message validator. This

value is optional, and is not used in this example.


Connection


56/70


The connection section of the configuration file defines the connection information and

references its connection factory.

This element is not used for WebSphere MQ connections. The destinations for SonicMQ

reference a connection, which then references a connection factory. WebSphere MQ

destinations reference their connection factory directly.

The administrative connection must also be defined even if it accesses the same

connection factory:

Table 13 describes the elements and attributes for defining a connection element.

Table 13. connection Element Attributes


name Unique, logical name of the connection.

protocol TCP, HTTP, or SSL.

user The name of the user.

password The password of the user.

resourceRef

connectionFactory

Name of the connection factory element that the connection

will use.


Connection Factory


57/70


The connectionFactory section of the configuration file defines connectionFactory

information. This sample defines three connection factories, one for a SonicMQmessaging client connection, one for SonicMQ Bridge Administration, and one for

WebSphere MQ:

In this example, the connection factories are identical except for the type. The admin

connection must always be a TOPIC connection:

The WebSphere MQ connectionFactory element requires additional parameters:

Table 14 describes the attributes for defining a connectionFactory element.

Table 14. connectionFactory Element Attributes

Attributes Description

name Unique logical name of this connection factory instance.

type TOPIC or QUEUE.

class Reserved.


Table 14. connectionFactory Element Attributes


58/70


Table 15 describes the connectionFactoryparameterRefs

webspheremq bridge

Documents