IBM WebSphere Developer Technical Journal:Building an Enterprise Service Bus usingWebSphere ESB, Part 3Adding Web services and promoting properties

Skill Level: Intermediate

Rachel Reinitz (rreinitz@us.ibm.com)Senior Consulting IT SpecialistIBM

Andre Tost (atost@us.ibm.com)Senior Technical Staff MemberIBM

24 Jan 2006

After discussing key WebSphere ESB features and describing message exchangesacross JMS in the previous articles of our series, we will now further expand the set oftechnologies we are leveraging in IBM® WebSphere® ESB by adding a Web servicesscenario to the mix. Moreover, we will show two new features that were introducedwith the release of Version 6.0.2 of both WebSphere ESB and WebSphere IntegrationDeveloper.

From the IBM WebSphere Developer Technical Journal.

Introduction

Our scenario included a one-way message being sent to a back-end application viaJMS, indicating that a package had been delivered to the customer. We mapped thisinto a "one-way" operation of a service (meaning the operation has a request, but noresponse), and we gave it JMS bindings. Next, we will cover a synchronousinteraction between service requester and provider through a "request-response"

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 1 of 18

operation (meaning that there is a response for every request). Our service will useSOAP/HTTP bindings as its protocol. As in the previous case, we will route eachmessage through the Enterprise Service Bus, implemented by WebSphere ESBV6.0.2 to decouple the service requester and provider. The service requester andprovider are not aware the messages are flowing through the ESB and know nothingabout the routing or logging in the ESB.

You will also see how to configure the runtime to route messages to a differentendpoint address, and how to change which details of the message are logged, bothwithout redeploying the mediation. This configuration can be made directly in theadmin console of WebSphere ESB. This functionality is new in the 6.0.2 release ofthe product, which was released since Part 2 was published. We will use this newversion of the product for the remainder of this series beginning with this installment.

The scenario evolves

The business background for our scenario is the need for Posts-R-Us to enablecustomers and employees to retrieve the status of a package delivery. To make thisfunction as accessible as possible, with a variety of client platforms, it was decidedto offer a Web service that takes the tracking number of a package as its inputparameter and returns an XML document containing the status of the package,including the estimated (or actual) delivery date.

Each request to this new service is routed through the ESB, represented by aWebSphere ESB mediation module. The mediation module logs each request andeach response message, and routes the requests to one of two implementations ofthe actual service logic. To increase the flexibility of the overall system, twoimplementations of the service exist, with one serving as the backup. Note that inour example, we are not talking about a clustered environment with an applicationserver instance serving as the automatic backup system in case of a failure, butrather a second instance of the service, at a different endpoint address. We willshow you how to reconfigure the mediation module's import bindings to switch to thebackup service at runtime, using the WebSphere ESB administrative console.

As usual, the mediation flow component communicates with its clients and the actualservice provider via an export and import, respectively. Figure 1 shows what thearchitecture of the system looks like.

Figure 1. Architecture for the sample scenario

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 2 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

The service provider

Here and in later sections, we won't describe step-by-stepinstructions, but rather invite you to import the predefined EAR filesincluded in the download section. We will highlight the importantparts of each application as we build the entire sample scenario.

For our example, we need to implement a service provider that takes atrackingNumber variable as input and returns a packageStatus structure withinformation about the package.

1. For one of the later tests we will take you through in this article, you mustensure the test server is configured appropriately. Double-click on theWebSphere ESB Server v6.0 in the Servers view and make sure Runserver with resources on Server is selected (Figure 2). This must bedone before you start the server and before you deploy any of the EARapplication archives from this article to it.

Figure 2. Test server configuration

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 3 of 18

2. You can find the sample service provider in thePackageSatusServiceEAR.ear file, included with in the downloadmaterials with this article. Import this file into WebSphere IntegrationDeveloper V6.0.2 and select WebSphere ESB Server v6.0 for the Targetserver. You are just using the same WebSphere Application Serverinstance that WebSphere ESB is installed in to run the services; in anactual environment the services would most likely be running on aseparate server.

3. In the J2EE perspective, you will see a new Web project calledPackageStatusService. Note that it contains a WSDL file calledPackageTrackingService.wsdl with the service definition in it. If you openthis WSDL file in the Interface Editor of the tool, you can see that it has arequest-response operation defined, named getPackageStatus, as shownin Figure 3.

Figure 3. PackageTrackingService interface

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 4 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

