An introduction to service mapping: Integrating evolving web services in WebSphere Application Server V8.5.5

SOAs and web services evolve over time — new versions of services are deployed or brand new services must be integrated with existing clients. Typically, development effort must be expended to ensure that web service clients continue to work with the web service providers. IBM® WebSphere® Application Server V8.5.5 and IBM Rational® Application Developer V9.0 introduce service mapping, a feature that enables you to remove the dependence of the service client on both the location and interface of the service provider via the interception, routing, and transformation of requests and responses between service clients and service providers. This article explains the concepts of service mapping and provides a working example, showing how multiple versions of a service provider can be called by the original service client via the development and use of service mapping technologies. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Andrew Borley (borley@uk.ibm.com), Software Engineer, IBM UK

Andrew Borley is an IT Specialist at IBM Hursley, UK. He has held various roles including developer, team leader, and project manager and has worked with various technologies in his 7 years at IBM. Since 2001 he has been working with customers on Service-Oriented Architecture projects, and his current role is developing the SCA for C++ implementation within the Apache Tuscany open source SOA project.



18 December 2013

Also available in Chinese

Introduction

There are many scenarios where evolutions and revolutions affect service-oriented architectures (SOAs) and the web services that they depend upon. For example, a new version of a service provider might be rolled out, providing extensions to existing functionality or new function entirely. When the new version is made available, it is likely that either the service clients that depend upon the service provider must be updated, or the original version of the service provider must continue to be supported. As a second example, an acquisition or re-organisation within a business might mean that existing service clients that want to make use of newly available service providers could find that the interfaces used by client and provider do not match up.

Service mapping helps with these scenarios by insulating applications that consume a service from the details of that service provider's interface or location. This is achieved by providing a simple way of performing content-based routing and message transformation that can be applied to web service messages being sent from service clients without needing to make changes to either the service client or service provider.

When a service client interacts with a service provider that might be at a different location or might have a different interface, there are several considerations that must be addressed:

  • Which service location should you route a message to?
  • Which operation on the service provider should be invoked when dealing with a request from a service consumer?
  • For any particular operation, how must each input, output, and fault message be transformed?

Prior to IBM WebSphere Application Server V8.5.5, a service client would send a message to a service provider only when it is configured with the endpoint address of the service provider and uses the same service specification. To send a request to a different service provider, the service client must be manually reconfigured with the new address. If the specification of the service provider is different, the service client will often need to be updated to adhere to the new specification.

In Figure 1, the service client is configured to interact with the service provider. If a new service provider were to be introduced, the service client must be manually reconfigured to send requests to the new service provider.

Figure 1. Static web service routing
Static web service routing

WebSphere Application Server V8.5.5 introduces service mapping, which enables the interactions between service client and service provider to be decoupled. The service mapping feature enables requests and responses to be intercepted, transformed, and routed to other service providers.

As shown in Figure 2, a service mapping consists of these two objects:

  • A service map, which defines how requests and responses are routed and transformed.
  • A local mapping service, which intercepts the requests and responses between service clients and service providers.
Figure 2. Service mapping with routing and transformation
Service mapping with routing and transformation

Service maps

A service map is a deployable artifact that contains the definitions needed to transform and route requests and responses between service clients and service providers. Service maps are developed using the service mapping editor in IBM Rational Application Developer V9.0 and depend upon the Web Service Definition Language (WSDL) documents that define the interfaces and endpoints of the original source web service provider and the new target web service providers. Transformation maps are created as part of the development of a service map to define how messages are transformed between the source service interface and the target service interfaces.

Once created, the service map and the files it depends upon are exported from Rational Application Developer in a service map library, which is an archive file with the suffix .slibzip. The service map library file is then deployed to the WebSphere Application Server runtime, where any service maps within the library can be installed and then attached to a local mapping service.


Local mapping services

The local mapping service intercepts requests and responses between service clients and service providers and is created and configured administratively in WebSphere Application Server. The local mapping service is defined with a service provider endpoint and, once configured, intercepts all invocations bound for that particular service provider, no matter which service client initiated the invocation. A local mapping service can have a service map attached to it, meaning that when a request is intercepted, the service map is applied to the message. In this case, the service map is used to select a service provider and transform the message to match the interface of the selected service provider. If a local mapping service does not have an associated service map, the original service provider is invoked.

Starting and stopping local mapping services

A local mapping service can be started and stopped, enabling calls to service providers to be administratively controlled. The default state for a local mapping service, when it is first created and is not attached to a service map, is in the started state. This means that a newly created local mapping service will permit any active web service clients to continue to send messages to their associated web service provider; the local mapping service will intercept these messages, but will not do anything with them. When a service map is attached to the local mapping service, the status of the local mapping service can change, depending on the status of the service map itself. Table 1 shows the possible states for local mapping services and how those states affect the behaviour of web service requests.

