Contents


WebSphere Message Broker deployment scripting using Ant

Comments

Prior to IBM® WebSphere® Message Broker V6.0.2, there was no supported way to modify the configurable properties within the broker.xml file using a command-line tool. Developers usually did this operation by using the Broker Archive Editor in the WebSphere Message Broker toolkit, or by manually unzipping the broker archive (BAR) file and manipulating broker.xml outside the Message Broker environment. In WebSphere Message Broker V6.0.2, a new command-line tool called mqsiapplybaroverride can help you modify the configurable properties in a BAR file. This article shows you how to use Ant, the popular open-source Java™-based build tool, to build and maintain BAR files from within WebSphere Message Broker V6.0.2. Ant is like a Java version of make. Ant scripts are written in XML, and as with make, Ant targets can depend on other targets.

BAR files

A BAR file enables you to deploy or dynamically install executable content to a WebSphere Message Broker domain or execution group. A BAR file is a standard ZIP file with the extension .bar instead of .zip. It is similar to the EAR files used for J2EE deployment packaging, which are ZIP files with the extension .ear instead of .zip. A BAR file contains a single deployment descriptor, known as broker.xml, along with compiled message flows, message set dictionaries, XML, XSLT, and JAR files used by the Java compute node or within ESQL code. The deployment descriptor is an XML file, which is stored in the META-INF/broker.xml directory within the BAR file. The META-INF/broker.xml file specifies overrides for the configurable properties in all of the message flows within a given BAR file. Figure 1 shows the XML Schema definition of broker.xml:

Figure 1. broker.xml XML schema definition
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Broker">
    <xsd:annotation>
      <xsd:documentation>
        The document element of the broker.xml file is always a Broker element.
        The structure of the broker.xml file may not be extended or modified by users.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="CompiledMessageFlow" minOccurs="0" maxOccurs="unbounded" />
      </xsd:sequence>
      <xsd:attribute name="name" type="xsd:string" />
    </xsd:complexType>
  </xsd:element>

  <xsd:element name="CompiledMessageFlow">
    <xsd:annotation>
      <xsd:documentation>
        A CompiledMessageFlow element defines all the property overrides
        for a single compiled msgflow ("CMF") file in the root folder of
        the bar archive.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element ref="ConfigurableProperty" minOccurs="0" maxOccurs="unbounded" />
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>

  <xsd:element name="ConfigurableProperty">
    <xsd:annotation>
      <xsd:documentation>
        A ConfigurableProperty optionally specifies a deploy-time
        value for a single configurable property.

        Attribute "uri" specifies the broker-schema qualified flow name,
        the node name (if needed),and the property name. Uri is required.

        Attribute "override" specifies the value to assign to the
        property during installation.

        Override is optional. If override is not set, the configurable
        property value at install defaults to the value in the flow.
        If override is set (even to ""), the value of the configurable
        property at install is set to the value of override.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:attribute ref="uri" use="required" />
      <xsd:attribute ref="override" use="optional" />
    </xsd:complexType>
  </xsd:element>

  <xsd:attribute name="uri" type="xsd:string">
    <xsd:annotation>
      <xsd:documentation>
  The following specifies the syntax for uri attribute values in the
  broker.xml ConfigurableProperty elements.

  URI
  >>--+-------------------+--flowName-- # --+---------------+--propertyName-->>
      +--schemaName-- . --+                 +--nodeName-- . --+

 where:
 * "schemaName" is the name of the Broker schema the msgflow was defined in,
                or nothing if the msgflow is defined in the unnamed schema.
                schemaName is a dot separated list of path segments.
 * "flowName"   is the name of the msgflow; i.e. the name of the file without
                the .msgflow or .msgnode extension.
 * "nodeName"   is the label of the node, if the property is defined on a node.
                The nodeName parameter is optional, and does not appear if the
                property is defined on a flow.
  * propertyName is the name of the property, or the label key if the node is
                a primitive node. The descriptor tab of the BAR editor displays
                the NL enabled name if the label key matches a NL enabled name,
                else it displays the key itself.
      </xsd:documentation>
    </xsd:annotation>
  </xsd:attribute>

  <xsd:attribute name="override" type="xsd:string">
    <xsd:annotation>
      <xsd:documentation>
  Override is an optional attribute. If the attribute is absent, the
  default value set in the msgflow tool will be applied at install time.
  If a value is provided for override, then that value will be applied
  at install time. If override="", then the value at install time is the
  empty string.
      </xsd:documentation>
    </xsd:annotation>
  </xsd:attribute>
