9.3 Design guidelines

---

9.3 Design guidelines

Figure 9-1 shows the Runtime pattern and Product mapping we used to demonstrate the Direct Connection application pattern within the business domain of an organization, using Web services technology. It is the same Runtime pattern and Product mapping used in Chapter 8, "Using RPC style Web services" on page 147. It supports both RPC and document style Web services.

Figure 9-1: Web services product mapping for Application Integration--Direct Connection

See Figure 8-4 on page 153 for an expanded view of this solution, showing the "stack" of coupling adapter pairs over "virtual" connections between the source and target.

9.3.1 Design considerations

A number of factors affect the design of a Web service. In this section we discuss some of the factors we considered when using document style Web services in our sample application.

SOAP messaging style

SOAP provides support for both RPC style Web services and document style Web services. As discussed previously, the advantages of document style Web services include:

• Looser coupling between the Web service requester and provider

• Better interoperability between Web service requesters and providers

• Better fit with asynchronous messaging scenarios

The disadvantages of document style include:

• Higher development effort than RPC style

We used document style Web services in our sample solution to demonstrate the Direct Connection pattern because of the improved interoperability and looser coupling provided. The document-based mechanism can be used for both the Call and Message styles of communication.

Transmission style

As with RPC style Web services, document style Web services can be operated in synchronous (request-reply, solicit-response) or asynchronous (one-way, notification operation) modes. Deciding which mode to use depends on several factors:

• Quality of Service requirements

  Improving the performance, reliability, and scalability of the business process may be a major issue when discussing the decoupling of applications. Services using asynchronous mode are usually less prone to execution delays or failures of the target application.

• Implementation effort

  Where the source application expects a response from the target application, or requires confirmation of successful execution on the target side, it may be easier and more appropriate to provide services using a synchronous mode, such as request-reply. Using an asynchronous mode would require additional effort to handle the receipt of responses and notifications or to implement error handling. This also has an impact on QoS aspects such as maintainability or complexity of architecture.

• Transport protocol

  The choice of underlying transport protocol, and the resulting transport capabilities, will affect the ease of using one or other asynchronous mode. For example, using a message transport infrastructure facilitates asynchronous operations while HTTP rather favors synchronous operations.

Message structure

The Web services specification does not mandate any particular message structure; the message structure is defined by the service provider. Message structures can be anything from simple strings to complex XML documents. In our document style example we use an XML request document containing the part number being ordered in the request message, and in reply receive an XML response document containing the expected delivery date.

We define the required message structures using schema files that are imported into the WSDL file for our Web service provider. There are a number of considerations when importing your message and type definitions, including:

• Defining messages separately from the interface or implementation files facilitates reuse of the message definitions in other service definitions.

• Changes to schema files may impact services that use those definitions, particularly if the implementer of the service or consumer has generated serialization code directly from the WSDL files. This means that once a data schema is published, altering it may have a big impact on users of services that use the schema.

• For any imports that refer to a network location, the network location must be available when performing operations such as designing WSDL files, starting services, and so on.

• Both run-time and development-time products must support the use of imported schemas.

9.3.2 Object model

In this section we provide an object model for our document style Web services scenario. We focus on how the source application is accessing the target application using Axis.

Class diagram

Figure 9-2 is a class diagram of the main application classes involved in initiating the direct connection between the source and target applications via document style Web services.

Figure 9-2: Class diagram of the document style Web service requester and provider (source and target)

The WebServiceDocBean class was developed by hand. The InventoryDoc, InventoryDocService, InventoryDocServiceLocator, and InventoryDocSoapBindingStub shown in Figure 9-2 were generated from the WSDL file. The WebServicesServlet is provided in the WebSphere V5.0.2 Web services runtime.

The InventoryRequest and InventoryReply classes were also generated from from the WSDL file. These classes provide application access to the XML request and reply documents. We developed the InventoryRequestBuilder and InventoryReplyBuilder classes by hand as constructor helpers for request and reply messages.

Interaction diagrams

The interaction diagrams in Figure 9-3 and Figure 9-4 show the sequence of steps performed when the source application uses the WebServiceDocBean to perform the getDeliveryDate() method. In Figure 9-3:

1. WebServiceDocBean in the source application creates an InitialContext and uses it to perform a JNDI lookup to locate the InventoryDocService. This lookup finds the value set in the webservicesclient.xml deployment descriptor.

2. WebServiceDocBean invokes the getInventoryDoc method of the InventoryDocService interface (implemented by InventoryDocServiceLocator) to get the target service endpoint interface, InventoryDoc.

3. The WebServiceDocBean uses the InventoryRequestBuilder to create an InventoryRequest message.

4. WebServiceDocBean calls the getDeliveryDate method of the InventoryDoc interface (implemented by InventoryDocSoapBindingStub) to invoke the Web service. WebServiceDocBean passes the InventoryRequest message as a parameter of getDeliveryDate.

   The stub implementing the InventoryDoc interface invokes the remote Web service via SOAP and HTTP using the WebSphere Web services runtime.

   The stub returns an InventoryReply message to WebServiceDocBean.

5. The WebServiceDocBean calls the getBody method of the returned InventoryReply object. It can then get the delivery date from the message Body.

Figure 9-3: Interaction diagram for document style Web services- Part 1

Figure 9-4: Interaction diagram for document style Web services - part 2

In Figure 9-4:

1. The stub implementing the InventoryDoc interface (InventoryDocSoapBindingStub) invokes the remote Web service via SOAP and HTTP using the WebSphere Web services runtime.

2. The WebServicesServlet in the target application server invokes the getDeliveryDate method on the InventoryBean, which is the stateless session bean on the target application.

3. The InventoryBean calls the getBody method of the passed InventoryRequest message. It can then get the part number from the message Body.

4. The InventoryBean determines the delivery date for the part number and uses the InventoryReplyBuilder to create an InventoryReply message.

The InventoryReply message then gets passed back through the chain to the requester side and to the WebServiceDocBean that made the request to begin with.

These interaction diagrams cover our implementation of the Get Delivery Date use case using document style Web services. Although we have not provided interaction diagrams covering the Update Inventory use case, this use case has been implemented as a one-way document style Web service. Its interaction diagrams are similar, except the InventoryReply message is not used. Also, the one-way invocation of the Web service does not block the client application. Execution control returns back to the WebServiceDocBean, without having to wait for the updateInventory call to the InventoryBean to complete.

See also Figure 8-7 on page 159 for our interaction diagram for one-way RPC style Web services.

---