Dynamically update a Web service interface using WebSphere Message Broker Version 6

This article provides IBM® WebSphere® Message Broker Version 6 user-defined Java™ nodes for executing Ant scripts and writing files. The scenario in this article dynamically collects a WSDL document from an internet URL, extracts the XML schema section of the document, and having imported as a message set dictionary, deploys the definition to an active broker. Readers will also learn how to install the user-defined Java nodes and how to implement the broker in a Web services architecture.

Share:

Ben Thompson (bthomps@uk.ibm.com), Consulting IT Specialist, IBM Hursley

Author photoBen Thompson is a Consulting IT Specialist working on the WebSphere Message Broker development team at the IBM Hursley Software Lab in the UK. He is currently working on the design and implementation of .NET support in Message Broker. In the past, he has worked for IBM Software Services for WebSphere designing and implementing WebSphere solutions for IBM customers worldwide. You can contact Ben at bthomps@uk.ibm.com.


developerWorks Contributing author
        level

Andy Piper (andy.piper@uk.ibm.com), Senior IT Specialist, IBM

Andy PiperAndy Piper is a Senior IT Specialist with IBM Software Services for WebSphere in the United Kingdom. His role is to work with leading customers to provide consultancy on architecture, design and implementation. He was also part of the team that delivered the beta program for WebSphere Message Broker Version 6 and has developed and presented education on the new function. Andy is also a co-author of the IBM Redbook "Migration to WebSphere Message Broker Version 5," and a contributor to the SupportPac "IC04: WBIMB V5 Change Management and Naming Standards." You can reach Andy at andy.piper@uk.ibm.com or via his blog at The lost outpost.



22 February 2006

Also available in Chinese

Introduction

Often during the iterative development cycles of integration projects, a Web service provider will update the interface it supplies to its consumers by republishing the WSDL document describing the interface on the company's intranet or internet site. It's important for software vendors and integration specialists to be able to quickly adapt their deployed code to respond to these interface changes. Where wholesale functional code changes are not required (for example, where new message formats are being added, rather than existing formats being changed), the WebSphere Message Broker scenario presented in this article addresses this requirement using the following technologies:

  • ESQL to convert an HTTPRequest node to carry out an HTTPGet
  • ESQL to regulate versioning of a WSDL document
  • A stylesheet for use by the XML transform node, to extract a schema from a WSDL
  • A Java plug-in node to write the schema document to the file system
  • A Java plug-in node to run Ant build files
  • An Apache Ant build file that uses the Message Broker command line utilities for automated deployment (mqsicreatemsgdefs, mqsicreatebar and mqsideploy)

Outside of the main scenario, the plug-in nodes we've written will help developers get more value from Message Broker. One node writes files to the broker's local file system (for production uses, you should also consider implementing the Message Broker File Extender product). The second node executes Ant scripts. Ant is a Java and XML-based make tool developed by the Apache Foundation. By calling an Ant script, a message flow can cause a number of different processes to be carried out. For instance, with the right Ant extension tasks installed, an FTP transfer could be triggered, a log file could be written, or another operating system process could be executed. The Ant node thus extends the functionality of a broker deployment, and also presents some opportunities for simple automation.

The message flow shown in Figure 1 illustrates the stages involved in the end-to-end scenario provided in this article.

Figure 1. DynamicWSUpdate message flow
DynamicWSUpdate message flow

