The configuration of the WebSphere MQ bridge requires you to perform some actions on the WebSphere MQ queue manager, and some on the WebSphere MQ Everyplace queue manager. The bridge can be divided into two pieces:
Configuration of both types of routes are discussed in the following sections.
The bridge objects are defined in a hierarchy as shown in Figure 42
The following rules govern the relationship between the various objects:
Figure 42. Bridge object hierarchy
The bridge configuration option allows a WebSphere MQ Everyplace queue manager to communicate with WebSphere MQ host and distributed queue managers through client channels. The bridge component manages a pool of client channels that can be attached to one or more host or distributed queue managers. You can configure multiple bridge-enabled WebSphere MQ Everyplace queue managers in a single network.
A gateway may have a number of transmit queue listeners that use that gateway to connect to the WebSphere MQ queue manager and retrieve a messages from WebSphere MQ to WebSphere MQ Everyplace. A listener uses only one service to establish its connection, with each listener connecting to a single transmission queue on the WebSphere MQ queue manager. Each listener moves messages from a single WebSphere MQ transmission queue to anywhere on the WebSphere MQ Everyplace network, via its parent gateway queue manager. Thus, a single gateway queue manager can funnel multiple WebSphere MQ message sources into the WebSphere MQ Everyplace network.
When moving messages in the other direction, from WebSphere MQ Everyplace to WebSphere MQ, the gateway queue manager configures one or more bridge queues. Each bridge queue can connect to any queue manager directly and send its messages to the target queue. In this way a gateway can dispatch WebSphere MQ Everyplace messages routed through a single WebSphere MQ Everyplace queue manager to any WebSphere MQ queue manager, either directly or indirectly.
The bridges resource is responsible for maintaining a list of bridge resources. The bridges resource is responsible for maintaining a list of bridge resources. It provides a single-resource which can be started and stopped, where starting and stopping a bridges resource can start and stop all the resources beneath it in the resource hierarchy. It is "owned" by the WebSphere MQ Everyplace queue manager. If the WebSphere MQ Everyplace queue manager is bridge-enabled, then a bridges resource is automatically created, and present. This resource has no persistent information associated with it. It has the following properties:
Property | Explanation |
---|---|
Bridgename | List of bridge names |
Run state | Status: running or stopped |
The bridges, and the other bridge resources can be started and stopped independently of the WebSphere MQ Everyplace queue manager. If such a bridge resource is started (or stopped) the action also applies to all of its children, that is all bridges, queue manager proxies, client connections, and transmission queue listeners.
More detail of these properties can be found in the WebSphere MQ Everyplace Java Programming Reference in the administration class com.ibm.mqe.mqbridge.MQeMQBridgesAdminMsg. The bridges resource supports the Inquire and InquireAll, start, and stop operations. Create, delete, and update are not appropriate actions to use with this resource. Examples of how to inquire, start, and stop a bridges resource can be found in the Java class examples.mqbridge.administration.programming.AdminHelperBridges
The bridge resource is responsible for holding a number of persistent
property values, and a list of WebSphere MQ queue manager proxy
resources. If started or stopped, it can act as a single point of
control to start and stop all the resources beneath it in the bridge
hierarchy. Each bridge object supports the full range of create,
inquire, inquire-all, update, start, stop, and delete operations.
Examples of these operations can be found in the Java class
examples.mqbridge.administration.programming.AdminHelperBridge.
The bridge resource has the following properties:
Property | Explanation |
---|---|
Class | Bridge class |
Default transformer | The default class, rule class, to be used to transform a message from WebSphere MQ Everyplace to WebSphere MQ, or vice versa, if no other transformer class has been associated with the destination queue |
Heartbeat interval | The basic timing unit to be used for performing actions against bridges |
Name | Name of the bridge |
Run state | Status: running or stopped |
Startup rule class | Rule class used when the bridge is started |
WebSphere MQ Queue Manager Proxy Children | List of all Queue Manager Proxies that are owned by this bridge |
More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeMQBridgeAdminMsg.
In simple cases a default transformer (rule) can be used to handle all message conversions. Additionally a transformer can be set on a per listener basis (for messages from WebSphere MQ to WebSphere MQ Everyplace) that overrides this default. For more specific control the transformation rules can be set on a target queue basis using bridge queue definitions on the WebSphere MQ Everyplace Java Programming Reference. This applies both to WebSphere MQ Everyplace and WebSphere MQ target queues.
The WebSphere MQ queue manager proxy holds the properties specific to a
single WebSphere MQ queue manager. The proxy properties are shown in
the following table:
Table 20. WebSphere MQ queue manager proxy properties
Property | Explanation |
---|---|
Class | WebSphere MQ queue manager proxy class |
WebSphere MQ host name | IP host name used to create connections to the WebSphere MQ queue manager via the Java client classes. If not specified then the WebSphere MQ queue manager is assumed to be on the same machine as the bridge and the Java bindings are used |
WebSphere MQ queue manager proxy name | The name of the WebSphere MQ queue manager |
Name of owning bridge | Name of the bridge that owns this WebSphere MQ queue manager proxy |
Run state | Status: running or stopped |
Startup rule class | Rule class used when the WebSphere MQ queue manager is started |
Client Connection Children | List of all the client connections that are owned by this proxy |
More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeMQQMgrProxyAdminMsg.
Each proxy object supports the full range of create, inquire, inquire-all, update, start, stop, and delete operations. Examples of these operations can be found in the Java class examples.mqbridge.administration.programming.AdminHelperMQQMgrProxy.
The client connection definition holds the detailed information required to
make a connection to a WebSphere MQ queue manager. The connection
properties are shown in the following table:
Table 21. Client connection service properties
Property | Explanation |
---|---|
Adapter class | Class to be used as the gateway adapter |
CCSID* | The integer WebSphere MQ CCSID value to be used |
Class | Bridge client connection service class |
Max connection idle time | The maximum time a connection is allowed to be idle before being terminated |
WebSphere MQ password* | Password for use by the Java client |
WebSphere MQ port* | IP port number used to create connections to the WebSphere MQ queue manager via the Java client classes. If not specified then the WebSphere MQ queue manager is assumed to be on the same machine as the bridge and the Java bindings are used |
WebSphere MQ receive exit class* | Used to match the receive exit used at the other end of the client channel; the exit has an associated string to allow data to be passed to the exit code |
WebSphere MQ security exit class* | Used to match the security exit used at the other end of the client channel; the exit has an associated string to allow data to be passed to the exit code |
WebSphere MQ send exit class* | Used to match the send exit used at the other end of the client channel; the exit has an associated string to allow data to be passed to the exit code |
WebSphere MQ user ID* | user ID for use by the Java client |
Client connection service name | Name of the server connection channel on the WebSphere MQ machine |
Name of owning queue manager proxy | The name of the owning queue manager proxy |
Startup rule class | Rule class used when the bridge client connection service is started |
Sync queue name | The name of the WebSphere MQ queue that is used by the bridge for synchronization purposes |
Sync queue purger rules class | The rules class to be used when a message is found on the synchronous queue |
Run state | Status: running or stopped |
Name of owning Bridge | The name of the bridge that owns this client connection |
MQ XmitQ Listener Children | List of all the listeners that use this client connection |
The adapter class is used to send messages from WebSphere MQ Everyplace to WebSphere MQ and the sync queue is used to keep track of the status of this process. Its contents are used in recovery situations to guarantee assured messaging; after a normal shutdown the queue is empty. It can be shared across multiple client connections and across multiple bridge definitions provided that the receive, send and security exits are the same. This queue can also be used to store state about messages moving from WebSphere MQ to WebSphere MQ Everyplace , depending upon the listener properties in use. The sync queue purger rules class is used when a message is found on the sync queue, indicating a failure of WebSphere MQ Everyplace to confirm a message.
The maximum connection idle time is used to control the pool of Java client connections maintained by the bridge client connection service to its WebSphere MQ system. When a WebSphere MQ connection becomes idle, through lack of use, a timer is started and the idle connection is discarded if the timer expires before the connection is reused. Creation of WebSphere MQ connections is an expensive operation and this process ensures that they are efficiently reused without consuming excessive resources. A value of zero indicates that a connection pool should not be used.
More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeClientConnectionAdminMsg.
Each client connection object supports the full range of create, inquire, inquire-all, update, start, stop,and delete operations. Examples of these operations can be found in the Java class examples.mqbridge.administration.programming.AdminHelperMQClientConnection.
The listener moves messages from WebSphere MQ to WebSphere MQ
Everyplace.
Property | Explanation |
---|---|
Class | Listener class |
Dead letter queue name | Queue used to hold messages from WebSphere MQ to WebSphere MQ Everyplace that cannot be delivered |
Listener state store adapter | Class name of the adapter used to store state information |
Listener name | Name of the WebSphere MQ XMIT queue supplying messages |
Owning client connection service name | Client connection service name |
Run state | Status: running or stopped |
Startup rule class | Rule class used when the listener is started |
Transformer class | Rule class used to determine the conversion of a WebSphere MQ message to WebSphere MQ Everyplace |
Undelivered message rule class | Rule class used to determine action when messages from WebSphere MQ to WebSphere MQ Everyplace cannot be delivered |
Seconds wait for message | An advanced option that can be used to control listener performance in exceptional circumstances |
More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeListenerAdminMsg.
Each transmit queue listener object supports the full range of create, inquire, inquire-all, update, start, stop, and delete operations. Examples of these operations can be found in the Java class
// type all on one line, no spacing examples.mqbridge.administration.programming. AdminHelperMQTransmitQueueListener
The undelivered message rule class determines what action is taken when a message from WebSphere MQ to WebSphere MQ Everyplace cannot be delivered. Typically it is placed in the dead letter queue of the WebSphere MQ system.
In order to provide assured delivery of messages, the listener class uses the listener state store adapter to store state information, either on the WebSphere MQ Everyplace system or in the sync queue of the WebSphere MQ system.
The transmission queue listener allows WebSphere MQ remote queues to refer to WebSphere MQ Everyplace local queues. You can also create WebSphere MQ Everyplace remote queues that refer to WebSphere MQ local queues. These WebSphere MQ Everyplace remote queue definitions are called WebSphere MQ bridge queues and they can be used to get, put and browse messages on a WebSphere MQ queue.
A WebSphere MQ bridge queue definition can contain the following
attributes.
Table 23. WebSphere MQ bridge queue properties
Property | Explanation |
---|---|
Alias names | Alternative names for the queue |
Authenticator | Must be null |
Class | Object class |
Client connection | Name of the client connection service to be used |
Compressor | Must be null |
Cryptor | Must be null |
Expiry | Passed to transformer |
Maximum message size | Passed to the rules class |
Mode | Must be synchronous |
MQ queue manager proxy | Name of the WebSphere MQ queue manager to which the message should first be sent |
WebSphere MQ bridge | Name of the bridge to convey the message to WebSphere MQ |
Name | Name by which the remote WebSphere MQ queue is known to WebSphere MQ Everyplace |
Owning queue manager | Queue manager owning the definition |
Priority | Priority to be used for messages, unless overridden by a message value |
Remote WebSphere MQ queue name | Name of the remote WebSphere MQ queue |
Rule | Rule class used for queue operations |
Queue manager target | WebSphere MQ queue manager owning the queue |
Transformer | Name of the transformer class that converts the message from WebSphere MQ Everyplace format to WebSphere MQ format |
Type | WebSphere MQ bridge queue |
More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeMQBridgeQueueAdminMsg.
Example code which manipulates a bridge queue can be found in the Java class examples.mqbridge.administration.programmingAdminHelperBridgeQueue.
WebSphere MQ bridge queues are synchronous only. Asynchronous applications must therefore use either a combination of WebSphere MQ Everyplace store-and-forward and home-server queues, or asynchronous remote queue definitions as an intermediate step when sending messages to WebSphere MQ bridge queues.
Applications make use of WebSphere MQ bridge queues like any other WebSphere MQ Everyplace remote queue, using the putMessage, browseMessages, and getMessage methods of the MQeQueueManager class. The queue name parameter in these calls is the name of the WebSphere MQ bridge queue, and the queue manager name parameter is the name of the WebSphere MQ queue manager. However, in order for this queue manager name to be accepted by the local WebSphere MQ Everyplace server, a connection definition with this WebSphere MQ queue manager name must exist with null for all the parameters, including the channel name.
Administration of the WebSphere MQ bridge is handled in the same way as the administration of a normal WebSphere MQ Everyplace queue manager, through the use of administration messages. New classes of messages are defined as appropriate to the queue.
To create an WebSphere MQ Everyplace network that can interoperates with a WebSphere MQ network, it is necessary to adopt the same limitations in naming convention for both systems. It is therefore important to understand the differences between valid queue names in both systems:
We strongly recommend that you do not use this character in the name of any WebSphere MQ queue or queue manager.
We strongly recommend that you do not define WebSphere MQ Everyplace queues or queue managers with names that contain more than 48 characters.
We strongly recommend that you do not defined any WebSphere MQ queue or queue manager with a name that starts or ends with a '.' character.
If you choose not to follow these guidelines, then you may experience problems when trying to address an WebSphere MQ Everyplace queue from a WebSphere MQ application.
To configure a very basic installation of the WebSphere MQ bridge you need to complete the following steps:
Define one or more Java server connections so that WebSphere MQ Everyplace can use the WebSphere MQ Classes for Java to talk to this queue manager. This involves the following steps:
The simplest way to start objects manually, is to send a start command to the relevant bridge object. This command should indicate that all the children of the bridge, and children's children should be started as well.
PCF messages are administration messages used by WebSphere MQ queue managers. Supportpac "MS0B: MQSeries Java classes for PCF" contains Java code, which supplies PCF message support. This code is available as a free download from the WebSphere MQ download site at http://www.ibm.com/software/ts/mqseries/txppacs.
If you download and install it, and put the com.ibm.mq.pcf.jar file on your classpath environment variable, you have access to Java classes, which can dynamically manipulate WebSphere MQ resources. When PCF messages are combined with WebSphere MQ Everyplace administration messages, complete programmatic configuration of bridge resources, and corresponding resources on a WebSphere MQ Everyplace queue manager are possible. Example code contained in the examples.mqbridge.administration.programming.AdminHelperMQ class, used in conjunction with the examples.mqbridge.administration.programming.MQAgent demonstrate how to do this. This example code has been added to the examples.awt.AwtMQeServer program, such that using the view -> "Connect local MQ default queue manager" menu item will:
This section describes an example configuration of 4 systems.
Figure 43. Configuration example
The four systems are:
The requirement for this example is that all machines are able to post a message to a queue on any of the other machines.
It is assumed that all machines are permanently connected to the network, except the MQeMoonQM machine, which is only occasionally connected.
For this example, it is assumed that there are local queues, to which messages can be put, on all the queue managers. These queues are called:
Applications on MQeMoonQM now have access to the MQeMoonQ (a local queue) in a synchronous manner, and the MQeEarthQ in an asynchronous manner.
Since the MQeMoonQM is not attached to the network for most of the time, use a store-and-forward queue on the MQeEarthQM to collect messages destined for the MQeMoonQM queue manager.
A (similarly named) home-server queue is needed on the MQeMoonQM queue manager. This queue pulls messages out of the store-and-forward queue and puts them to a queue on the MQeMoonQM queue manager.
Any messages arriving at MQeEarthQM that are destined for MQeMoonQM are stored temporarily in the store-and-forward queue TO.HANDHELDS. When MQeMoonQM next connects to the network, it's home-server queue TO.HANDHELDS gets any messages currently on the store-and-forward queue, and delivers them to the MQeMoonQM queue manager, for storage on local queues.
Applications on MQeEarthQM can now send messages to MQeMoonQ in an asynchronous manner.
The synchronous queue is needed for assured delivery.
Applications on MQeEarthQM can now send messages to the MQSaturnQ on MQSaturnQM.
Now applications on MQeEarthQM can send a message to MQJupiterQ on MQJupiterQM, through MQSaturnQM.
The connection indicates that any message bound for the MQSaturnQM queue manager should go through the MQeEarthQM queue manager.
Applications connected to MQeMoonQM can now issue messages to MQeMoonQ, MQeEarthQ, MQSaturnQ, and MQJupiterQ, even when the handheld PC is disconnected from the network.
Applications on MQSaturnQM can now send messages to MQeEarthQ using the MQeEarthQM queue manager alias . This routes each message onto the MQeEarth.XMITQ, where the WebSphere MQ Everyplace transmission queue listener MQeEarth.XMITQ gets them, and moves them onto the WebSphere MQ Everyplace network.
Applications on MQSaturnQM can now send messages to MQeMoonQ using the MQeMoonQM queue manager alias . This routes each message to the MQeEarth.XMITQ, where the WebSphere MQ Everyplace transmission queue listener MQeEarth.XMITQ gets them, and posts them onto the WebSphere MQ Everyplace network.
The store-and-forward queue TO.HANDHELDS collects the message, and when the MQeMoonQM next connects to the network, the home-server queue retrieves the message from the store-and-forward queue, and delivers the message to the MQeMoonQ.
Now any application connected to any of the queue managers can post a message to any of the queues MQeMoonQ, MQeEarthQ, MQSaturnQ or MQJupiterQ.
This section contains information on the tasks associated with the administration of the WebSphere MQ bridge
An example administration GUI is provided with the WebSphere MQ bridge. It is a subclass of the examples.administration.console.Admin example described in Example administration console.
The subclass is called examples.mqbridge.administration.console.AdminGateway.
WebSphere MQ bridge function cannot execute on a client queue manager, so using this class in conjunction with a client queue manager does not allow the administration of bridge objects on that client queue manager, but it does enable administration of a remote WebSphere MQ bridge-enabled server queue manager.
You can administer all the resources required to configure a bridge so that it can communicate with WebSphere MQ, without programming in Java, or using the Java examples supplied with WebSphere MQ Everyplace. For example, using the examples.awt.AwtMQeServer, open a queue manager and select View - > Admin menu item to bring up the administration GUI.
You can also use the examples.mqbridge.administration.commandline tools in conjunction with the the examples.administration.commandline package, to configure the WebSphere MQ bridge. The WebSphere MQ Everyplace Java Programming Reference describes how to use these tools. Use batch files to combine a sequence of these example configuration tools, as described in Example of use of command-line tools.
Each administered object has a run state. This can be 'running' or 'stopped' indicating whether the administered object is active or not.
When an administered object is 'stopped', it cannot be used, but its configuration parameters can be queried or updated.
If the WebSphere MQ bridge queue references a bridge administered object that is 'stopped', it is unable to convey a WebSphere MQ Everyplace message onto the WebSphere MQ network until the bridge, WebSphere MQ queue manager proxy, and client connection objects are all 'started'.
The run state of administered objects can be changed using the start and stop actions from the MQeMQBridgeAdminMsg, MQeMQQMgrProxyAdminMsg, MQeClientConnectionAdminMsg, or MQeListenerAdminMsg administration message classes.
The actions supported by the WebSphere MQ bridge administration objects are described in the following sections.
An administrator can send a start action to any of the administered objects.
The affect children boolean flag affects the results of this action. The start action starts the administered object and all its children (and children's children) if the affect children boolean field is in the message and is set to true. If the flag is not in the message or is set to false, only the administered object receiving the start action changes its run-state. For example, sending start to a bridge object with affect children as true causes all proxy, client connection, and listeners that are ancestors, to start. If affect children is not specified, only the bridge is started. An object cannot be started unless its parent object has already been started. Sending a start event to an administered object attempts to start all the objects higher in the hierarchy that are not already running.
An administered object can be stopped by sending it a stop action. The receiving administered object always makes sure all the objects below it in the hierarchy are stopped before it is stopped itself.
The inquire action queries values from an administered object.
If the administered object is running, the values returned on the inquire are those that are currently in use. The values returned from a stopped object reflect any recent changes to values made by an update action. Thus, a sequence of start, update, inquire, returns the values configured before the update, while start, update, stop, inquire, returns the values configured after the update.
You may find it less confusing if you stop any administered object before updating variable values.
The update action changes one or more values for characteristics for an administered object. The values set by an update action do not become current until the administered object is next stopped. (See Inquire action.)
The delete action permanently removes all current and persistent information about the administered object. The affect children boolean flag affects the outcome of this action. If the affect children flag is present and set to true the administered object receiving this action issues a stop action, and then a delete action to all the objects below it in the hierarchy, removing a whole piece of the hierarchy with one action. If the flag is not present, or it is set to false, the administered object deletes only itself, but this action cannot take place unless all the objects in the hierarchy below the current one have already been deleted.
The create action creates an administered object. The run state of the administered object created is initially set to stopped.
We recommend that before you stop a WebSphere MQ queue manager, you issue a stop administration message to all the WebSphere MQ queue-manager-proxy bridge objects. This stops the WebSphere MQ Everyplace network from trying to use the WebSphere MQ queue manager and possibly interfering with the shutdown of the WebSphere MQ queue manager. This can also be achieved by issuing a single stop administration message to the MQeBridges object.
If you choose not to stop the WebSphere MQ queue-manager-proxy bridge object before you shut the WebSphere MQ queue manager, the behavior of the WebSphere MQ shutdown and the WebSphere MQ bridge depends on the type of WebSphere MQ queue manager shutdown you choose, immediate shutdown or controlled shutdown.
Stopping a WebSphere MQ queue manager using immediate shutdown severs any connections that the WebSphere MQ bridge has to the WebSphere MQ queue manager (this applies to connections formed using the MQSeries Classes for Java in either the bindings or client mode). The WebSphere MQ system shuts down as normal.
This causes all the WebSphere MQ bridge transmission queue listeners to stop immediately, each one warning that it has shut down due to the WebSphere MQ queue manager stop.
Any WebSphere MQ bridge queues that are active retain a broken connection to the WebSphere MQ queue manager until:
When a WebSphere MQ bridge queue has no connection, the next operation on that queue causes a new connection to be obtained. If the WebSphere MQ queue manager is not available, the operation on the queue fails synchronously. If the WebSphere MQ queue manager has been restarted after the shutdown, and a queue operation, such as putMessage, acts on the bridge queue, then a new connection to the active WebSphere MQ queue manager is established, and the operation executes as expected.
Stopping a WebSphere MQ queue manager using the controlled shutdown does not sever any connections immediately, but waits until all connections are closed (this applies to connections formed using the MQSeries Classes for Java in either the bindings or client mode). Any active WebSphere MQ bridge transmission queue listeners notice that the WebSphere MQ system is quiesce, and stop with a relevant warning.
Any WebSphere MQ bridge queues that are active retain a connection to the WebSphere MQ queue manager until:
The bridge client-connection object maintains a pool of connections, that are awaiting use. If there is no bridge activity, the pool retains WebSphere MQ client channel connections until the connection idle time exceeds the idle time-out period (as specified on the client connection object configuration), at which point the channels in the pool are closed.
When the last client channel connection to the WebSphere MQ queue manager is closed, the WebSphere MQ controlled shutdown completes.
This section describes the characteristics of the different types of administered objects associated with the WebSphere MQ Everyplace WebSphere MQ bridge. Characteristics are object attributes that can be queried using an inquireAll() administration message. The results can be read and used by the application, or they can be sent in an update or create administration message to set the values of the characteristics. Some characteristics can also be set using the create and update administration messages. Each characteristic has a unique label associated with it and this label is used to set and get the characteristic value.
The following lists show the attributes that apply to each administered object. The label constants are defined in the header file published/MQe_MQBridge_Constants.h. If you include published/MQe_API.h in you installation, this file is included automaticallyclass com.ibm.mqe.mqbridge.MQeCharacteristicLabels.
The WebSphere MQ bridge transmission queue listener acts in a similar way to a WebSphere MQ channel, pulling messages from a WebSphere MQ transmission queue, and delivering them to the WebSphere MQ Everyplace network. It follows the WebSphere MQ Everyplace convention in that if a message cannot be delivered, an undelivered message rule is consulted to determine how the transmission queue listener should react. If the rule indicates the report options in the message header, and these indicate that the message should be put onto a dead-letter queue, the message is placed on the WebSphere MQ queue, on the sending queue manager.