Administration of the WebSphere MQ bridge

This section contains information on the tasks associated with the administration of the WebSphere MQ bridge

The example administration GUI application

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.command line tools in conjucntion with the the examples.administration.command line 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.

WebSphere MQ bridge administration actions

Run state

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.

Start action

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.

Stop action

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.

Inquire action

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.

Update action

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

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

Create action

The create action creates an administered object. The run state of the administered object created is initially set to stopped.

WebSphere MQ bridge considerations when shutting down a WebSphere MQ queue manager

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.

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

Controlled shutdown

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 quiescing, 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.

Administered objects and their characteristics

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.

Characteristics of bridges objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeMQBridgesAdminMsg.

Characteristics of bridge objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeMQBridgeAdminMsg.

Characteristics of WebSphere MQ queue manager proxy objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeMQQMgrProxyAdminMsg.

Characteristics of client connection objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeClientConnectionAdminMsg.

Characteristics of WebSphere MQ transmission queue listener objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeListenerAdminMsg.


© IBM Corporation 2002, 2003. All Rights Reserved