Prior to WebSphere® Business Integration Message Broker V5 (hereafter called WebSphere Message Broker), every message set and every flow had to be deployed by itself by exporting them in the control center of the appropriate environment. WebSphere Message Broker changed this by introducing the deployment unit, the configurable broker archive (BAR) file. The BAR file is a unit of deployment that contains a number of message sets, flows and manifest that describe the deployment parameters. WebSphere Message Broker provides commands for deploying BAR files, but stops short in providing support for scripting (changing parameters) inside the BAR file manifest. The recommended approach to change the BAR file parameters is using an Eclipse-based tool, which requires manual changes of the parameters. Although this approach usually works, it is error-prone, especially as the number of parameters increases. This article describes a scripted deployment approach, based on a set of parameters you can download. The article starts by describing the content of the BAR file and then introduces the code that can modify the parameters.
The broker archive is an envelope for deploying or dynamically installing executable content to a WebSphere Message Broker domain. Broker archives are files in standard zip format with the extension of "bar" that you can manipulate using zip tools to add, remove, or modify their contents. The BAR file contains the deployment descriptor, compiled message flows, and message set definitions.
The deployment descriptor is an XML file stored in the META-INF/broker.xml file in a broker archive. The deployment descriptor specifies overrides for configurable properties in all message flow files contained in a given BAR archive. The deployment descriptor provides simple, text-editor friendly access to these configurable properties and their values. The deployment parameters are specified as name/value pairs, where names are defined in the form of the universal resource identifier (URI), specifying the parameter's locations in the message flows. The deployment descriptor adheres to the deployment descriptor schema as shown in Figure 1.
Figure 1. Deployment descriptor schema
<?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.
The URI attribute specifies the broker-schema qualified flow name,
the node name (if needed), and the property name. URI is required.
The override attribute 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 = (schemaName.)flowName#(nodeName.)propertyName,
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, such as 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>
|
Based on the content of the BAR file and content descriptor presented, the following overall architecture of the scripted deployment for WebSphere Message Broker is shown in Figure 2.
Figure 2. Overall application structure
As you can see in Figure 2, the BAR scripter application relies on the original BAR file and parameters file to produce the resulting BAR file. It first reads the configuration parameters to create an override table of the parameters values, keyed on the parameter's URIs. After this, the BAR scripter reads the original BAR file, and extracts the broker.xml file from it. For every configurable property entry in the original broker.xml, the value of the URI is extracted and checked against content of the override table. If the parameter with the given URI exists in the override table, then the parameter is assigned to the value from the table. Otherwise, the value from the original configuration file is used. The created URI/values pairs are stored in the new configuration file. Finally, the rest of the files from the original BAR file are copied to the resulting BAR file. Figure 3 shows the processing flow for the BAR scripter application.
Figure 3. BAR file processing algorithm
You can use the configuration parameters to configure the BAR file that are located in a separate configuration file. Figure 4 shows the sample configuration file.
Figure 4. Layout of the configuration parameters
broker.bar.0.flowName=mmsmscenario21 broker.bar.0.propertyName=additionalInstances broker.bar.0.overrideValue=2 broker.bar.1.schemaName= broker.bar.1.flowName=mmsmscenario21 broker.bar.1.nodeName=Mapping broker.bar.1.propertyName=dataSource broker.bar.1.overrideValue=abcd broker.bar.2.schemaName= broker.bar.2.flowName=mmsmscenario21 broker.bar.2.nodeName=insert Flow Parameters broker.bar.2.propertyName=environment broker.bar.2.overrideValue=local broker.bar.3.flowName=mmsmscenario21 broker.bar.3.nodeName=insert Flow Parameters broker.bar.3.propertyName=value broker.bar.3.overrideValue=<a><d>test1</d><c>test2</c></a> |
As you can see from Figure 4, every BAR file's configurable property is defined by a group of configuration parameters. Every group is identified by an index and contains up to five properties that correspond to the definition for the URI and override attributes as defined by the deployment descriptor schema (Figure 1):
broker.bar.(index).schemaName: An optional property defining the broker schema. If this property is omitted or defined as an empty string, the schema is not used for constructing the parameter's URI.broker.bar.(index).flowName: A required property defining the flow to which the parameter belongs. If this property is omitted, the rest of the parameter's file is ignored.broker.bar.(index).nodeName: An optional property defining the node to which the given parameter belongs. If this property is omitted or defined as an empty string, the schema is not used for constructing the parameter's URI.broker.bar.(index).propertyName: The required property defining the property name. If this property is omitted, the group of properties is ignored.broker.bar.(index).overrideValue: An optional property defining the parameter's value. If this property is omitted, then all properties for this index are ignored. If the property is defined, but the value is not supplied, then an empty string overrides the parameter's value.
Properties in the configuration parameter's file should have continuous index values, starting from 0. If one of the indexes is omitted, the higher indexes are not processed.
Figure 5 shows the class diagram of the BAR scripter application.
Figure 5. BAR scripter class diagram
The overall implementation consists of five classes:
- BarScripter: main class coordinating the overall execution.
- Override properties: container class for properties, defined as configuration parameters.
- ZipReader: class reading the original BAR file and creating the resulting one.
- DescriptorProcessor: class modifying the deployment descriptor.
- Errors: supporting class (error container for the XML parser).
Implementation details for each class are described below.
This class coordinates the overall execution. It reads command arguments that define the following:
- Fully qualified name of the original BAR file.
- Fully qualified name of the resulting BAR file.
- Fully qualified name of the configuration parameters file.
If the number of parameters is less then 3, the printUsage method is invoked and the application exits. Otherwise, the OverrideProperties and ZipReader classes are created. The process method for the ZipReader class, which is doing all the work, is invoked.
This class is responsible for parsing the configuration parameters files and holding override properties for the duration of the execution. It has two methods, the constructor and the GetParameter. The constructor method reads the configuration parameters file as properties and converts these properties into URI/value pairs as defined by the deployment descriptor schema (Figure 1). These pairs are stored in the internal hash map, which is keyed by the URI. The constructor method uses the normalize method to ensure that the override value strings do not contain symbols used by XML parser. The GetParameter method obtains the value of the override parameter based on the URI value. If the URI does not exist in the internal hash table, a null is returned.
Because the BAR file is basically a zip file, we are using the java.util.zip.* package to process it. The main method in this class is the process method (Figure 3) that opens the original BAR file and loops through its content. For every file contained in the BAR file, it obtains the file name and opens a stream for the file content. If the current file is a deployment descriptor, it is modified using the descriptor processor class, and then is written to the resulting BAR file. Otherwise, the file is copied directly to the output BAR file. Two additional methods on this class, writeByteEntry and writeStreamEntry, store a file represented as either a stream or a byte array to the resulting BAR file.
The deployment descriptor is an xml file that is defined by the schema (defined in Figure 1). The ProcessContent method of the DescriptorProcessor class (Figure 3) gets the stream for the descriptor file and uses the internal getDocument method to convert it into a DOM tree. It then traverses the original document tree by copying it to the output document tree. For every URI attribute found in the original document, the OverrideProperties is consulted for the override value. If the value is found, it is stored in the resulting document in place of the original value. Figure 6 shows the results of the execution written in the standard output. You can use this output as a log to verify the resulting parameters.
Figure 6. BAR scripter execution results
Converting bar file C:/IBM/WSAD/WBI/barProcessor/M220.BAR.bar Into bar file C:/IBM/WSAD/WBI/barProcessor/broker.bar Using property file C:/IBM/WSAD/WBI/barProcessor/brokerbar.properties Configured parameters are .... Flow: mmsmscenario21 uri: mmsmscenario21#additionalInstances value:2 uri: mmsmscenario21#commitCount value:null uri: mmsmscenario21#commitInterval value:null uri: mmsmscenario21#coordinatedTransaction value:null uri: mmsmscenario21#MQInput.queueName value:null uri: mmsmscenario21#Compute1.dataSource value:null uri: mmsmscenario21#MQOutput.replyToQ value:null uri: mmsmscenario21#WSDLTODestination.timeToLive value:null uri: mmsmscenario21#WSDLTODestination.startURL value:null uri: mmsmscenario21#CandleMonitor.activateNode value:null uri: mmsmscenario21#Mapping.dataSource value:abcd uri: mmsmscenario21#WSDLTODestination.nodeTraceSetting value:null uri: mmsmscenario21#Compute.dataSource value:null uri: mmsmscenario21#MQOutput.queueName value:null uri: mmsmscenario21#insert Flow Parameters.path value:blah/blah1 uri: mmsmscenario21#MQOutput.queueManagerName value:null uri: mmsmscenario21#Compute2.dataSource value:null uri: mmsmscenario21#MQInput.topicProperty value:null uri: mmsmscenario21#insert Flow Parameters.environment value:local uri: mmsmscenario21#insert Flow Parameters.nodeTraceSetting value:null uri: mmsmscenario21#insert Flow Parameters.value value:<a><d>test1</d><c>test2</c></a> uri: mmsmscenario21#JMSOutput2.queueName value:null uri: mmsmscenario21#MQOutput.replyToQMgr value:null |
The newly created descriptor document is then converted into ByteArrayOutputStream, which is returned to the ZipReader class.
The errors class is an implementation of the org.xml.sax.ErrorHandler interface. It is required to support the Xerces XML parser that is used by the DescriptorProcessor class to parse the original descriptor.
You can download the barscripter.zip file to obtain an Eclipse project. The file contains the code described in this article along with the sample properties file, the brokerbar.properties file, and several test BAR files (M220.BAR.bar, M660.bar, and xsltBar.bar).
The introduction of a new deployment structure, the BAR files in WebSphere Message Broker V5, allows you to package related artifacts of the WebSphere Message Broker implementations (message sets, flows, and so on). This new deployment structure, along with the ability to externalize parameters depending on the deployment environment, can significantly simplify the maintenance and promotion of the WebSphere Message Broker code. The BAR's scripting code allows you to automate and modify the BAR's parameters, reducing the amount of manual intervention and errors. Using the deployment scripts also ensures consistent and quality promotion operations.
The author thanks his colleagues at CNA, especially Alagiriswamy Venkiduswamy and James Bouquet, for their help in putting together the code for this article.
| Description | Name | Size | Download method |
|---|---|---|---|
| Sample WebSphere Message Broker BAR files | barscripter.zip | 33KB | FTP |HTTP |
Information about download methods
- Read a case study using WebSphere Message Broker V5 to automate the creation of a BAR file in
Deploying a complex flow to WebSphere Business Integration Message Broker
- Read about WebSphere Message Broker V5 in
WebSphere Business Integration Message Broker V5 Overview and Architecture (Redbook) .
- You can find documentation information at the
WebSphere Message Broker V5 library.
- You can find information about WebSphere Business Integration products at the
developerWorks WebSphere Business Integration zone.
Boris Lublinsky is an Enterprise Architect at CNA Insurance where he is involved in the design and implementation of CNA's integration strategy, building application frameworks and implementing Service-Oriented Architecture. Prior to this he was a Director of Technology at Inventa Technologies, where he was overseeing and actively participating in engagements in EAI and B2B integration implementations and the development of large-scale Web applications. He was also a Technical Architect at Platinum Technology and SSA, where he was involved in component-based systems development and design. Boris has over 20 years of experience in software engineering and technical architecture.
Comments (Undergoing maintenance)
Table of contents
Local resources
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