</xsd:schema>

Creating BAR files using Ant

Ant is a powerful tool for automating build environments. Calling mqsicreatebar from within an Ant task is a common way to build a BAR file from message flow and message set source artifacts. The most common way to build a BAR file from source files is to use an Ant script to extract the source data from a repository, although you do not have to use this technique in order to use the mqsicreatebar command. Here is the syntax diagram for the mqsicreatebar command, which is also described in the WebSphere Message Broker Information Center:

Figure 2. Syntax diagram for mqsicreatebar command
>>-mqsicreatebar-- -data --WorkSpace-- -b --BarName------------->

>--+--------------+--+---------------------------+-------------->
   '- -cleanBuild-'  '- -version --VersionString-'

                 .-----------------------.
                 V                       |
>--+----------+----+-------------------+-+-- -o ---------------->
   '- -Esql21-'    '- -p --ProjectName-'

   .--------------.
   V              |
>------FilePath---+--------------------------------------------><

Parameters

-data WorkSpace
(Required) The path of the workspace in which your projects are created.
-b BarName
(Required) The name of the BAR file where the result is stored. The BAR file is replaced if it already exists and the META-INF/broker.xml file is created within the BAR file.
-cleanBuild
(Optional) Refreshes the projects in the workspace and then invokes a clean build before new items are added to the BAR file. Use the -cleanBuild parameter to refresh all the projects in the BAR file and invoke a clean build if amendments have been made to the BAR file resources using external tools.
-version VersionString
(Optional) Appends the _ (underscore) character and the value of VersionString to the names of the objects added to the BAR file, before the file extension. In Message Broker V6.0, runtime versioning was introduced and you should use that mechanism to version your source files and propagate them to the deployed execution group. For details, see WebSphere Message Broker Information Center.
-Esql21
(Optional) Compile ESQL for V2.1 brokers.
-p ProjectName(s)
(Optional) Projects containing files to include in the BAR file. You can specify multiple projects, which can include a message flow project, a message set project, or a message flow plug-in node project. If a project that you specify is not part of your workspace, the command links the project to the workspace so that the files in the project can be included in the BAR file. The command does not copy the files into your workspace directory. If a project that you specify is part of your workspace but is closed, the command opens and builds the project so that the files in the project can be included in the BAR file.
-o FilePath
(Required) The workspace relative path (including the project) of a msgflow or messageSet.mset file to add to the BAR file. You can add more than one deployable file to this command by using the following format: -o FilePath1 FilePath2 .... FilePath'n'.

Using -data with existing workspaces and new workspaces

The -data parameter for the mqsicreatebar command refers to a workspace directory, and its behavior varies depending on whether or not the workspace directory already exists.

If the workspace and .metadata directory already exist and already contain the Message Set and Message Flow projects, then the -p option is not necessary. However, you should always supply the -p option regardless of whether a workspace directory already exists. If it does exist, issue the -cleanBuild parameter if any of the files were changed outside the WebSphere Message Broker toolkit. The -cleanBuild option forces a refresh of all the projects within the given workspace. Then issue a -cleanBuild to synchronize the projects with the existing .metadata information.

