Building SOA applications with reusable assets, Part 3: WS response template pattern

This series explores reusable assets, recipes and software patterns and how they can facilitate the development of SOA solutions. This third article demonstrates the WS response template pattern implementation. You can apply the WS response template pattern to a UML model of a service, to create a more flexible service. We examine this pattern in the context of the SOA Implement and Optimize Services Recipe and the accompanying reference example, which was covered in the first two articles in this series. Future articles will show how to apply other SOA patterns to the reference example to satisfy non-functional requirements.

He Lei (heleihl@cn.ibm.com), Staff Software Engineer, IBM Japan, Software Group

He Lei (Joyce) is a staff software engineer with IBM Enterprise Integration Design Center in Beijing, China. She received an M.S. degree in computer science from BeiHang University in 2003. Since joining IBM, Ms. He has worked on China Grid project for the Grid Computing Group and has worked on customer projects for EIS design center. She is currently working on IBM SOA tools.



Sun Ying Lin , Software Engineer, IBM Japan, Software Group

Sun Ying Lin (Neo)Sun Ying Lin (Neo) is a software engineer with IBM Enterprise Integration Design Center in Beijing, China. He received an M.S. degree in computer science from BeiHang University in 2005. Since joining IBM, Mr. Sun has worked on IBM SOA tools.



田 晨, Software Engineer, IBM Japan, Software Group

Author1 photoTian Chen (Simon) is a software engineer with IBM Enterprise Integration Design Center in Beijing, China. He received an M.S. degree in computer science from BeiHang University in 2004. Since joining IBM, Mr. Tian worked on IBM SOA tools.



Eoin Lane, Senior Solution Engineer, IBM Japan, Software Group

Dr. Eoin Lane, senior solution engineer, is the lead for harvesting and developing of application pattern from key IBM SOA engagements and driving those patterns through IBM pattern governance process to accelerate adoption. Eoin also specializes in Model Driven Development (MDD), asset based development and Reusable Asset Specification (RAS) to facilitate SOA development.



14 July 2006

Introduction

In the previous articles in this series, we introduced the SOA Implement and Optimize Services Recipe and discussed a reference example to show how the recipe can be applied. The reference example uses a model-driven development (MDD) approach and leverages the modeling capabilities of IBM Rational® Software Architect to develop a use case model, analysis model, design models and services models. This article demonstrates how to modify an existing service, a key step in the SOA Implement and Optimize Services Recipe.

Typically a legacy application already exists that provides the core functionality. To modify an existing service, this application must be surfaced as a service, and this service often has to adhere to set of non-functional requirements that differ from the requirements for the original application.

We use the SOA Implement and Optimize Services Recipe with a reference example to show how software patterns can satisfy these new non-functional requirements. Using software patterns to satisfy non-functional requirements helps the developer and architect build an architecturally consistent service that complies with software development best practices and principles.

Modify an existing service

From the inventory use case analysis that we considered in the second part of this series, an existing legacy catalog application provides a Java™ interface to access catalog information. Now we must expose the legacy application as a service. In our recipe this is an example of a four-step process of reusing an existing service or application:

  1. Review the service model
  2. Review the nonfunctional requirement for the service
  3. Review the legacy application analysis/design model
  4. Apply the appropriate patterns, based on the nonfunctional requirements

The SOA Implement and Optimize Services Recipe provides the reference example for each of these steps.

  • A service model for the catalog service and related message representations is available as a Rational Software Architect asset and can be imported into an Rational Software Architect UML model project.
  • A Rational RequisitePro requirement management file, for the non-functional requirements for the inventory use case, is available as a Reusable Asset Specification (RAS) asset. However, this requirement file should be available across a network for shared access. Figure 3 shows the Rational RequisitePro Requirement Explorer inside Rational Software Architect after opening this Rational RequisitePro requirements management file for the Reference example.
  • A design model for legacy catalog; this is the catalog design model is available as a RAS asset and can be imported into a Rational Software Architect UML model project.

Review the service model

Catalog service model

Figure 1 shows the catalog service model. The model has two operations:

  • The getCatalog() operation takes a primary key and returns Catalog
  • The getCatalogs() operation takes an array of primary keys and returns an array of catalogs
Figure 1. Catalog service UML model
Catalog Service UML Model

Catalog message model

