IBM WebSphere MQ Plugin Manual

Preface

This document describes the functionality provided by the Websphere MQ plugin.

See the XL Deploy Reference Manual for background information on XL Deploy and deployment concepts.

Overview

The WMQ plugin is a XL Deploy plugin that adds the capability to manage MQ resources on Websphere MQ environment. It works out of the box for deploying/ undeploying local queues and alias queues on a queue manager and can easily be extended to support management of other possible resources on a Websphere MQ environment.

Features

• Resources
  • Local Queue
  • Alias Queue
• Control Taks
  • Start/Stop queue manager

Requirements

• XL Deploy requirements

  • XL Deploy: version 4.0.0+
  • Websphere MQ: 7.x
  • Other XL Deploy Plugins: None

• Infrastructural requirements

  • User credentials for accessing the Host running Websphere MQ, and should be having the rights to run WMQ commands.

Usage in Deployment Packages

The plugin works with the standard deployment package DAR format. Please see the Packaging Manual for more details about the DAR format and the ways to compose one.

The following is a sample deployit-manifest.xml file that can be used to create a WMQ specific deployment package. It contain declarations for a LocalQueue, and an AliasQueue.

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0" application="WebsphereMQApp">
  <orchestrator>default</orchestrator>
  <parallelByContainer>false</parallelByContainer>
  <deployables>
   <wmq.AliasQueueSpec name="testAliasQueue">
      <target>testTargetQueue</target>
      <cluster>QUEUE_CLUSTER</cluster>
    </wmq.AliasQueueSpec>
    <wmq.LocalQueueSpec name="testLocalQueue">
      <maxDepth>3</maxDepth>
      <boqname>testBackoutQueue</boqname>
      <bothresh>10</bothresh>
    </wmq.LocalQueueSpec>
  </deployables>
</udm.DeploymentPackage>

Using the deployables and deployeds

The following table describes which deployable/container combinations are possible.

Deployable vs. Container table

The following table describes the effect a deployed has on it's container

Deployed Actions Table

Queue manager

wmq.QueueManager is a container type which represents an existing queue manager running in the MQ environment, and the MQ resources like local queue or alias queue can be targeted to it. It has a containment relationship with Host, which means that it can only be created under a Host. Also, since a wmq.QueueManager is meant to represent an existing queue manager, the name of the CI should reflect the existing queue manager name. For example if the existing queue manager running in the MQ environment is called VENUS, the wmq.QueueManager CI should be called VENUS.

wmq.QueueManager also supports control tasks for starting and stopping the queue manager. Please refer to the CLI or GUI manual to know more on how to use control tasks.

Extension points

The WMQ plugin is designed to be extended through XL Deploy's Plugin API type system. Also, since the WMQ plugin is built on top of the generic-plugin, support for new types can be added using the generic plugin patterns. Refer to the Generic Plugin Manual for more details. Also, refer to the Customization Manual for an explanation of the type system.

The next section describes extensibility by examples:

Extending the WMQ Plugin

Making an existing property hidden/visible or changing the default value

The following synthetic.xml snippet shows how the maxDepth property can be made hidden with a default value set on it in the wmq.LocalQueue type:

<type-modification type="wmq.LocalQueue">
  <!-- make it hidden, and give a default value if all the local queues are always created with the maxDepth value of 3-->
  <property name="maxDepth" kind="integer" default="3" hidden="true"/>
</type-modification>

Adding a new property to a deployed/deployable

The following synthetic.xml snippet shows how a new property 'DEFPRTY'(for specifying the default priority) can be added to the wmq.LocalQueue type:

<type-modification type="wmq.LocalQueue">
    <!-- adding new property for setting the default priority-->
    <property name="defprty" kind="integer" default="3" label="default priority" 
    description="The default priority of messages put on the queue. The value must be in the range zero 
    (the lowest priority) through to the MAXPRTY queue manager parameter. (MAXPRTY is 9.)"/>
</type-modification>    

Note that while adding a new property in the WMQ plugin, the property name should match exactly with the the WMQ command parameter name. Hence the property has been called defprty and not 'defaultProperty' or 'defPriority'. Also, a label can be specified for the property to give it a user-friendly name on the UI. In the example above, the property defprty will appear as default priority on the UI.

Adding a new type

New types can be added in WMQ plugin using the Generic Plugin patterns. For example, the following synthetic.xml snippet defines a new deployed type wmq.ModelQueue (and the corresponding deployable type wmq.ModelQueueSpec, which will be automatically generated from the deployed definition):

<type type="wmq.ModelQueue" extends="wmq.Resource" deployable-type="wmq.ModelQueueSpec" 
                                     container-type="wmq.QueueManager">
    <generate-deployable type="wmq.ModelQueueSpec" extends="generic.Resource"/>
    <property name="createScript" hidden="true" default="wmq/create-qmodel" />
    <property name="modifyScript" hidden="true" default="wmq/modify-qmodel" />
    <property name="destroyScript" hidden="true" default="wmq/destroy-qmodel" />
    <property name="maxDepth" kind="integer" description="The maximum number of messages allowed on the queue"/>
</type>

Once this new type has been added in the synthetic.xml, the new types wmq.ModelQueueSpec and wmq.ModelQueue is readily available to the XL Deploy type system. But to make it usable completely, the corresponding scripts must be added at the specified path. This is how the create script wmq/create-qmodel.sh might look:

#!/bin/sh
echo "DEFINE QMODEL(${deployed.name}) ${deployed.parameters}" 
       | ${deployed.container.executablesDirectory}/runmqsc ${deployed.container.name}

Similarly, below is an example destroy script wmq/destroy-qmodel.sh for the newly defined type:

#!/bin/sh
echo "DELETE QMODEL(${deployed.name})" | ${deployed.container.executablesDirectory}/runmqsc ${deployed.container.name}

On similar lines, the modify script can be specified containing the alter command for altering the model queue.

Release notes

Version 4.0.0

XL Deploy 4.0.0 compatibility.

Version 3.8.0

Updated to use plugin-api-3.8.0

Version 3.7.0

Upgraded to version 3.7.0 of the plugin-api