Install the FileUdn in the toolkit

  1. Unzip Scenario.zip, provided in the Download section of this article, to the root of your directory, such as C: on Windows™. All of the samples and scenarios are provided within a single directory, named Resources. The zip file contains the following:
    FileDescription
    Resources\UdnDevWorkspaceMessage Broker workspace for installation of user-defined Java nodes (including source code for the nodes)
    Resources\ScenarioWorkspace Message Broker workspace for Scenario (including Message Flow project)
    Resources\DynamicWSUpdate.xslXML stylesheet, for use by the XML transform node in Message Broker
    Resources\DynamicWSUpdate_AntBuild.xmlAnt build file for use by the Ant user-defined Java node in Message Broker
    Resources\Input.xmlInput file for use by the scenario
    Resources\FileUdnOutput\Output.xsdExample output file generated by a working scenario
    Resources\Logs\AntLog.logExample log file generated by the Ant user-defined Java node
    Resources\Logs\CreateMsgDefLog.logExample log file generated by the XML Schema Importer in Message Broker

    Note: If you choose to unzip the files to a different location, you may have to reconfigure the Ant build file and the message flow properties later.

  2. Start the Message Broker V6 toolkit. When prompted, select the workspace C:\Resources\UdnDevWorkspace. This workspace provides all the source files for the message flow nodes and Update Manager Site projects. This directory structure is used by the Eclipse Install/Update Manager to find features and plug-ins to install in a workbench.
  3. When the toolkit starts, select Software Updates => Find and Install from the Help menu.
  4. Select Search for new features to install, then click Next.
  5. Click New Local Site.
  6. Select the FileUdn Update Site project at C:\Resources\UdnDevWorkspace\com.ibm.issw.fileudn.site.
  7. Expand the Update Site project and select FileUdnFeature, then click Next.
  8. Check com.ibm.issw.fileudn.feature, then click Next.
  9. Accept the terms in the license agreements, then click Next.
  10. Choose the location where the features will be installed. In Available Sites, select C:\IBM\MessageBrokersToolkit\6.0\Eclipse.
  11. Click Finish.
  12. Close the Message Broker toolkit.

Install the AntUdn in the toolkit

  1. Start the Message Broker toolkit. When prompted, select the workspace C:\Resources\UdnDevWorkspace.
  2. When the toolkit starts, select Software Updates => Find and Install from the Help menu.
  3. Select Search for new features to install, then click Next.
  4. Click New Local Site.
  5. Select the AntUdn Update Site project at C:\Resources\UdnDevWorkspace\com.ibm.issw.antudn.site
  6. Expand the Update Site project and select AntUdnFeature, then click Next.
  7. Check com.ibm.issw.antudn.feature, then click Next.
  8. Accept the terms in the license agreements, then click Next.
  9. Choose the location where the features will be installed. In Available Sites, select C:\IBM\MessageBrokersToolkit\6.0\Eclipse.
  10. Click Finish.
  11. Close the Message Broker toolkit.

Install the FileUdn and AntUdn in the runtime broker

  1. Copy the files ComIbmIsswAntUdn.par and ComIbmIsswFileUdn.par into the directory C:\IBM\MQSI\6.0\jplugin, or the equivalent location of the jplugin directory on your broker machine.
  2. Restart the Message Broker.

Import the scenario

  1. Start the Message Broker toolkit. When prompted, select the workspace C:\Resources\ScenarioWorkspace. This workspace provides the message flow project for the scenario.
  2. When the toolkit starts, select Window => Open Perspective => Broker Administration Perspective.
  3. Open the message flow project named DynamicWSUpdate and explore the message flow.
  4. Deploy the broker archive file DynamicWSUpdate.bar to your runtime broker, and then close the toolkit before running messages through the message flow. The toolkit must be closed because the Ant Build File executes Message Broker command utilities that update the scenario workspace. The workspace contains a lock file that stops these headless commands from executing if the toolkit is open. This avoids Eclipse project metadata becoming corrupted.

Configure the scenario

If you've unzipped the Scenario.zip file to a directory other than the root of your C drive, you'll need to reconfigure some of the message flow node properties before deploying the flow to your broker. If you unzipped the file to the root, you may skip to step 5 below.

  1. On the XML transform node ExtractXSD, set the property Stylesheet Directory.
  2. On the FileUdn node, the property FileName is set to Output.xsd and the property DirectoryName is set to C:\Resources\FileUdnOutput. The latter of these values should match to the directory name in the target, createmsgdefs, in the Ant Build File DynamicWSUpdate_AntBuild.xml, which is used in the scenario.
  3. On the AntUdn node, set the property AntBuildFile to the location of the build file DynamicWSUpdate_AntBuild.xml. By default this is C:\Resources\DynamicWSUpdate_AntBuild.xml. Also on the AntUdn node, set the property AntLogFile to the location of the log file DynamicWSUpdate_AntBuild.xml. By default this is C:\Resources\Logs\AntLog.log.
  4. In the Ant Build file, DynamicWSUpdate_AntBuild.xml, the property named "base" is set to the broker toolkit's base installation path, C:\IBM\MessageBrokersToolkit\6.0\. If your broker is installed in a different location, change this setting.
  5. The last section of the Ant build file is concerned with automating the mqsideploy command. This command must be pointed at your domain connection file, so that the deploy operation can be successfully directed to your configuration manager. On import, the build file is expecting a project named Servers to contain the connection properties inside a file configdomain.configmgr. These parameters may have to be changed to match your Message Broker installation (Queue Manager name is set to QM1 and Listener port set to 1414). The build file is also set up to deploy to a broker named BK1 and its execution group named default. You may want to edit these settings.