4. Next, move on to the actual implementation class, calledPackageTrackingServiceSoapBindingImpl.java in the postsrus.servicepackage. If you open this class in the Java editor of the tool, you can seethat two tracking numbers are handled in our example, namely "123" and"456". All other numbers lead to an exception. We will use this knowledgelater when testing the scenario.

5. The other interesting class, located in the same package, isPackageStatus.java,,containing the data structure that is returned as aresult of a service operation invocation, which consists of four properties:

package postrus.service;

public class PackageStatus {private java.util.Calendar actualDeliveryDate;private java.lang.String location;private java.util.Calendar projectedDeliveryDate;private java.lang.String status;

public PackageStatus() {}

...}

Note how the time and date of delivery is represented by properties oftype java.util.Calendar. You will see later how that maps to an element oftype <xsd:dateTime> in our XML schema.

6. You can now briefly test this service to make sure it is deployed properlyand operational. For that, start the WebSphere ESB 6.0.2 test server inthe tool, then use the Add and remove projects... menu option to deploythe PackageStatusServiceEAR application to the server.

7. Once the application has been deployed and started, you will want to usethe WebSphere Integration Developer Web services testing tool. Enablethe Web services capability in WebSphere Integration Developer by

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 5 of 18

expanding Workbench => Capabilities under Preferences, and checkingWeb Service Developer. Now, right-click onPackageStatusService.wsdl and then select Web Services => Testwith Web Service Explorer, as shown in Figure 4.

Figure 4. Selecting the Web Services Explorer option

This will open the Web Service Explorer view, which enables you to testthe Web service, without actually generating a test client application.

8. Click on the getPackageStatus operation link, enter 123 as the trackingnumber, and then click Go. Port assignments on test servers vary, so ifyou get a connection error, selectPackageTrackingServiceSoapBinding in the Web Services Explorerand you can add another endpoint. Try setting the port to be 9081 or lookat your test server settings to determine the correct port. You should see

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 6 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

a printout in the server console indicating that the service was called, anda PackageStatus object is returned (Figure 5).

Figure 5. Web Services Explorer

9. Next, go ahead and import the PackageStatusServiceBackupEAR.ear fileinto WebSphere Integration Developer and select WebSphere ESB asthe target server . Change the endpoint port if needed. This projectcontains an identical set of Java classes and other artifacts, and also hasa Web service defined in it that has a getPackageStatus operation. Inother words, it is an exact copy of the service we just looked at; the onlydifference is that it is deployed under a different endpoint address andhas a different System.out statement specifying the "backup service" hasbeen called.

10. You can now add this project to the WebSphere ESB server and test itwith the Web Services Explorer. Make sure that this time, you right-clickthe WSDL file in the PackageStatusBackupService project. After runningthe test, you should see this line in the server console, indicating thatindeed the backup service was called:

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 7 of 18

[1/22/07 10:52:59:422 CST] 00000048 SystemOut O Package statusrequest in backup service for tracking number 456

The mediation module

Next, let's look at the mediation module that will go between the service provider wejust installed and any client that uses this service.

11. We stored the module as a Project Interchange file, calledPackageStatusModule.zip. After you have imported the file, switch to theBusiness Integration perspective in WebSphere Integration Developer. Inthe PackageStatusModule module, you should see thePackageStatusService file under Interfaces. This is the same WSDL filewe already used in the service provider. In other words, the mediationmodule will expose the same interface as the original service, so notransformation is required in the ESB. Under Data Types, notice thePackageStatus definition with the fields that are returned from the service.

12. Now, open the assembly diagram for the module in the Assembly editor.There is nothing too exciting about this assembly; it shows the mediationflow component, an export and an import (Figure 6).

Figure 6. Assembly diagram

13. Select the PackageStatusServiceImport and look at the associatedproperties view. In the Binding tab, you can see that it points to theendpoint address of the service implementation that you deployed earlier.Note that the port number is set to 9082. If your test server uses portnumber 9081, you can update it right here in the properties view.Similarly, if you select the PackageStatusExport, you will notice that ishas a Web service binding on it, with a new endpoint address. Thisaddress is what you will use in the Web Services Explorer later when

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 8 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

testing the complete solution.

14. Double-click the PackageStatusMediation to open the Mediation Floweditor. Since you have built a mediation flow component before, there areno big surprises here: each request and response message is routedthrough a MessageLogger mediation primitive, so that it is logged in thedefault database.