Figure 2 shows the catalog message model. The following is self evident from this model:

  • Each Catalog message contains multiple CatalogItem messages
  • Each CatalogItem message contains multiple FeatureValue messages
  • Each FeatureValue message contains one Feature messages
Figure 2. Catalog message UML model
Catalog message UML model
Figure 3. Rational RequisitePro Requirements Explorer in Rational Software Architect
Requisite Pro Requirements Explorer in Rational Software Architect

Review of non-functional requirements

The catalog service model file was examined in detail in the second part of this series.

Rational RequisitePro tracks the non-functional requirements for that catalog model. Rational Software Architect provides a Rational RequisitePro Client what shows the mapping between the use cases and the functional and non-functional requirements. Following are the non-functional requirements for the catalog service:

  • Interoperability: The catalog service needs to be accessed by multiple clients' implementations.
  • Maintainability: The existing catalog service is very course gained but the client invocations will typically only want a subset of the information provided
  • Performance: The catalog service needs to perform within certain time limits
  • Tractability: All invocation of the catalog service need to be traced

Review of the legacy catalog design model

Figure 4 shows a UML visualization of the legacy catalog application/service. This application is a Java component and exposes a Java interface. When you inspect this interface you'll see that the getCatalog() and getCatalogs() operations are very coarse-grained in that they return an entire catalog and a list of catalogs respectively. The legacy catalog design model is also accessible from the SOA Implement and Optimize Services Recipe but you don't need it for the purposes of what's discussed in this article.

Figure 4: Legacy catalog application design model
Legacy catalog application design model

Apply the appropriate patterns