Technical description of the scenario

This section provides a full description of the scenario:

Section 1: IN => Convert => HTTPRequest

The first three nodes in the message flow are concerned with contacting the internet URL where the WSDL document is published. The compute node, named Convert, consists of a single module whose purpose is to configure the LocalEnvironment tree in order to control the behavior of the following HTTPRequest node. The values are recognised by the HTTPRequest node, and cause it to send an HTTP GET to the internet URL rather than an HTTP POST, as it would in its standard mode of operation. So that changes to the LocalEnvironment are not lost after leaving the node, remember to alter the Compute Mode property of the compute node.

Listing 1. Convert node ESQL
BEGIN
	CALL CopyEntireMessage();
	SET OutputLocalEnvironment.Destination.HTTP.RequestLine.Method = 
	'GET';
	SET OutputLocalEnvironment.Destination.HTTP.RequestURL = 	
	InputRoot.XMLNS.URL;
	RETURN TRUE;
END;

The ESQL also sets the value of the RequestURL field to the value carried in the URL field of the input message. The test message supplied with this article provides a URL which currently provides an example available WSDL document available on the internet. Obviously, although correct at time of publishing, this addresses will be subject to change in the future.

Section 2: Standardize => ExtractXSD

WSDL documents provide a contract between a Web service consumer and a Web service provider. The information contained includes a full specification for the service's interface, location and bindings. Like all the best open standard strategies, this specification is designed to be independent of implementation. For this reason, an XML schema definition is used to specify the precise format of messages that will be exchanged in the Web service interaction. Message Broker provides support to wrap existing legacy systems with new Web service interfaces. In order to provide this function, the message broker requires details specifying metadata for each message that will be received, parsed and validated. The Message Repository Manager (MRM) domain is used in circumstances where validation support is required. In these situations, a message dictionary must be deployed to a broker installation to facilitate parsing.

This article describes a Message Broker solution that allows changes to an internet published WSDL interface to be dynamically extracted and then deployed to a Message Broker Web services client application. If the Web service provider changes the message formats used to communicate with its Web service requester, changes must be incorporated in the client code. In the case of Message Broker wrapper message flows, these changes require the redeployment of a message set dictionary. The first stage in this new deployment is the extraction of metadata from the online WSDL document. Listing 2 shows the basic anatomical structure of a WSDL document.

Listing 2. Anatomical structure of a WSDL document
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">  

	<wsdl:types>

		<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
			<xsd:complexType name=" ..." />
					...
		</xsd:schema>

	</wsdl:types>

	<wsdl:message ... >  ...  </wsdl:message>
	<wsdl:portType ... >  ...  </wsdl:portType>
	<wsdl:binding  ...  > ... </wsdl:binding>
	<wsdl:service  ...  >  ...  </wsdl:service>

</wsdl:definitions>

Section 2 of the message flow extracts the schema from the WSDL document that is passed as part of the logical tree from the HTTP node. Following the stated aims of reusability and promotion of open standards, we've chosen to execute this stage of the scenario using the Message Broker's XML transform node, which alters the logical tree using an XSLT stylesheet.

Before invoking the stylesheet transformation, the compute node Standardise slightly alters the captured WSDL document. This code is only necessary so that the scenario can be used with a wide array of publicly published WSDL documents. When using the stylesheet transform node, the stylesheet is sensitive to the layout of XML comments between elements in the WSDL. The ESQL removes comments from the WSDL document in the levels above the beginning of the XSD file that is being extracted. With tighter control over the precise syntax of the WSDL being provided to the flow, the scenario's complexity could be significantly reduced.

