![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
From the IBM WebSphere Developer Technical Journal.
Our scenario included a one-way message being sent to a back-end application via JMS, indicating that a package had been delivered to the customer. We mapped this into a "one-way" operation of a service (meaning the operation has a request, but no response), and we gave it JMS bindings. Next, we will cover a synchronous interaction between service requester and provider through a "request-response" operation (meaning that there is a response for every request). Our service will use SOAP/HTTP bindings as its protocol. As in the previous case, we will route each message through the Enterprise Service Bus, implemented by WebSphere ESB V6.0.2 to decouple the service requester and provider. The service requester and provider are not aware the messages are flowing through the ESB and know nothing about the routing or logging in the ESB.
You will also see how to configure the runtime to route messages to a different endpoint address, and how to change which details of the message are logged, both without redeploying the mediation. This configuration can be made directly in the admin console of WebSphere ESB. This functionality is new in the 6.0.2 release of the product, which was released since Part 2 was published. We will use this new version of the product for the remainder of this series beginning with this installment.
The business background for our scenario is the need for Posts-R-Us to enable customers and employees to retrieve the status of a package delivery. To make this function as accessible as possible, with a variety of client platforms, it was decided to offer a Web service that takes the tracking number of a package as its input parameter 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 a WebSphere ESB mediation module. The mediation module logs each request and each response message, and routes the requests to one of two implementations of the actual service logic. To increase the flexibility of the overall system, two implementations of the service exist, with one serving as the backup. Note that in our example, we are not talking about a clustered environment with an application server instance serving as the automatic backup system in case of a failure, but rather a second instance of the service, at a different endpoint address. We will show you how to reconfigure the mediation module's import bindings to switch to the backup service at runtime, using the WebSphere ESB administrative console.
As usual, the mediation flow component communicates with its clients and the actual service provider via an export and import, respectively. Figure 1 shows what the architecture of the system looks like.
Figure 1. Architecture for the sample scenario
For our example, we need to implement a service provider that takes a trackingNumber variable as input and returns a packageStatus structure with information about the package.
-
For one of the later tests we will take you through in this article, you must ensure the test server is configured appropriately. Double-click on the WebSphere ESB Server v6.0 in the Servers view and make sure Run server with resources on Server is selected (Figure 2). This must be done before you start the server and before you deploy any of the EAR application archives from this article to it.
Figure 2. Test server configuration
-
You can find the sample service provider in the PackageSatusServiceEAR.ear file, included with in the download materials with this article. Import this file into WebSphere Integration Developer V6.0.2 and select WebSphere ESB Server v6.0 for the Target server. You are just using the same WebSphere Application Server instance that WebSphere ESB is installed in to run the services; in an actual environment the services would most likely be running on a separate server.
-
In the J2EE perspective, you will see a new Web project called PackageStatusService. Note that it contains a WSDL file called PackageTrackingService.wsdl with the service definition in it. If you open this WSDL file in the Interface Editor of the tool, you can see that it has a request-response operation defined, named getPackageStatus, as shown in Figure 3.
Figure 3. PackageTrackingService interface
-
Next, move on to the actual implementation class, called PackageTrackingServiceSoapBindingImpl.java in the postsrus.service package. If you open this class in the Java editor of the tool, you can see that two tracking numbers are handled in our example, namely "123" and "456". All other numbers lead to an exception. We will use this knowledge later when testing the scenario.
-
The other interesting class, located in the same package, is PackageStatus.java,,containing the data structure that is returned as a result 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 of type java.util.Calendar. You will see later how that maps to an element of type <xsd:dateTime> in our XML schema.
-
You can now briefly test this service to make sure it is deployed properly and operational. For that, start the WebSphere ESB 6.0.2 test server in the tool, then use the Add and remove projects... menu option to deploy the PackageStatusServiceEAR application to the server.
-
Once the application has been deployed and started, you will want to use the WebSphere Integration Developer Web services testing tool. Enable the Web services capability in WebSphere Integration Developer by expanding Workbench => Capabilities under Preferences, and checking Web Service Developer. Now, right-click on PackageStatusService.wsdl and then select Web Services => Test with 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 test the Web service, without actually generating a test client application.
-
Click on the getPackageStatus operation link, enter 123 as the tracking number, and then click Go. Port assignments on test servers vary, so if you get a connection error, select PackageTrackingServiceSoapBinding in the Web Services Explorer and you can add another endpoint. Try setting the port to be 9081 or look at your test server settings to determine the correct port. You should see a printout in the server console indicating that the service was called, and a PackageStatus object is returned (Figure 5).
Figure 5. Web Services Explorer
-
Next, go ahead and import the PackageStatusServiceBackupEAR.ear file into WebSphere Integration Developer and select WebSphere ESB as the target server . Change the endpoint port if needed. This project contains an identical set of Java classes and other artifacts, and also has a Web service defined in it that has a getPackageStatus operation. In other words, it is an exact copy of the service we just looked at; the only difference is that it is deployed under a different endpoint address and has a different System.out statement specifying the "backup service" has been called.
-
You can now add this project to the WebSphere ESB server and test it with the Web Services Explorer. Make sure that this time, you right-click the WSDL file in the PackageStatusBackupService project. After running the test, you should see this line in the server console, indicating that indeed the backup service was called:
[1/22/07 10:52:59:422 CST] 00000048 SystemOut O Package status request in backup service for tracking number 456
Next, let's look at the mediation module that will go between the service provider we just installed and any client that uses this service.
-
We stored the module as a Project Interchange file, called PackageStatusModule.zip. After you have imported the file, switch to the Business Integration perspective in WebSphere Integration Developer. In the PackageStatusModule module, you should see the PackageStatusService file under Interfaces. This is the same WSDL file we already used in the service provider. In other words, the mediation module will expose the same interface as the original service, so no transformation is required in the ESB. Under Data Types, notice the PackageStatus definition with the fields that are returned from the service.
-
Now, open the assembly diagram for the module in the Assembly editor. There is nothing too exciting about this assembly; it shows the mediation flow component, an export and an import (Figure 6).
Figure 6. Assembly diagram
-
Select the PackageStatusServiceImport and look at the associated properties view. In the Binding tab, you can see that it points to the endpoint address of the service implementation that you deployed earlier. Note that the port number is set to 9082. If your test server uses port number 9081, you can update it right here in the properties view. Similarly, if you select the PackageStatusExport, you will notice that is has a Web service binding on it, with a new endpoint address. This address is what you will use in the Web Services Explorer later when testing the complete solution.
-
Double-click the PackageStatusMediation to open the Mediation Flow editor. Since you have built a mediation flow component before, there are no big surprises here: each request and response message is routed through a MessageLogger mediation primitive, so that it is logged in the default database.
Figure 7. Mediation flow component
You may remember that in the properties for the MessageLogger primitive, you can define an XPath statement that indicates which part of the message is actually getting logged. You can change this in the Details tab of the Properties view. The default value of the Root property is "/body", meaning that the entire body of the message is logged. For our example, we have changed this property to "/body/getTrackingStatus/trackingNumber", meaning that only the actual number is logged.
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 property like the Root property of the MessageLogger primitive was to load the module into WebSphere Integration Developer, change the property, and redeploy the entire module to the server. With Version 6.0.2, properties that have been "promoted" can also be changed via the admin console at runtime. There is a new Promoted Properties tab in the Properties view that lets you select which properties, specific to the mediation primitive, you want to make changeable. Each mediation primitive has a specific set of properties which can be promoted.
In our scenario, you want to promote the property that lets you define which part of a message is logged. This way, you can adjust at run time how much of a message is logged, without ever having to redeploy the module. Assume, for example, that you have a service with a rather large message payload. You might decide only to log a small part of that message to save storage. Later on, you may want to run an extended analysis of certain messages, for which you need the entire message load. This can now be done simply via the admin console.
-
Open the Properties view for the RequestMessageLogger primitive in the mediation 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, if there are multiple properties in the same module with the same name, you can distinguish between them in the admin console. In this case, we called the property RequestMessageLogger.root. If you check the message logger primitive in the response queue, you will notice that we promoted the same property there, but with a different alias, namely ResponseMessageLogger.root. Promoted properties with the same alias name will all share the same value.
You are now ready to deploy the mediation module and run a test.
-
Go ahead and add the PackageStatusModuleApp to your test server. Once the application has started, switch to the J2EE perspective, and find the file named PackageStatusExport_PackageTrackingServiceHttp_Service.wsdl in the PackageStatusModule project under Other Projects. This file was generated as part of creating Web services bindings for the mediation module's export. Right click on the file and select Web services => Test with Web Services Explorer.
-
Test the ESB service invocation with the tracking number 123. The result should be the same as before, just this time you should see more printouts in the server console because of the logger primitive that is being invoked. By default, the primitive logs messages in a Cloudscape® database. We will check it later to see what entries have been logged.
-
But first, open the admin console for the test server, by right-clicking on it in the Servers view and selecting Run administrative console. In the admin console, navigate to the SCA Modules page, as shown in Figure 9.
Figure 9. SCA Modules page
-
Click on the PackageStatusModule module link. On the following page, click on Module Properties under Additional Properties, and on the next page notice how it shows the two properties we promoted earlier, and their values:
Figure 10. Module properties
-
Change the RequestMessageLogger.root property to "/body". Click OK and save your changes. Log out of and close the admin console window.
-
Now, run the same test as before in the Web Services Explorer. This time, though, use "456" as the tracking number. This will help you distinguish between the logged messages.
-
Stop the server after you have run the test so that the lock on the logger database is released, enabling you to examine the logged messages. Use the cview utility, which is located in the [WebSphere Integration Developer install directory]\runtimes\bi_v6\cloudscape\bin\embedded directory. Start the utility, select the File => Open menu option, and find the EsbLogMedDB database located in the [WebSphere Integration Developer install directory]\pf\esb\databases directory. Open the MSGLOG table and examine its content using the Data tab. The window should look similar to Figure 11.
Figure 11. cview utility
Above, you deployed two actual service provider instances, one primary PackageStatusService, and the additional service called PackageStatusBackupService. There are many situations in which you want to be able to easily switch the endpoint of the service being called; one is as you move from a development environment to a test environment. So how do you route messages to the backup service without changing the module in WebSphere Integration Developer, which would require a redeploy? There are two methods, one of which we will cover here.
-
You can dynamically route a message to a new endpoint address by inserting an additional primitive (that is, the MessageElementSetter primitive) into the flow. This primitive can update the context header, causing the message to go to a different address than what it configured in the bindings of the import. It can optionally combine this with a lookup in a registry, like WebSphere Registry and Repository (for which there is an additional new primitive in Version 6.0.2 of WebSphere ESB and WebSphere Integration Developer). The details of this method are beyond the scope of this article, but you can find more information, together with a detailed scenario, in Dynamic routing improvements in WebSphere Enterprise Service Bus V6.0.2.
-
You can change the endpoint address of an SCA module in the server's admin console. If you stopped the server, restart it, then run the administrative console, and open the SCA Modules page, just as before. Select the PackageStatusModule module and expand the Imports node under Module components (Figure 12).
Figure 12. The Module components
Click on the Binding link open a page that lets you override the endpoint URL that is used by this import. Change it to the endpoint URL of the backup service, which is http://localhost:9082/PackageStatusServiceBackup/services/PackageTrackingService. As before, we assume that your test server is using port 9082. If that is not 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.
In this article, you started using Web services (SOAP/HTTP) for your service interactions with WebSphere ESB. You deployed two identical Web services, under different endpoint addresses, both returning status information for a package. The mediation flow component established between the service requester and the service provider is straightforward and simply logs all messages that come across to a database.
You then learned how the support for promoted properties in WebSphere ESB V6.0.2 enables you to change properties for mediation primitives at runtime, via the admin console. In this example, you changed the level of detail of a message that is logged.
Finally, you saw how you can use the admin console to change the endpoint address used by an import with Web services bindings, which lets you reroute requests from one service provider to another -- again without the need to reload the module into the development tool and to redeploy it.
- Part 1: An introduction to using WebSphere ESB, or WebSphere ESB vs. SIBus
- Part 2: A JMS messaging example
| Description | Name | Size | Download method |
|---|---|---|---|
| Code sample | part3-downloads.zip | 52 KB | FTP |
Information about download methods
-
An introduction to the IBM Enterprise Service Bus
-
WebSphere Enterprise Service Bus product page
-
Getting started with WebSphere Enterprise Service Bus and WebSphere Integration 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
Rachel Reinitz is a Distinguished Engineer with IBM Software Services for WebSphere focusing on Web services. Rachel consults with customers and ISVs on how service oriented architecture and Web services can be used to achieve their business and technical objectives. She developed IBM's Advanced Web Services Training course and is a frequent conference presenter. Rachel is also an IBM Academy Member, and an experienced eXtreme Programming coach who has used XP practices for 4 years. She lives in the Bay Area in California, and enjoys hiking, socializing, and international travel.
Andre Tost works as a Senior Technical Staff Member in the Software Group's Enterprise Integration Solutions organization, where he helps IBM's customers establishing Service-Oriented Architectures. His special focus is on Web services technology. Before his current assignment, he spent ten years in various partner enablement, development and architecture roles in IBM software development, most recently 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 time with his family and play and watch soccer whenever possible.
Table of contents
Next steps from IBM
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