When we talk about patterns (and let's use the Gang of Four "Design Patterns" as an example), two different elements are of most interest. One is the actual text that describes the pattern. This is what you would find in the book, say in the chapter on the Adapter pattern.

Then there are the design tooling elements that implement that pattern. For instance, there are UML artifacts in Rational Software Architect that implement the different Design Patterns from the Gang of Four book. So, if you wanted to apply an Adapter to one of your designs, you'd pull that element off the palette and make some manipulations in the tool to actually transform your design to use the pattern.

We're calling the first item a "pattern specification". The second item we're calling a "pattern implementation".

See the Resources section for the WS response template pattern specification

Using the Analysis and Design models the architect or developer will apply the appropriate patterns to satisfy the relevant non-functional requirements.

Three patterns will be used to construct the catalog service:

  • The WS response template pattern specification details the context, the problem and the repeatable solution. It provides service interface flexibility and maintainability. See the Resources section for the WS response template pattern specification.
  • The Requestor Side Caching Pattern specification improves the service performance. See the Resources section for the WS response template pattern specification.
  • The Logging pattern provides service invocation traceability.

Before we examine these patterns in detail it will help to consider an n-tier architecture as outlined below. A simple three-tier architecture will have a presentation tier, a business tier and and persistence tier. In a SOA environment we can separate the business tier further into a service layer, a controller layer, and a entity/object management layer. This layering is shown in Figure 5. The core Enterprise JavaBeans™ patterns such as the session facade, message facade, and the business delegate belong in the controller tier. Figure 5 shows where in the n-tier architecture these patterns are applied.

Figure 5. Pattern classification and structure
Pattern classification and structure

The WS response template pattern

An analysis of the catalog service model shows that the catalog service interface returns an entire catalog. While this may benefit some client applications, this interface is too coarse-grained for our application. One of the non-functional requirements is to make this catalog service perform and be interoperable with other services and clients.

Non-functional requirements

The WS response template pattern satisfies the following non-functional requirements:

  1. The service must be interoperable with other services
  2. The service most provide fine-grained access to coarse-grained interfaces
  3. The interface should provide some flexibility in the interface definition and allow for the evolution of the value objects

To satisfy these non-functional requirements we use the WS response template pattern. See the Resources section for the WS response template pattern specification. For completeness the class diagram and sequence diagram are shown below. These diagrams will make more sense in the context of the pattern specification. See the Sidebar discussion of pattern specifications and pattern implementations. The WS response template pattern specification details the context, the problem and the repeatable solution that the pattern provides.

Class diagram

Figure 6 shows the class diagram from the WS response template pattern.

Figure 6. WS response template class diagram
WS respose template class diagram

Sequence diagram

Figure 7 shows the sequence diagram for the WS response template pattern.

  • Using the provided WS response template-aware WSDL the client invokes the service. The requester invokes the WS response template implementation with a key and a request template.
  • The key uniquely identifies the required value object.
  • The request template tells the service implementation what disconnected sub-set of information is required in the response.
  • The service implementation queries the provider using the key and gets the corresponding value object associated with that key.
  • A runtime component -- an unsupported implementation is provided as part of the pattern -- called the navigator, is now invoked. The navigator takes a request template and a value object as input and returns and response template.
  • The response template contains a safe sub-set of the value object information graph requested by the user in the request template. The response template is returned to the requester.
Figure 7. WS response template sequence diagram
WS response template sequence diagram

Applying the WS response template pattern

The Web service response template pattern implementation can be imported into Rational Software Architect using the recipe. First navigate to the 'Apply patterns to a service implementation' section in recipe and expand the section 'Applying the WS response template pattern'. Locate the asset under this step and select import. See Figure 8.

You can see how this pattern is applied and used by watching the flash file available in the Download section.

Figure 8. Import the WS response template pattern implementation
Import the WS response template pattern implementation

This will install the WS response template pattern implementation into Rational Software Architect as well as the UML software services profile. Once the pattern has been installed it will show up in the pattern explorer as shown in Figure 9.

Figure 9. Pattern explorer showing the WS response template pattern
Pattern explorer showing the WS response template pattern

Here's how we will apply the pattern: Open up the SOA Inventory Service Model. You can obtain this service model from a Rational Software Architect repository, and it is referenced from the SOA Implement and Optimize Services Recipe. This model contains the UML Service Model for both the Catalog Service and the Inventory Service. Make sure that the UML Profile for Software Services, Rational Software Architect Plug-In has been installed. See the Resources section. If your install the WS response template pattern, the UML Profile for Software Services gets installed automatically

Figure 10. Import the SOA Catalog Service_Design Model
Import the SOA Catalog Service_Design Model

Figure 11 and Figure 12show the two perspectives that we are interested in: the Service View and the Message View

Figure 11. SOA catalog service design model view
SOA Catalog Service Design Model View

A CatalogItems Overview diagram in the message view shows the Catalog Messages. Double-clicking on it to open this view.

Figure 12. Catalog message model
Catalog message model

In the modeling perspective, drag and drop the WS response template pattern from the Pattern Explorer Pallet onto the Catalog Message Model. In the modeling perspective you may find this with the fast view icon on the upper right of Rational Software Architect. If you can't find it there, look for the the Pattern Explorer in Windows > Show View. Figure 13 shows the message model diagram after this has been done.

Figure 13. Applying the WS response template pattern
Applying the WS response template pattern

The WS response template pattern takes in four parameters:

  • The AnchorMessage Parameter: The root message of the message graph. In our case this will be the Catalog message
  • The ServiceSpecification Parameter: The Service Specification where the WS response template pattern will be applied. In our case this will be the Catalog Service
  • The FilterParameter Parameter: Typically this is an attribute of the child composite Message that allows filtering of the children elements. In our case this will be the SKU attribute what will allow the filtering of CatalogItems by sku
  • The WSRTOperations Parameter: Identifies the operations on the Service Specification that are to be made WS Response Template aware. In our case we use the getCatalog() operation.

Figure 14 shows what the model looks like after applying the pattern:

Figure 14. WS response template pattern applied to the catalog service model
WS response template pattern applied to the catalog service model

The output of applying this pattern is a new generated service model emx file. Figure 15 shows the internal structure of this generated WS response template-aware services model.

Figure 15. Generated catalog service model
Generated catalog service model

Inspection of this generated service model reveals the following:

  • There is now a separate request and response package in the message view corresponding to the request and response templates.
  • The message graph in the request package is loosely typed. This does not need to be strongly typed as it only serves to inform the service implementation about what elements are needed in the response.
  • The message graph in the response package is strongly typed as this refers to the actual data returned from the server

The method signatures in the catalog service interface has also changed. The getCatalog() operation signature is now in the following format: getCatalog(primaryKey, requestTemplate):ResponseTemplate . The method returns a strongly typed catalog response template instance. In addition, the method now takes in two request parameters:

  1. The primary key identifying the catalog
  2. A catalog request template, this request template allows the user to specify what (disconnected) sub set of the catalog information graph is required in the response.

The WS response template-aware WSDL and XSD can be generated from this new service model.

  • Locate the CatalogComponent in the service view
  • Locate the transformation menu in the right mouse context menu. Use the UML to WSRT transformation.
  • The dialog box for this transformation will prompt the user for a web project, to generate the WSDL and XSDs into, and the namespace for the WSDL. Use http://catalog.retail.ibm.com/ for the namespace.
Figure 16. UML to WSRT dialog box
UML to WSRT dialog box

We will use the WSDL to Java generator to create a Java implementation of the catalog Web service:

  • Switch to the J2EE perspective
  • Right-click on the generated WSDL file. Rational Software Architect Web Service capabilities must be enabled. To enable this and other capabilities, go to Windows > Preferences > Workbench > Capabilities and enable Web Service Developer and XML Developer.
  • Disable databinding for use of SOAPElement. Windows > Preferences > Workbench > Web Services > Code Generation > IBM WebSphere runtime. See Figure 17.
  • In the WSDL- Java generation dialog box check the Test the Web Service and the Monitor the Web Service.
  • The rest of the defaults may be accepted.
  • Note: It is a good idea to start the test IBM WebSphere® 6.0 server prior to this generation step.
Figure 17. Disable databinding for use of SOAPElement.
Disable databinding for use of SOAPElement.
Figure 18. WSDL to Java transformation
WSDL to Java transfromation

It is a good idea to test this empty implementation with the Web service explorer at this point. Figure 19 shows the an invocation of 'Catalog B', where all the client cares about is the name the description and the start date of the catalog.

Figure 19. Test with the Web service explorer
Test with the Web service explorer

In the SOAP invocation request there are two parameters:

  • The primary key for the catalog in this case catalog 'B'
  • The request template indicating that only the name, description and start date data should be returned.

If the monitor Web service box was checked during the WSDL to Java generation, the SOAP invocation request should appear in the TCP/IP tunneller with an empty SOAP response.

Now let's flesh out the implementation to return something real. In the getCatalog() implementation take the following steps:

  1. Call the legacy catalog application that gets the catalog, typically this will have the signature getCatalog(key):Catalog
  2. Call the navigator. A non supported reference implementation for the navigator is provided with this article (see the Download section) and must be included in the deployed application to convert the catalog request template and that catalog valueobject (from the legacy catalog application) into a catalog response object.
  3. A full listing of this server side implementation, both the generated skeleton interface and implementation for the Catalog service, is shown below.
  4. The wst.server (reference navigator code) and the legacy catalog application (the application that actually gets the catalog) must be made available to both the development and the runtime. See the Download section. For the development make sure both projects are included in the build path. For the runtime these project must first be added to the parent EAR file then referenced in the catalog service WAR file as dependant JARs.

The following listing shows the generated skeleton interface and implementation for the Catalog service:

Listing 1. Catalog service skeleton interface
/**
 * IWSRTTireCatalog.java
 *
 * This file was auto-generated from WSDL
 * by the IBM Web services WSDL2Java emitter.
 * o0505.16 v2605125559
 */

package com.ibm.retail.catalog;

import com.ibm.awsdc.wst.core.InvokerException;
import com.ibm.awsdc.wst.core.WriterException;

public interface IWSRTTireCatalog extends java.rmi.Remote {
    public javax.xml.soap.SOAPElement getCatalog(javax.xml.soap.SOAPElement key, 
    javax.xml.soap.SOAPElement requestTemplate) throws java.rmi.RemoteException, 
    InvokerException, WriterException;
}
Listing 2. Catalog service implementation
						/**
 * IWSRTCatalogSpecificationBindingImpl.java
 * 
 * This file was auto-generated from WSDL by the 
 * IBM Web services WSDL2Java
 * emitter. o0526.04 v62905175048
 */

package com.ibm.retail.catalog;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.server.ServiceLifecycle;
import javax.xml.rpc.server.ServletEndpointContext;

import com.ibm.awsdc.wst.core.InvokerException;
import com.ibm.awsdc.wst.core.Navigator;
import com.ibm.awsdc.wst.core.WriterException;

public class IWSRTCatalogSpecificationBindingImpl implements
	  com.ibm.retail.catalog.IWSRTCatalogSpecification,ServiceLifecycle {
	private ServletEndpointContext context;

	public javax.xml.soap.SOAPElement getCatalog(
		  javax.xml.soap.SOAPElement key,
		  javax.xml.soap.SOAPElement requestTemplate)
		  throws InvokerException, WriterException {
		Object catalog = null;
		String keystr = ((javax.xml.soap.Node) key.getChildElements().next())
			.getValue();
		System.out.println(keystr);
		// Get a refer to the legacy catalog application
		com.ibm.retail.entity.catalog.LegacyCatalogApp catalogImpl = 
		 new com.ibm.retail.entity.catalog.LegacyCatalogAppImpl();
		catalog = catalogImpl.getCatalog(keystr);
		// Nagivate the catalog to return a response template
		return Navigator.navigate(requestTemplate, catalog, context);
	}

	/*
	 * (non-Javadoc)
	 * 
	 * @see javax.xml.rpc.server.ServiceLifecycle#init(java.lang.Object)
	 */
	public void init(Object arg0) throws ServiceException {
		context = (ServletEndpointContext) arg0;

	}

	/*
	 * (non-Javadoc)
	 * 
	 * @see javax.xml.rpc.server.ServiceLifecycle#destroy()
	 */
	public void destroy() {
		// TODO Auto-generated method stub

	}
}

Test the implementation with the Web service explorer. Figure 20 shows the an invocation of 'Catalog A', where all the client is interested in is the name the description and the start date of the catalog.

Figure 20. Test with the Web service explorer
Test with the Web service explorer

Here is the corresponding SOAP invocation request. This request has two parameters:

  • The primary key for the catalog in this case catalog 'A'
  • The request template indicating that only the name, description and start date data should be returned.

If the monitor Web Service box was checked during the WSDL to Java generation, the SOAP invocation request should appear in the TCP/IP tunneller with an empty SOAP response. See Figure 21

Figure 21. TCP/IP Tunneller
TCP/IP Tunneller

See the Download section for final Rational Software Architect project, packaged as a Project Interchange file. To import into Rational Software Architect , choose File > Import > Project Interchange.


What have we accomplished?

Figure 22 shows the sequence diagram for the WS response template pattern as applied to the Catalog Service Model.

Examination of this sequence diagram reveals the following:

  • Using the provided WS response template-aware WSDL the client invokes the service. The requester invokes the WS response template implementation with a key and a request template.
  • The key uniquely identifies the value object required.
  • The request template tells the service implementation what (disconnected) sub set of information graph is required in the response.
  • The service implementation queries the provider using the key and gets the corresponding value object associated with that key
  • A runtime component (an unsupported implementation is provided as part of the pattern) called the navigator, is now invoked. The navigator takes a request template and a value object as input and returns and response template.
  • The response template contains a type safe subset of the value object information graph requested by the user in the request template. The response template is returned to the requester.
Figure 22. getCatalog() WS response template sequence diagram
getCatalog() WS response template sequence diagram

At this point, in applying the WS response template pattern to the catalog service, we realize that most of the effort involves understanding the problem, identifying its scope, and then making it general enough so that it would be applied again in the future.

We also come to see that the fundamental change is the method signature from getCatalog(primaryKey):Catalog to getCatalog(primaryKey, catalogRequestTemplate):CatalogResponseTemplate.

The requester now has fine grain control of what information is returned in the response from the service, and the service invocation now performs better in terms of the quantity of information on the wire. This is particularly relevant in WS invocations, where the ASCII nature of the contract increases the verbosity of the exchange.

Our solution leverages the existing capabilities of the tooling we worked on, and most of the effort was in understanding the problem, identifying it scope and making it general enough so that it would be applied again in the future.


Conclusion

In this article we applied a pattern to produce a flexible service model to help satisfy some of the non-functional requirements for that service. We also showed, in a broader context, how patterns in general satisfy non-functional requirements. Finally, using a WS response template pattern we produced a service that provides the client with fine-grained access to what was originally a coarse-grained interface, while maintaining network optimization, and also provides the flexibility in the service interface by allowing the correct entity to change without affecting the client.


Downloads

DescriptionNameSize
Final Interchange Projectwsrt-catapp.zip10KB
The WS Response Template runtime code (Nagivator)wst.server.zip23KB
Legacy Catalog ApplicationLegacyCatalogApp.zip50KB
Flash demo: Applying the WS Response Patternwsrt.swf1681KB

Resources

Learn

Get products and technologies

Discuss

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. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. 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 SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=146588
ArticleTitle=Building SOA applications with reusable assets, Part 3: WS response template pattern
publish-date=07142006