Table 1. Behaviour of web service requests when intercepted by a local mapping service
Local mapping service statusService map attached statusWeb service request behaviour
StartedNo service map attachedThe request continues to the original target service specified by the service client
StoppedNo service map attachedThe request fails and an error is returned to the service client
StartedService map attachedThe routing and transformation defined in the service map is applied to the request and any response
StoppedService map attachedThe request fails and an error is returned to the service client
UnknownService map attached, but the service map has not been saved to the master configurationThe request continues to the original target service specified by the service client

Event emission from local mapping services

A local mapping service enables you to emit events when service requests and responses are intercepted, enabling the monitoring of web service client calls made by applications in WebSphere Application Server. When a local mapping service is configured to emit events, the events are published to a JMS topic using a specified JMS provider and can contain details about the intercepted message. Subscribers to the JMS topic can use this event information to monitor the business status of their systems. As an example, the events can be sent to the IBM Integration Bus data capture store and viewed in the IBM Integration Bus web user interface.

To enable local mapping services to emit events, an event point must be administratively configured on the local mapping service. The event point determines the details to be included in the events, when an event will be emitted and to where events will be published.


A service versioning scenario

For example, suppose you have a business that provides vehicle management services. In particular, you provide a SOAP-based web service that supplies information about customers and their cars when provided with a customer ID. Various clients make use of the web service and, specifically, an application provides a simple web front end to the web service.

The files needed to reproduce this example are included in the Download section of this article.

A recent acquisition means that a new version of the web service has been developed that provides an updated version of the original service. Rather than re-developing the web front end client, you can use service mapping to reroute client calls to the new provider and transform the messages that are sent and received.

Prerequisites

To deploy the sample that is provided with this article, you will need:

  • IBM WebSphere Application Server V8.5.5 or later with the full profile installed (not the Liberty profile).
  • IBM Rational Application Developer V9.0 or later. When Rational Application Developer is installed, ensure the service mapping tools feature is enabled. You can also use IBM Installation Manager to modify your existing Rational Application Developer installation.

The instructions in this article are based on an Application server (non-federated) WebSphere Application Server profile. If you are using a profile with separate deployment manager and federated server, you might need to use different server names and port numbers than are provided in this exercise and will likely need to synchronize the nodes when using the Integrated Solutions Console.


Getting started

Let us look first at the original application. This provides the web front end (implemented using a Java™ servlet) which uses a web service client to call version 1 of the web service provider. When you install and start the DevWorksCars.ear enterprise application in your WebSphere Application Server instance (follow the instructions in the next section if you are unfamiliar with installing enterprise applications on WebSphere Application Server) and go to the application address http://localhost:9080/DevWorksCarsWeb/DevWorksCarsClient in your browser (your server name and port number might differ, depending on the settings of your WebSphere Application Server instance), you will see the web front end for the DevWorksCars application, which will look something like Figure 3.

Figure 3. Initial DevWorksCars application
Initial DevWorksCars application

The web service provider implementation contains a simple database of customers. If you type the value 1A into the Customer ID field and then click the Submit button, you should receive some data in response, which will look like Figure 4. The web front end also enables you to specify the endpoint address for version 1 of the web service provider in the Version1 Service URL field; this is the address used by the web service client to call to version 1 of the web service provider. You might need to update the server name and port number in the address, depending on your WebSphere Application Server instance.

Figure 4. Customer and service information retrieved from version 1 of the web service provider
Customer and service information retrieved from version 1 of the web service provider

The Service information picture is additional data to tell you what’s going on with the service. In the initial case, it’s pretty simple: the web browser sends the customer ID and the service URL to the web front end, which uses that information in the web service client to call to version 1 of the web service provider, which returns data that is displayed back at the web browser.

Other customer IDs you can use with version 1 of the web service are: 1B and 1C. If you try any other customer ID you should see a Customer ID was not found fault message.


Installing the sample application

  1. Download all the files included with this article.
  2. Ensure your WebSphere Application Server instance is started.
  3. Go to the WebSphere Application Server Integrated Solutions Console by going to http://localhost:9060/ibm/console/login.do in your browser (server name and port number might differ, depending on your WebSphere Application Server instance). Log in if you have administrative security switched on.
  4. Expand Applications > New Application.> New Enterprise Application.
  5. Click the Choose File button and select the DevWorksCars.ear file (that you downloaded) from the file selection dialog. Click Open.
  6. Click Next.
  7. Click Next to select the fast path for application installation.
  8. Accept all the defaults on the next set of pages, clicking Next until you reach the summary page, then click Finish.
  9. The DevWorksCars application will be installed. Click Save to save the WebSphere Application Server master configuration.
  10. Expand Applications > Application Types > WebSphere enterprise applications. You should see DevWorksCars in the list of enterprise applications.
  11. Select the checkbox next to the DevWorksCars application and then click Start to launch the application.