If the workspace directory does not exist, the -p option is mandatory, so that the projects specified by it can be added to a newly created workspace. The -cleanBuild parameter is not necessary in this case, because when the projects are added to the new workspace, the -p option forces a clean build on them. Use the second option when -data references a workspace that does not exist when using Ant to build BAR files using mqsicreatebar, because the message flow and message set projects are usually extracted from a repository, and the source files would be out of sync with the workspace that would be used. This would require the "-cleanBuild" parameter and could give inconsistent results. You can call the mqsicreatebar command from any Ant task by supplying the correct parameters. Figure 3 below shows a sample Ant task that will build a given BAR file:

Figure 3. Sample Ant task calling mqsicreatebar command to build a BAR file
<?xml version="1.0"?>
<project name="project" default="run">
  <target name="run" description="">
    <property name="toolkit.home" value="C:\MessageBroker\602" />
    <property name="ant.bars.basedir" value="C:\Dev\messagebroker" />
    <property name="workspaces.dir" value="${ant.bars.basedir}\workspace" />
    <property name="bar.name" value="${ant.bars.basedir}\postcard.bar" />
    <antcall target="mqsicreatebar.buildbar" />
  </target>

  <!--
    Target to build the broker archive using mqsicreatebar
  -->
  <target name="mqsicreatebar.buildbar">
    <echo message="Building Broker Archive file: ${bar.name} " />
    <exec executable="${toolkit.home}\eclipse\mqsicreatebar.exe" spawn="false">
      <arg value="-data" />
      <arg value="${workspaces.dir}" />
      <arg value="-b" />
      <arg value="${bar.name}" />
      <arg value="-p" />
      <arg value="Postcard" />
      <arg value="PostcardFlow" />
      <arg value="-o" />
      <arg value="Postcard\Postcard\messageSet.mset" />
      <arg value="PostcardFlow\PostcardFlow.msgflow" />
    </exec>
    <echo message="Completed building Broker Archive file - ${bar.name} " />
  </target>
</project>

Modifying the BAR file deployment descriptor using Ant

Using the mqsiapplybaroverride command lets you replace configurable values in the BAR file deployment descriptor with new values that you specify in a properties file. You can use this command in conjunction with the mqsicreatebar command. Figure 4 below is the syntax diagram for the mqsiapplybaroverride command, which is also described in the WebSphere Message Broker Information Center.

Figure 4. Syntax diagram for mqsiapplybaroverride command
>>-mqsiapplybaroverride-- -b --BarFile-- -p --PropertiesFile---><

Parameters

-b BarFile
(Required) The path to the BAR file (absolute, or relative to the executable command), to which the override values apply.
-p PropertiesFile
(Required) The path to the properties file (absolute, or relative to the executable command) that contains override values.

The mqsiapplyoverride command can change a specific URI in the broker.xml file, or replace all instances of a specific override value within the BAR file broker.xml file.

Figure 5 below shows a broker.xml file within a given BAR file before the mqsiapplyoverride command is applied with the property values from Figure 6. Figure 7 then shows the new broker.xml file within a given BAR file with the updated values. The two configurable properties that are being changed are:

<ConfigurableProperty uri="PostcardFlow#additionalInstances" />
<ConfigurableProperty override="Q1" uri="PostcardFlow#MQInput.queueName" />
Figure 5. Sample broker.xml file within a BAR file before applying new override values
<?xml version="1.0" encoding="UTF-8" ?>
<Broker>
  <CompiledMessageFlow name="PostcardFlow">
    <ConfigurableProperty uri="PostcardFlow#additionalInstances" />
    <ConfigurableProperty uri="PostcardFlow#commitCount" />
    <ConfigurableProperty uri="PostcardFlow#commitInterval" />
    <ConfigurableProperty uri="PostcardFlow#coordinatedTransaction" />
    <ConfigurableProperty uri="PostcardFlow#MQInput.serializationToken" />
    <ConfigurableProperty uri="PostcardFlow#MQInput.topicProperty" />
    <ConfigurableProperty uri="PostcardFlow#Postcard.validateMaster" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.queueManagerName" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.replyToQMgr" />
    <ConfigurableProperty uri="PostcardFlow#Postcard.dataSource" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.replyToQ" />
    <ConfigurableProperty uri="PostcardFlow#MQInput.validateMaster" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.validateMaster" />
    <ConfigurableProperty override="Q1" uri="PostcardFlow#MQInput.queueName" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.queueName" />
  </CompiledMessageFlow>
