Automating Websphere Message Broker build and deployment using Ant

This article shows you how to use Ant, the popular open-source, Java-based build tool from Apache, with WebSphere Message Broker to automate the build and deployment process.

Soumen Chatterjee (soumecha@in.ibm.com), SOA Architect, SOA Technology Assembly Center, IBM India, IBM

Photo of Soumen ChatterjeeSoumen Chatterjee is an SOA Architect at the IBM SOA Technology Assembly Center in India. He is the member of the IBM Asset Advisory Group and the Worldwide Estimation Community. He has worked on variety of SOA engagements has expertise in XXX. You can contact Soumen at soumecha@in.ibm.com.



20 February 2013

Also available in Chinese

Introduction

This article provides a step-by-step guide for creating IBM® WebSphere® Message Broker deployable packages from source code using Ant scripts. It also shows you how to create different build parameter files and deployable packages tailored for different target environments.

A broker archive (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. BAR files are similar to the EAR files used for J2EE deployment packages, which are ZIP files with the extension .ear instead of .zip. A BAR file contains a single deployment descriptor named 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 broker.xml deployment descriptor file is stored in the META-INF directory within the BAR file, and it specifies overrides for the configurable properties in all of the message flows within a given BAR file.

Creating BAR files manually or using the WebSphere Message Broker toolkit is not an ideal option in an enterprise environment. This article shows you how to create a BAR file from source code located in a source control directory, apply environment-specific parameters to the generated BAR files, and deploy them in a target environment.

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 to use the mqsicreatebar command. Here is the syntax for the mqsicreatebar command -- for more information, see mqsicreatebar command in the in the WebSphere Message Broker V7 information center.

mqsicreatebar -data <workspace> -b <barName> [-version id]  [-esql21]  
    [-p projectName [...]]     -o filePath1 [filePath2 [...]]

Parameters

-data <workspace>
(Required) Path of the workspace in which your projects are created.
-b barName
(Required) 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 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. Message Broker V6 or later includes runtime versioning, and you should use it to version your source files and propagate them to the deployed execution group.
-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 .... FilePathn

Sample Ant task 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\700" />
    <property name="ant.bars.basedir" value="C:\OutputDIR" />
    <property name="bar.name" value="${ant.bars.basedir}\TestFlow.bar" />
    <property name="workspace.dir" value="C:\workspaces\wmb" />
    <antcall target="build" />
  </target>
  <target name="build">
     <echo message="Building the Message Broker Project @ ${workspace.dir}" />
     <exec executable="${toolkit.home}\mqsicreatebar.exe" spawn="false">
        <arg value="-data" />
            <arg value="${workspace.dir}" />
        <arg value="-b" />
            <arg value="${bar.name}" />
        <!-- List all the message flow projects --> 
        <arg value="-p" />
            <arg value="TestProject" />

        <!-- List all the files to be included in the archive --> 
        <arg value="-o" />
            <arg value="TestProject\TestFlow.msgflow" />
            <arg value="TestProject_MSET\TestMessageSet\messageSet.mset" />
     </exec>
  </target>
</project>

Modifying the BAR file deployment descriptor using Ant

To modify the configurable properties within the broker.xml file, you can either use the Broker Archive Editor in the WebSphere Message Broker toolkit, or manually unzip the BAR file and manipulate broker.xml outside the Message Broker environment. The mqsiapplybaroverride command can help you modify the configurable properties in a BAR file. This article shows you how to use Ant to build and maintain BAR files from within WebSphere Message Broker. Ant is like a Java version of make, and as with make, Ant targets can depend on other targets.

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 mqsiapplybaroverride in conjunction with the mqsicreatebar command. Here is the syntax diagram for the mqsiapplybaroverride command -- for more information, see mqsiapplybaroverride command in the in the WebSphere Message Broker V7 information center.

>>-mqsiapplybaroverride-- -b --BarFile-- -p --PropertiesFile---><

Parameters

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

broker.xml file for this project

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. Here is an example of the current project -- broker.xml before applying the overrides:

<Broker>
<CompiledMessageFlow name="TestFlow">
<ConfigurableProperty uri="TestFlow#additionalInstances"/>
<ConfigurableProperty uri="TestFlow#commitCount"/>
<ConfigurableProperty uri="TestFlow#commitInterval"/>
<ConfigurableProperty uri="TestFlow#coordinatedTransaction"/>
<ConfigurableProperty uri="TestFlow#consumerPolicySet"/>
<ConfigurableProperty uri="TestFlow#providerPolicySet"/>
<ConfigurableProperty uri="TestFlow#consumerPolicySetBindings"/>
<ConfigurableProperty uri="TestFlow#providerPolicySetBindings"/>
<ConfigurableProperty uri="TestFlow#securityProfileName"/>
<ConfigurableProperty uri="TestFlow#monitoringProfile"/>
<ConfigurableProperty uri="TestFlow#Compute.dataSource"/>
<ConfigurableProperty uri="TestFlow#Compute.validateMaster"/>
<ConfigurableProperty uri="TestFlow#MQ Input.additionalInstances"/>
<ConfigurableProperty uri="TestFlow#MQ Input.componentLevel"/>
<ConfigurableProperty override="HOME.REQUEST.Q" uri="TestFlow#MQ Input.queueName"/>
<ConfigurableProperty uri="TestFlow#MQ Input.resetBrowseTimeout"/>
<ConfigurableProperty uri="TestFlow#MQ Input.securityProfileName"/>
<ConfigurableProperty uri="TestFlow#MQ Input.serializationToken"/>
<ConfigurableProperty uri="TestFlow#MQ Input.topicProperty"/>
<ConfigurableProperty uri="TestFlow#MQ Input.validateMaster"/>
<ConfigurableProperty override="DEVQM" uri="TestFlow#MQ Output.queueManagerName"/>
<ConfigurableProperty override="HOME.RESPONSE.Q" uri="TestFlow#MQ Output.queueName"/>
<ConfigurableProperty uri="TestFlow#MQ Output.replyToQ"/>
<ConfigurableProperty uri="TestFlow#MQ Output.replyToQMgr"/>
<ConfigurableProperty uri="TestFlow#MQ Output.securityProfileName"/>
<ConfigurableProperty uri="TestFlow#MQ Output.validateMaster"/>
</CompiledMessageFlow>
</Broker>

Now change the two parameters highlighted in bold above using the following properties file to pass to the -p option in mqsiapplyoverride command:

TestFlow#additionalInstances=2
DEVQM=TESTQM

To make this change, add the lines highlighted in bold in the Build.xml file as described above.

<?xml version="1.0"?>
<project name="project" default="run">
  <target name="run" description="">
    <property name="toolkit.home" value="C:\MessageBroker\700" />
    <property name="ant.bars.basedir" value="C:\OutputDIR" />
    <property name="bar.name" value="${ant.bars.basedir}\TestFlow.bar" />
    <property name="bar.properties.name" value=
        "${ant.bars.basedir}\brokerXML.properties" />
    <property name="workspace.dir" value="C:\workspaces\wmb" />

    <antcall target="build" />
    <antcall target="modifybar" />
  </target>

  <target name="build">
     <echo message="Building the Message Broker Project @ ${workspace.dir}" />
     <exec executable="${toolkit.home}\mqsicreatebar.exe" spawn="false">
        <arg value="-data" />
            <arg value="${workspace.dir}" />
        <arg value="-b" />
            <arg value="${bar.name}" />
        <!-- List all the message flow projects --> 
        <arg value="-p" />
            <arg value="TestProject" />

        <!-- List all the files to be included in the archive --> 
        <arg value="-o" />
            <arg value="TestProject\TestFlow.msgflow" />
            <arg value="TestProject_MSET\TestMessageSet\messageSet.mset" />
     </exec>
  </target>

  <!--
    Target to build the broker archive using mqsiapplybaroverride
  -->
  <target name="modifybar">
    <echo message="Applying overrides in Broker Archive file - ${bar.name} " />
    <echo
      message="${toolkit.home}\mqsiapplybaroverride.exe 
            -b  ${bar.name} -p ${bar.properties.name}" />
    <exec executable="${toolkit.home}\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 scripts with WebSphere Message Broker commands to automate the process of building BAR files. Using Ant saves time, reduces manual intervention, and helps you avoid common mistakes when building BAR files, and it provides a consistent and reliable way to modify deployment descriptors within them.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=858442
ArticleTitle=Automating Websphere Message Broker build and deployment using Ant
publish-date=02202013