The new version of the web service provider

In addition to version 1 of the web service provider, the DevWorksCars application also includes version 2 of the web service provider, which is similar but subtly different. The two services are described using WSDL documents. To import the DevWorksCars application into Rational Application Developer and inspect the two WSDL files:

  1. Start Rational Application Developer. If Rational Application Developer starts with the Welcome page, go to the Workbench.
  2. If the Java EE perspective is not open, open it by navigating to Window > Open Perspective > Other…, choose the Java EE perspective and click OK.
  3. Import the DevWorksCars application by selecting File > Import… to open the Import dialog. Select General > Existing Projects into Workspace and click Next.
  4. Choose Select archive file, click Browse... and select the DevWorksCarsSrc.zip file (that you downloaded) in the file selection dialog and click the Open button.
  5. Ensure both projects are selected in the Projects section of the Import dialog, and click Finish.
  6. You might need to go through the Workspace Migration dialog. Accept the default settings on each page of the dialog, clicking the Next button until you can click the Finish button.
  7. Open the two different WSDL files by expanding the DevWorksCarsWeb project, then the WebContent/WEB-INF/wsdl folder, and then double-click both the DevWorksCarsV1.wsdl file and the DevWorksCarsV2.wsdl file.

Version 1 of the DevWorksCars service should look like Figure 5, with a single getCarInfo operation and one input, one output, and one fault message.

Figure 5. The DevWorksCarsV1.wsdl file
The DevWorksCarsV1.wsdl file

If you hover over the arrow next to the InfoReturn type (highlighted in Figure 5), the type structure shows in a hover help window, as shown in Figure 6.

Figure 6. Version 1 of the InfoReturn type
Version 1 of the InfoReturn type

You can see that version 1 of the InfoReturn type has the namespace http://example.ibm.com/DevWorksCarsV1/ and contains separate CustomerInfo and CarInfo structures.

Version 2 of the DevWorksCars service looks like Figure 7, the single getCarInfo operation in version 1 has been updated to a getInfo operation in version 2, and version 2 has an extra fault message for when the car registration for a customer is missing.

Figure 7. The DevWorksCarsV2.wsdl file
The DevWorksCarsV2.wsdl file

If you hover over the arrow next to the InfoReturn type (highlighted in Figure 7), version 2 of the type structure shows in a hover help window, as shown in Figure 8.

Figure 8. Version 2 of the InfoReturn type
Version 2 of the InfoReturn type

You can see that version 2 of the InfoReturn type has the namespace http://example.ibm.com/DevWorksCarsV2/ and contains a different set of structures; in particular, the CustomerInfo structure now contains the CarInfo structure within it.

The two services are close, but do not match, meaning that SOAP messages sent and received by a client based on version 1 of the service provider cannot be understood by version 2 of the service provider. This means that the web front end of your DevWorksCars application would need to be rewritten to use a version 2 web service client to be able to call the version 2 web service provider.

A simpler way to make the version 2 web service provider work with the version 1 web service client is to use service mapping. The next sections show how to create a service map to map between the two versions, create a local mapping service to intercept the version 1 web service calls, and then install the service map and attach it to the local mapping service to reroute and transform version 1 messages to the version 2 web service provider.


Creating the service map