The stylesheet starts by matching the root element of the document that it is passed, using the regular expression /*. The XML element that is found is stored in the variable named wibble, and then its local name is compared to definitions and its namespace compared to http://schemas.xmlsoap.org/wsdl/. Note the use of XML entitities within the comparison, in order to escape the quotation characters. The child elements of definitions are then searched using a variable named wobble and compared with the expected child called types. If the bitstream found by the HTTP request has successfully located a valid and well-formed WSDL document, then types will contain a child element named Schema, which resides in the namespace http://www.w3.org/2001/XMLSchema. If the above checks result in a valid schema being found embedded in the WSDL at the correct level, the schema is copied to the output logical tree.

Listing 3. The XSLT stylesheet
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet	version="1.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
	<xsl:output method="xml" encoding="UTF-8"/>
		<xsl:template match="/*">       
	<xsl:variable name="wibble" select="."/>
	<xsl:if test="	local-name($wibble)="definitions" and
namespace-uri($wibble)="http://schemas.xmlsoap.org/wsdl/"">       
	<xsl:for-each select="./*">
	<xsl:variable name="wobble" select="."/>
	<xsl:if test="	local-name($wobble)="types" and
namespace-uri($wobble)="http://schemas.xmlsoap.org/wsdl/"">
	<xsl:for-each select="./*">
	<xsl:variable name="webble" select="."/>
	<xsl:if test="local-name($webble)="schema" and
namespace-uri($webble)="http://www.w3.org/2001/XMLSchema"">
	<xsl:copy-of select="."/>
	</xsl:if>
	</xsl:for-each>
	</xsl:if>
	</xsl:for-each>
		</xsl:if>	
		</xsl:template>           
</xsl:stylesheet>

Section 3: PrepareEnv => FileUdn

Section 3 takes the extracted schema file and writes it to the broker's local file system using a user-defined File output node. The Message Broker does not supply this form of output node among its primitive nodes (readers may be interested in finding out more about IBM's Message Broker File Extender product). The node, which is also supplied as a download with this article, has two basic mandatory properties: FileName and DirectoryName. These properties dictate the location where the data should be written in the file system. The buffered data that is written to the file includes the content of the child, named File, of the global environment section of the logical tree. The PrepareEnv compute node simply takes the Binary Large OBject (BLOB) message body that is output by the XML transform node and copies it to the Environment.File section of the tree. This extra step could easily have been contained within the Java code of the File node, but for the purpose of this article, we chose to code both the plug-in nodes in as generic a method as possible, in order to maximize their re-use outside of this particular scenario.

The message is forwarded unchanged to the output terminal of the PrepareEnv compute node. From this point on in the flow, the propagation of a message body from one node to the next does not actually supply any data for the nodes' operation, but simply acts as a trigger for the execution of the Ant build file.

Section 4: AntUdn => OUT

The final section of the scenario uses a user-defined Java node, coded to execute an Ant Build file. The Apache Ant framework provides a Java and XML based framework for automating common build tasks. The Ant plug-in is a generic piece of coding that successfully runs any Ant build file that conforms to the Ant 1.6.5 build level. The build file supplied with the scenario imports the XML schema document that was written to the file system by the preceding node, and creates a Message Broker message definition file inside a message set project. Having imported the schema, the build file then uses the two Message Broker command line utilities: mqsicreatebar and mqsideploy. mqsicreatebar generates a Broker Archive File that contains a compiled message set dictionary. mqsideploy deploys the archive.

Conclusion

The scenario took a WSDL document from a public internet page and updated the online broker's deployed message set dictionary, using Web technologies and open standards where available. The user-defined Java nodes supplied with this article provide significant value to message flow developers outside of the scenario.


Download

DescriptionNameSize
Code sampleScenario.zip  ( HTTP | FTP )8.7 MB

Resources

Learn

Get products and technologies

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, SOA and web services
ArticleID=104228
ArticleTitle=Dynamically update a Web service interface using WebSphere Message Broker Version 6
publish-date=02222006