Figure 7. Mediation flow component

You may remember that in the properties for the MessageLoggerprimitive, you can define an XPath statement that indicates which part ofthe message is actually getting logged. You can change this in theDetails tab of the Properties view. The default value of the Root propertyis "/body", meaning that the entire body of the message is logged. For ourexample, we have changed this property to"/body/getTrackingStatus/trackingNumber", meaning that only the actualnumber is logged.

Promoted properties

Here we will start using a feature that is new in Version 6.0.2 of WebSphere ESB,called promoted properties. In earlier releases, the only way to change a propertylike the Root property of the MessageLogger primitive was to load the module intoWebSphere Integration Developer, change the property, and redeploy the entiremodule to the server. With Version 6.0.2, properties that have been "promoted" canalso be changed via the admin console at runtime. There is a new PromotedProperties tab in the Properties view that lets you select which properties, specific tothe mediation primitive, you want to make changeable. Each mediation primitive hasa specific set of properties which can be promoted.

In our scenario, you want to promote the property that lets you define which part of amessage is logged. This way, you can adjust at run time how much of a message islogged, without ever having to redeploy the module. Assume, for example, that youhave a service with a rather large message payload. You might decide only to log asmall part of that message to save storage. Later on, you may want to run an

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 9 of 18

extended analysis of certain messages, for which you need the entire message load.This can now be done simply via the admin console.

15. Open the Properties view for the RequestMessageLogger primitive in themediation flow and select the Promoted Properties view (Figure 8).

Figure 8. Promoted properties

Notice how each promoted property is given an alias name. This way, ifthere are multiple properties in the same module with the same name,you can distinguish between them in the admin console. In this case, wecalled the property RequestMessageLogger.root. If you check themessage logger primitive in the response queue, you will notice that wepromoted the same property there, but with a different alias, namelyResponseMessageLogger.root. Promoted properties with the same aliasname will all share the same value.

Finishing the solution

You are now ready to deploy the mediation module and run a test.

16. Go ahead and add the PackageStatusModuleApp to your test server.Once the application has started, switch to the J2EE perspective, and findthe file namedPackageStatusExport_PackageTrackingServiceHttp_Service.wsdl in thePackageStatusModule project under Other Projects. This file wasgenerated as part of creating Web services bindings for the mediationmodule's export. Right click on the file and select Web services => Testwith Web Services Explorer.

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 10 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

17. Test the ESB service invocation with the tracking number 123. The resultshould be the same as before, just this time you should see moreprintouts in the server console because of the logger primitive that isbeing invoked. By default, the primitive logs messages in a Cloudscape®database. We will check it later to see what entries have been logged.

18. But first, open the admin console for the test server, by right-clicking on itin the Servers view and selecting Run administrative console. In theadmin console, navigate to the SCA Modules page, as shown in Figure 9.

Figure 9. SCA Modules page

19. Click on the PackageStatusModule module link. On the following page,click on Module Properties under Additional Properties, and on the nextpage notice how it shows the two properties we promoted earlier, andtheir values:

Figure 10. Module properties

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 11 of 18

20. Change the RequestMessageLogger.root property to "/body". Click OKand save your changes. Log out of and close the admin console window.

21. Now, run the same test as before in the Web Services Explorer. Thistime, though, use "456" as the tracking number. This will help youdistinguish between the logged messages.

22. Stop the server after you have run the test so that the lock on the loggerdatabase is released, enabling you to examine the logged messages. Usethe cview utility, which is located in the [WebSphere Integration Developerinstall directory]\runtimes\bi_v6\cloudscape\bin\embedded directory. Startthe utility, select the File => Open menu option, and find theEsbLogMedDB database located in the [WebSphere IntegrationDeveloper install directory]\pf\esb\databases directory. Open theMSGLOG table and examine its content using the Data tab. The windowshould look similar to Figure 11.

Figure 11. cview utility

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 12 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

Stopping the server to view the logged messages is only necessarybecause we are using Cloudscape as the database. An actualproduction environment would utilize a production-level database,such as DB2®, and so stopping the server would not be required.

Changing the endpoint address

Above, you deployed two actual service provider instances, one primaryPackageStatusService, and the additional service calledPackageStatusBackupService. There are many situations in which you want to beable to easily switch the endpoint of the service being called; one is as you movefrom a development environment to a test environment. So how do you routemessages to the backup service without changing the module in WebSphereIntegration Developer, which would require a redeploy? There are two methods, oneof which we will cover here.