You will use Rational Application Developer to create a service map to define the mapping between the two service versions. To create a service map library, create the service map, and then create the message mappings for the request, response, and fault messages:

  1. In Rational Application Developer navigate to File > New > Other.... In the New dialog box expand Service Map and select Service Map Library. You might need to check the Show All Wizards checkbox to see the Service Map options. If you still don’t see the Service Map options, it could be that the service mapping tools feature is not installed in your instance of Rational Application Developer. If this is the case, use IBM Installation Manager to modify your Rational Application Developer installation.
  2. Click Next.
  3. Set the Service map library name to DevWorksCarsServiceMapLibrary, leave the location at the default setting, and click the Finish button. A new service map library is created.
  4. Right-click on the newly created service map library and select Service Map > Service Map, as shown in Figure 9.
    Figure 9. Creating a new service map within a service map library
    Creating a new service map within a service map library
  5. The New Service Map dialog will open. Set the Service map name field to DevWorksCarsRouteToV2.srvcmap as seen in Figure 10. Click the Next button.
    Figure 10. New Service Map dialog, first page
    New Service Map dialog, first page
  6. Click Browse... to select a source service WSDL file. This is the WSDL that describes the original (version 1) service that you want to intercept calls for. Open the nested directories to the DevWorksCarsWeb/WebContent/WEB-INF/wsdl directory and then select the DevWorksCarsV1.wsdl file. Click OK. The other fields are automatically filled in. If the source WSDL has more than one port type or binding, the port type and binding that you want to map can be selected in this dialog. The DevWorksCarsV1.wsdl file has only one port type and binding, so the completed dialog page will look like Figure 11. Click Next.
    Figure 11. Selecting the source service in the New Service Map dialog
    New Service Map dialog, first page
  7. Click Browse... to select a target service WSDL file. This is the WSDL that describes the new (version 2) service that you want to route calls to. Again, open the nested directories to the DevWorksCarsWeb/WebContent/WEB-INF/wsdl directory and this time select the DevWorksCarsV2.wsdl file. Click OK. The other fields are automatically filled in. Set the Service Name field to targetV2. If the server name and port number are incorrect in the Endpoint address field, check the Override defaulst endpoint address checkbox and alter the Endpoint address field to the URL of your version 2 service. A quick way to check if you have the correct URL is to go to that address in your web browser (for example, click on http://localhost:9080/DevWorksCarsWeb/DevWorksCarsV2); if there is a web service at that address, your browser should display the Hello! This is an Axis2 Web Service! message. The completed dialog page will look like Figure 12. Click the Finish button to create the service map file.
    Figure 12. Selecting the target service in the New Service Map dialog
    New Service Map dialog, first page
  8. The service map editor will open. You should see the source and targetV2 services and the single operation that each has: getCarInfo and getInfo respectively. To map between these two operations, hover over the getCarInfo operation and the mapping grab handle will appear. Click on the grab handle and drag the connection to the getInfo operation on the targetV2 service. A new Operation Map connection will be made, and the Operation Map section of the service map editor will show the two operations and their request, response, and fault messages, as well as initial Data Map connections between the request and response messages.
  9. Create Data Map connections between the fault messages for the two operations: hover over the getInfo fault1 message and the grab handle will appear. Click on the grab handle and drag the connection to the getCarInfo fault message. A new Data Map connection will be made. Repeat the process for the getInfo fault2 message, so that both fault1 and fault2 messages are mapped to the getCarInfo fault message, meaning that if version 2 of the service returns either the fault1 or fault2 messages, the version 1 web service client will receive a getCarInfo fault message. The service map editor should now look like Figure 13.
    Figure 13. The service map editor with a new operation mapping and message mappings for the request, response and all fault messages
    The service map editor with a new operation mapping and message mappings for the request, response and all fault messages
  10. Save the service map by selecting File > Save.
  11. Create a data map transformation for the request messages by right-clicking the Data Map connection between the getCarInfoRequest and getInfoRequest messages and selecting Show In > Properties View. The Properties view will open. Click the New… button in the Properties view and the New Data Map dialog will open. Accept the default name and location for the new data mapping file and click Finish.
  12. The data map editor will open. You should see the ServiceMapMessage on both the input and output sides of the data map editor. Expand the Body section of the input ServiceMapMessage and you will see the input request message element, which is getCarInfo. Expand getCarInfo and RequestInfo to show the CustomerId field in the input message. On the output side, expand Body, getInfo and RequestInfo to show the CustomerId field of the output message. Hover over either of the CustomerId fields and a grab handle will appear. Click on the grab handle and drag the connection to the other CustomerId field to create a Move connection. This will map from the getCarInfo request message (which has namespace http://example.ibm.com/DevWorksCarsV1/) to the getInfo request message (which has namespace http://example.ibm.com/DevWorksCarsV2/) and should look like Figure 14. If you wanted to map SOAP headers, HTTP transport headers, or use contextual information (such as the source and target operation names), you can access those via the other sections in the ServiceMapMessage structure. For this example, you don’t need to do that, so save the request data map file and close the data map editor.
    Figure 14. The completed data map editor for the request messages
    The completed data map editor for the request messages
  13. Create a data map for the response messages by following the same instructions in step 11 for the Data Map connection between the getCarInfoResponse and getInfoResponse messages in the service map editor.
  14. When the data map editor for the response message map opens, expand the Body sections of both the input and output ServiceMapMessages fully and follow the same instructions in step 12 to create Move connections between the following fields:
    • CustomerInfo > Id to CustomerInfo > Id
    • CustomerInfo > Name to CustomerInfo > Name
    • CustomerInfo > Car > Make to CarInfo > Make
    • CustomerInfo > Car > Model to CarInfo > Model
    • CustomerInfo > Car > EngineSize to CarInfo > EngineSize
    • CustomerInfo > Car > Colour to CarInfo > Colour
    • CustomerInfo > Car > Registration to CustomerInfo > CarRegistration
    • ServerInfo > ServerId to ServerInfo > ServerId
    • ServerInfo > Version to ServerInfo > Version

    The completed data map will look like Figure 15. Save the response data map file and close the data map editor.

    Figure 15. The completed data map editor for the response messages
    The completed data map editor for the response messages
  15. Repeat steps 11 and 12 to create a data map for the getInfo fault1 to getCarInfo fault message mapping in the service map editor. Create Move connections between the following fields:
    • CustomerNotFoundFault > CustomerId to CustomerNotFoundFault > CustomerId
    • CustomerNotFoundFault > ServerInfo > ServerId to CustomerNotFoundFault > ServerInfo > ServerId
    • CustomerNotFoundFault > ServerInfo > Version to CustomerNotFoundFault > ServerInfo > Version

    The completed data map will look like Figure 16. Save the fault data map file and close the data map editor.

    Figure 16. The completed data map editor for the first fault message mapping
    The completed data map editor for the first fault message mapping
  16. Repeat step 15 for the other fault message mapping between the getInfo fault2 and getCarInfo fault messages. Create Move connections between the following fields:
    • MissingCarRegistrationFault > customerId to CustomerNotFoundFault > CustomerId
    • MissingCarRegistrationFault > ServerInfo > ServerId to CustomerNotFoundFault > ServerInfo > ServerId
    • MissingCarRegistrationFault > ServerInfo > Version to CustomerNotFoundFault > ServerInfo > Version

    The completed data map will look like Figure 17. Save the fault data map file and close the data map editor.

    Figure 17. The completed data map editor for the second fault message mapping
    The completed data map editor for the second fault message mapping
  17. The service map file will have been updated with links to the four data maps you have created. Save the service map, which will now look like Figure 18 — and that’s it.
    Figure 18. The completed service map
    The completed service map

You have now successfully created your first service map and specified the operation-level and message-level mappings.

Next, to run the service map, you need to export the service map library and then create and attach a local mapping service to it.


Exporting the service map library

Service maps are exported within service map libraries, enabling multiple service maps to be exported and installed together. To export the service map you have just created from Rational Application Developer, follow these instructions:

  1. In the Enterprise Explorer view in Rational Application Developer, right-click on the DevWorksCarsServiceMapLibrary project and then select Service map > Export… The Export Service Map dialog will open.
  2. Select the DevWorksCarsRouteToV2.srvcmap file and ensure the checkbox next to it is selected. In the right panel you will see the list of files that the service map depends on, including the four data maps you created and the two WSDL files that you started with. Click the Browse... button to provide a file name and directory to save the service map library as, such as C:\developerworks\DevWorksCarsRouteToV2.slibzip (*.slibzip is the file extension for service map library files) and click Save. The completed dialog will look like Figure 19.
    Figure 19. The completed Export Service Map dialog
    The completed Export Service Map dialog
  3. Click Finish to export the service map and all the related files to your service map library file.

Installing the service map

You now have a service map ready for deployment. Return to WebSphere Application Server to install the service map:

  • Ensure your WebSphere Application Server instance is started.
  • Go to the WebSphere Application Server Integrated Solutions Console at http://localhost:9060/ibm/console/login.do (server name and port number might differ). Log in if you have administrative security switched on.
  • Expand Service integration > Service mapping and click Service maps. The (empty) list of installed service maps is displayed. Click the Install button.
  • Click the Choose File button and select the DevWorksCarsRouteToV2.slibzip service map library file (that you exported earlier) in the file selection dialog. Click Open.
  • Click Next to display step 1 of the Install service map wizard. Add a description to the service map such as Routes and transforms to version 2 of the DevWorksCars service. At this point, you have another opportunity to set the endpoint address used to send transformed messages to the new target service. If you need to, set the correct server name and port name (although you may already have done that when you created the service map in Rational Application Developer). The completed page will look like Figure 20. Click Next.
    Figure 20. Step 1 of the Install Service Map wizard
    Step 1 of the Install Service Map wizard
  • If you are working in a federated WebSphere Application Server environment, step 2 of the Install service map wizard gives you the opportunity to decide which servers or clusters into which the service map will be installed. If you are using an Application server (non-federated) profile, you will see just a single server in the list. Select the appropriate cluster or server and click Next.
  • Step 3 of the wizard shows a summary of the service maps you are installing and their details. Click Finish to install the service map.
  • Click Save to save the WebSphere Application Server master configuration. The installed service map will appear in the list of service maps, but is currently not attached to a local mapping service, and so will not (yet) be in use. Figure 21 shows the list of service maps.
    Figure 21. The list of service maps installed in WebSphere Application Server
    The list of service maps installed in WebSphere Application Server

Creating the local mapping service

Now that you have a service map installed, you need to set up the local mapping service. The local mapping service will intercept all requests sent to the version 1 web service provider made by the version 1 web service client. In fact, it will intercept any request being sent to the version 1 web service client from this WebSphere Application Server instance, meaning that if you had multiple client applications that called the version 1 web service provider, all of those calls would be intercepted, and, if a service map was attached to the local mapping service, all of those the calls would be routed and transformed according to the service map.

To create a local mapping service:

  1. Go to the WebSphere Application Server Integrated Solutions Console. Log in if you have administrative security switched on.
  2. Expand Service integration > Service mapping, and select Local mapping services. The list of local mapping services is displayed.
  3. Click on the New button. Step 1 of the New local mapping service wizard is shown. Set the Name field to DevWorksCarsV1LMS and the Description field to Intercepts calls for version 1 of the DevWorksCars service, as shown in Figure 22. Click Next.
    Figure 22. Step 1 of the “New local mapping service” wizard
    Step 1 of the “New local mapping service” wizard
  4. Step 2 of the wizard enables you to attach a service map at the same time as creating the local mapping service. Choose DevWorksCarsRouteToV2, the service map you just installed, from the dropdown list. Click Next.
  5. Step 3 of the wizard has been mostly prefilled for you based on the source service details from the service map you selected in the previous step. The only field you need to specify is Endpoint address, which should be set to the address used by the web service client to call to version 1 of the web service provider. This is the same address as used in the web front-end Version1 Service URL field, which by default is http://localhost:9080/DevWorksCarsWeb/DevWorksCarsV1, but might need the server name and port number updated. Figure 23 shows step 3 of the wizard with completed fields.
    Figure 23. Step 3 of the “New local mapping service” wizard
    Step 3 of the “New local mapping service” wizard

    The fields on this page determine the exact web service client requests that will be intercepted by this local mapping service; the calls must match the endpoint address, service name, port name, port type, and the namespace specified here. Web service client requests that are based on the WSDL of the version 1 web service provider will match these values.

  6. Step 4 of the wizard shows a summary of the local mapping service you are creating. Click Finish to create the local mapping service.
  7. The newly created local mapping service is shown in the list, but it will currently be in stopped state, because it is attached to a service map that is not yet started. When a service map is installed, a new business level application (BLA) is created for it, which must be started before the service map can be used. The state of an attached local mapping service reflects the state of the attached service map. Check the box next to the DevWorksCarsV1LMS local mapping service and click the Start button to start both the service map BLA and the local mapping service itself.
  8. Click Save to save the WebSphere Application Server master configuration. The new local mapping service will show in the list, and will show that it is both attached to a service map and started. Figure 24 shows the list of service maps.
    Figure 24. The list of local mapping services configured in WebSphere Application Server
    The list of local mapping services configured in WebSphere Application Server

Testing the service mapping

Now that you have created, exported, and installed a service map and attached it to a newly created local mapping service, you are ready to test it all.

Go back to the web front end for the DevWorksCars application in your browser at http://localhost:9080/DevWorksCarsWeb/DevWorksCarsClient (server name and port number might differ) and enter version 2 customer ID 2A in the Customer ID field. Ensure the Version1 Service URL field still contains the endpoint address of the version 1 web service provider. When you click the Submit button, you should see information about the customer from version 2 of the web service provider, as shown in Figure 25.

Figure 25. Customer and service information retrieved from version 2 of the web service provider via a service map
Customer and service information retrieved from version 2 of the web service provider via a service map

So, let us summarize what has happened here.

The web front end used the web service client based on version 1 of the service to send a request to version 1 of the service provider. That request was intercepted by the local mapping service and passed to the service map, where the request was transformed (using the data mapping you specified), and then routed to version 2 of the web service provider. Version 2 of the web service provider receives a standard version 2 message and returns a version 2 response message, which again is intercepted at the client by the local mapping service and transformed into a version 1 response message by the service map before being passed back to the web service client and the web front end.

You did not need to make any changes at all to the web service client or the client application. The version 1 web service client sends and receives version 1 messages and the version 2 web service provider receives and returns version 2 messages – the interception, transformation, and routing of the web service messages is completely transparent to the applications involved.

Other customer IDs you can use with version 2 of the web service are 2B, 2C, and 2D. Customer 2D exists, but does not have a car, so the version 2 MissingCarRegistrationFault is returned, which is transformed to a version 1 CustomerNotFoundFault message (containing the message from the MissingCarRegistration SOAP fault). If you try any other customer ID you should see the Customer ID was not found fault message which has been transformed from version 2 to version 1.

However, because you are now always routing to version 2 of the web service provider, you can no longer look up customers from version 1. If you try any of the customer IDs that worked before you added the service mapping (1A, 1B, 1C) you will get the Customer ID was not found message because the request was sent to version 2 of the service. To fix this, you need to go back to the service map editor in Rational Application Developer to define some content-based routing.


Updating the service map to route messages based on message contents

To enable messages to be routed to either version 1 or verson 2 of the web service providers you will use Rational Application developer to update the service map you created earlier. You can use a simple rule to determine whether the request should be routed to version 1 or 2 of the service – if the customer ID starts with the number 2 then it should be routed to version 2 of the web service provider. Follow these instructions to add an extra target service to the service map and set up the conditions to decide when a message should be routed to version 1 or version 2.

  1. In the Enterprise Explorer view in Rational Application Developer, expand the DevWorksCarsServiceMapLibrary project and double click on the DevWorksCarsRouteToV2.srvcmap file. The service map editor will open (if it isn’t still open from earlier).
  2. Add a new target service by clicking Add a target service. The Add service dialog will open.
  3. Click the Browse… button to select a target service WSDL file. This is the WSDL that describes the original (version 1) service that you also want to route calls to. Open the nested directories to the DevWorksCarsWeb/WebContent/WEB-INF/wsdl directory and then select the DevWorksCarsV1.wsdl file. Click OK. The other fields are automatically filled in. Set the Service Name field to targetV1. If the server name and port number are incorrect in the Endpoint address field, check the Override default endpoint address checkbox and alter the Endpoint address field to the URL of the version 1 service provider. The completed dialog page will look like Figure 26. Click OK to add the version 1 service as a second target service in the service map.
    Figure 26. Adding a new target service to the service map
    Adding a new target service to the service map
  4. You should see the source, targetV2, and targetV1 services in the service map editor. Add a mapping between the source getCarInfo operation and the targetV1 getCarInfo operation by hovering over the source service getCarInfo operation and clicking on the mapping grab handle that appears. Drag the connection to the getCarInfo operation on the targetV1 service. A confirmation message will ask you if it’s OK to convert the existing operation mapping to a conditional mapping. Click OK and a new Conditions mapping will be added to the service map and the Routing conditions dialog will display.
  5. In the Routing conditions table, click on the Name cell of the first condition (by default set as Condition) and rename it to RouteToV2. Click on the Name cell of the second condition, Condition0, and rename it to RouteToV1. With the second condition row still selected, click the Set As Default button to change the Order cell to *, meaning that if the first condition is not matched when a message is received by the service map, the seconad RouteToV1 condition will be used. Now click on the Expression cell of the first condition and click on the button that displays to launch the XPath Expression Builder.
  6. In the XPath Expression Builder, expand the $Body, getCarInfo, and RequestInfo structures to show the CustomerId field. Double click on the CustomerID field to add $Body/tns:getCarInfo/RequestIcnfo/CustomerId to the XPath Expression field. Now edit the XPath Expression field to create an XPath that will match when the value in the CustomerId field starts with the number 2. The easiest way to do this is to use the starts-with XPath function, so that the XPath Expression field contains:

    starts-with( $Body/tns:getCarInfo/RequestInfo/CustomerId , '2')

    Figure 27 shows the completed XPath Expression Builder dialog. Click Finish to set the condition XPath.

    Figure 27. Completed XPath Expression Builder dialog
    Completed XPath Expression Builder dialog
  7. Figure 28 shows the completed Routing conditions dialog. The order of routing conditions is important, as the first condition in the list that matches the message will provide the target service that the message is routed to, even if further conditions would also match. You can reorder conditions using the Up and Down buttons in the Routing conditions dialog. Click OK to set the conditions in the service map.
    Figure 28. Completed Routing conditions dialog
    Completed Routing conditions dialog
  8. You have now set up the service map with conditions to decide when to route to version 2 or version 1 of the service provider. If you click on the RouteToV1 condition in the service map editor, you will see that the service map is now ready to use, as the message mappings in the Operation Map section have already been created for you. As the source service and targetV1 service use the same WSDL, the request, response, and fault messages do not need to be altered, so you are provided with a set of Move connections to simply pass the unaltered message along. Figure 29 shows the message mappings set up for the RouteToV1 conditional operation map.
    Figure 29. Message mappings for the RouteToV1 conditional operation map
    Message mappings for the RouteToV1 conditional operation map
  9. You will make one extra update to enable your web front end to show you when a message has been mapped to version 1 of the web service provider. Click the down arrow next to the Move connection for the getCarInfoResponse message. When the Transform selector appears, click on the Data Map transform as highlighted in Figure 30.
    Figure 30. Selecting the Data Map transform for the getCarInfoResponse message
    Selecting the Data Map transform for the getCarInfoResponse message
  10. Now right-click on the Data Map connection between the getCarInfoResponse messages and select Show In > Properties View. The Properties view will open. Click the New… button and the New Data Map dialog will open. Accept the default name and location for the new data mapping file and click the Finish button.
  11. The data map editor will open. Follow the instructions used for creating Move connections in previous data maps to create Move connections between the following structures:
    • ReturnInfo > CustomerInfo to ReturnInfo > CustomerInfo
    • ReturnInfo > ServerInfo > ServerId to ReturnInfo > ServerInfo > ServerId
    • ReturnInfo > ServerInfo > Version to ReturnInfo > ServerInfo > Version
    • ReturnInfo > CarInfo to ReturnInfo > CarInfo

    Click the down arrow next to the Move connection between the two ServerId fields and change the transform to a fn:concat transform. The fn:concat transform is found by expanding the String Functions section of the Transform selector. This is an XPath 2.0 function that concatenates two or more values into a single string. In the Parameters table in the Properties view leave the string1 value as $ServerId and click on the Value cell for the string2 parameter to set it to the value 'MAPPED' (with the single quotes). Figure 31 shows the completed data map with the fn:concat transform selected. Save the response data map file and close the data map editor.

    Figure 31. The completed data map editor for the version 1 response message
    The completed data map editor for the version 1 response message
  12. Save the service map. The completed service map now looks like Figure 32.
    Figure 32. The completed service map with routing and transformation for version 1 messages
    The completed service map with routing and transformation for version 1 messages
  13. Export the service map library from Rational Application Developer by following the same instructions as used in the Exporting the service map library section earlier. You can use a different filename if you do not wish to overwrite the previously exported service map library.
  14. Now install the service map into WebSphere Application Server by following the same instructions as used in the Installing the service map section earlier. In Step 1 of the Install service map wizard, provide a new name for the updated service map by setting the Name field to DevWorksCarsRouteToV1AndV2 and the Description field to Routes and transforms to version1 and version 2 of the DevWorksCars service. If necessary, update the target service endpoint addresses with the correct server names and port numbers. When the service map has been installed and the WebSphere Application Server master configuration has been saved, you will have two service maps available, as shown in Figure 33.
    Figure 33. The list of service maps installed in WebSphere Application Server
    The list of service maps installed in WebSphere Application Server
  15. Currently the local mapping service is attached to the first service map, DevWorksCarsRouteToV2, but this is easily rectified. Click on the DevWorksCarsV1LMS link to take you to the details page for the local mapping service. In the Service Maps section, use the dropdown to switch the attached service map from DevWorksCarsRouteToV2 to the new service map, DevWorksCarsRouteToV1AndV2. Click OK and you will be taken to the list of local mapping services, where the DevWorksCarsV1LMS local mapping service is now attached to the DevWorksCarsRouteToV1AndV2 service map.
  16. Again, you will need to start the local mapping service, as the newly created service map BLA is not yet started. Check the box next to the DevWorksCarsV1LMS local mapping service and click the Start button to start both the service map BLA and the local mapping service itself. Click Save to save the WebSphere Application Server master configuration.
  17. Now that you have updated the local mapping service to use your updated service map, you can test it all out again. Go back to the web front end for the DevWorksCars application by pointing your web browser to http://localhost:9080/DevWorksCarsWeb/DevWorksCarsClient (server name and port number might differ) and enter a version 1 customer ID, 1A, in the Customer ID field. Ensure the Version1 Service URL field still contains the endpoint address of version 1 of the web service provider. When you cslick the Submit button, you should see information about the customer from version 1 of the web service with the Service information picture showing that a mapping has occurred, as shown in Figure 34.
    Figure 34. Customer and service information retrieved from version 1 of the web service provider via a service map
    Customer and service information retrieved from version 1 of the web service provider via a service map
  18. If you now try a version 2 customer ID, such as 2A, you will see that the service map also supports routing to version 2 of the web service provider. You should see the same results as you saw in Figure 25 earlier, but this time, the service map has inspected the customer ID in the request message, checked that it starts with the number 2, and then transformed and routed the request message to version 2 of the web service provider.

Troubleshooting

If you find your service mapping is not working correctly, carefully retrace your steps to ensure the service map, data maps, and the local mapping service have been correctly set up and attached to each other. Ensure the server name and port numbers are correct when specifying web service endpoint addresses and web browser URLs.

A completed service map library file, DevWorksCarsRouteToV2-Complete.slibzip, is included with the download materials, which includes both the DevWorksCarsRouteToV2 and the DevWorksCarsRouteToV1AndV2 service maps. This service map library can be imported into Rational Application Developer (if you want to inspect the service maps), or installed into WebSphere Application Server (if you want to run them).


Conclusion

When service-oriented architectures evolve, changes are often required to ensure updated and new service providers continue to work with service clients. Service mapping enables you to insulate applications that consume a service from the details of that service provider's interface or location via content-based routing and message transformation.

Service maps are developed in Rational Application Developer and installed on WebSphere Application Server, and contain the specification of the content-based routing conditions and the data map transformations.

Local mapping services are configured in WebSphere Application Server and silently intercept web service messages and, if attached, apply a service map to the request, response, and fault messages sent to and received from a web service provider. Local mapping services can also be configured to send events when a web service request, response, or fault is intercepted.

This article included an example that showed how different versions of a service provider can be called by the original service client via the development and use of a service map and a local mapping service.


Download

DescriptionNameSize
Sample code1312_borley_downloads.zip197 KB

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, Rational
ArticleID=957240
ArticleTitle=An introduction to service mapping: Integrating evolving web services in WebSphere Application Server V8.5.5
publish-date=12182013