</Broker>
Figure 6. Sample properties file to pass to the -p option in mqsiapplyoverride command
#If want to replace a specific URI override value within the broker.xml
#URI_<uri with # escaped with a backslash \>=<new override value>
URI_PostcardFlow\#additionalInstances=2

#Replace all places in broker.xml that have IQ as a override value with
<old override value>=<new override value>
Q1=TEST_QUEUE
Figure 7. Sample broker.xml file within a BAR file after applying new override values
<?xml version="1.0" encoding="UTF-8" ?>
<Broker>
  <CompiledMessageFlow name="PostcardFlow">
   <ConfigurableProperty override="2" uri="PostcardFlow#additionalInstances" />
    <ConfigurableProperty uri="PostcardFlow#commitCount" />
    <ConfigurableProperty uri="PostcardFlow#commitInterval" />
    <ConfigurableProperty uri="PostcardFlow#coordinatedTransaction" />
    <ConfigurableProperty uri="PostcardFlow#MQInput.serializationToken" />
    <ConfigurableProperty uri="PostcardFlow#MQInput.topicProperty" />
    <ConfigurableProperty uri="PostcardFlow#Postcard.validateMaster" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.queueManagerName" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.replyToQMgr" />
    <ConfigurableProperty uri="PostcardFlow#Postcard.dataSource" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.replyToQ" />
    <ConfigurableProperty uri="PostcardFlow#MQInput.validateMaster" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.validateMaster" />
   <ConfigurableProperty override="TEST_QUEUE" 
			uri="PostcardFlow#MQInput.queueName" />
    <ConfigurableProperty uri="PostcardFlow#MQOutput.queueName" />
  </CompiledMessageFlow>
</Broker>

You can call the mqsiapplybaroverride command from any Ant task by supplying the correct parameters. Figure 8 below shows a sample Ant task that will change the override values within a given BAR file:

Figure 8. Sample Ant task calling mqsiapplybaroverride command to modify a BAR file deployment descriptor
<?xml version="1.0"?>
<project name="project" default="run">
  <target name="run" description="">
    <property name="toolkit.home" value="C:\MessageBroker\602" />
    <property name="ant.bars.basedir" value="C:\Dev\messagebroker" />
    <property name="bar.name" value="${ant.bars.basedir}\postcard.bar" />
    <property name="bar.properties.name" 
			value="${ant.bars.basedir}\brokerxml.properties" />

    <antcall target="mqsiapplybaroverride.modifybar" />
  </target>

  <!--
    Target to build the broker archive using mqsiapplybaroverride
  -->
  <target name="mqsiapplybaroverride.modifybar">
    <echo message="Applying overrides in Broker Archive file - ${bar.name} " />
    <echo
      message="${toolkit.home}\eclipse\mqsiapplybaroverride.exe 
			  -b  ${bar.name} -p ${bar.properties.name}" />
    <exec executable="${toolkit.home}\eclipse\mqsiapplybaroverride.exe" spawn="false">
      <arg value="-b" />
      <arg value="${bar.name}" />
      <arg value="-p" />
      <arg value="${bar.properties.name}" />
    </exec>
    <echo message="Completed apply overrides in Broker Archive file - ${bar.name}" />
  </target>
</project>

Conclusion

This article has shown you how to use the Ant scripting language to automate the scripting process of building BAR files using WebSphere Message Broker V6.0.2 command-line tools, to reduce manual intervention and avoid common mistakes when building BAR files. Using Ant scripts to build BAR files provides a consistent and reliable way to modify deployment descriptors within them.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware, Open source
ArticleID=229135
ArticleTitle=WebSphere Message Broker deployment scripting using Ant
publish-date=06062007