1. You can dynamically route a message to a new endpoint address byinserting an additional primitive (that is, the MessageElementSetterprimitive) into the flow. This primitive can update the context header,causing the message to go to a different address than what it configuredin the bindings of the import. It can optionally combine this with a lookupin a registry, like WebSphere Registry and Repository (for which there isan additional new primitive in Version 6.0.2 of WebSphere ESB andWebSphere Integration Developer). The details of this method are beyondthe scope of this article, but you can find more information, together with adetailed scenario, in Dynamic routing improvements in WebSphereEnterprise Service Bus V6.0.2.

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 13 of 18

2. You can change the endpoint address of an SCA module in the server'sadmin console. If you stopped the server, restart it, then run theadministrative console, and open the SCA Modules page, just as before.Select the PackageStatusModule module and expand the Imports nodeunder Module components (Figure 12).

Figure 12. The Module components

Click on the Binding link open a page that lets you override the endpointURL that is used by this import. Change it to the endpoint URL of thebackup service, which ishttp://localhost:9082/PackageStatusServiceBackup/services/PackageTrackingService.As before, we assume that your test server is using port 9082. If that isnot the case, you will also need to update the URL to use the correct port.

Finally, click on OK and save your changes. After that, run the test again;you should see the printout for the backup service in the server console.

Conclusion

In this article, you started using Web services (SOAP/HTTP) for your serviceinteractions with WebSphere ESB. You deployed two identical Web services, underdifferent endpoint addresses, both returning status information for a package. Themediation flow component established between the service requester and theservice provider is straightforward and simply logs all messages that come across toa database.

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 14 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

You then learned how the support for promoted properties in WebSphere ESBV6.0.2 enables you to change properties for mediation primitives at runtime, via theadmin console. In this example, you changed the level of detail of a message that islogged.

Finally, you saw how you can use the admin console to change the endpointaddress used by an import with Web services bindings, which lets you rerouterequests from one service provider to another -- again without the need to reload themodule into the development tool and to redeploy it.

More in this series

• Part 1: An introduction to using WebSphere ESB, or WebSphere ESB vs.SIBus

• Part 2: A JMS messaging example

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 15 of 18

Downloads

Description Name Size Download method

Code sample part3-downloads.zip52 KB FTP

Information about download methods

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 16 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.

Resources

• An introduction to the IBM Enterprise Service Bus

• WebSphere Enterprise Service Bus product page

• Getting started with WebSphere Enterprise Service Bus and WebSphereIntegration Developer

• Developing custom mediations for WebSphere Enterprise Service Bus

• Building a powerful, reliable SOA with JMS and WebSphere ESB

• WebSphere Enterprise Service Bus V6.0.2

• Tutorial: Invoking a Web service with a JMS client

• Service Component Architecture

• Redbook: Enabling SOA Using WebSphere Messaging

About the authors

Rachel ReinitzRachel Reinitz is a Senior Consulting IT Specialist with IBM Software Services forWebSphere focusing on Web services. Rachel consults with customers and ISVs onhow service oriented architecture and Web services can be used to achieve theirbusiness and technical objectives. She developed IBM's Advanced Web ServicesTraining course and is a frequent conference presenter. Rachel is also an IBMAcademy Member, and an experienced eXtreme Programming coach who has usedXP practices for 4 years. She lives in the Bay Area in California, and enjoys hiking,socializing, and international travel.

Andre TostAndre Tost works as a Senior Technical Staff Member in the Software Group'sEnterprise Integration Solutions organization, where he helps IBM's customersestablishing Service-Oriented Architectures. His special focus is on Web servicestechnology. Before his current assignment, he spent ten years in various partnerenablement, development and architecture roles in IBM software development, mostrecently for the WebSphere Business Development group. Originally from Germany,he now lives and works in Rochester, Minnesota. In his spare time, he likes to spend

ibm.com/developerWorks developerWorks®

Building an Enterprise Service Bus using WebSphere ESB, Part 3© Copyright IBM Corporation 1994, 2006. All rights reserved. Page 17 of 18

time with his family and play and watch soccer whenever possible.

developerWorks® ibm.com/developerWorks

Building an Enterprise Service Bus using WebSphere ESB, Part 3Page 18 of 18 © Copyright IBM Corporation 1994, 2006. All rights reserved.