8.4 Design guidelines

---

8.4 Design guidelines

Figure 8-3 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 illustrates the logical connection between the source and target applications provided using SOAP.

Figure 8-3: Web services product mapping for Application Integration——Direct Connection

This view of the solution can be further expanded to obtain a "stack" of coupling adapter pairs over "virtual" connections between the source and target, as shown in Figure 8-4. In this diagram the dotted line represents a virtual connection which is actually implemented at lower levels.

Figure 8-4: Web services coupling adapter connector stack

8.4.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 building our sample application.

SOAP messaging style

SOAP provides support for both RPC style Web services and document-style Web services. In RPC style, Web Services are invoked using remote method calls. In document-style messaging, Web Services are invoked by sending a complete well-formed document describing the task to be performed, and possibly, some parametric data.

The advantages of SOAP RPC-based Web services are:

• Simpler to develop than SOAP message-oriented messaging

• Uses a higher level API

• Supports strong typing: all calls must conform to the method signature

The disadvantages of RPC-based SOAP messaging are:

• Higher coupling between the Web service requester and provider because the requester to provider binding includes both methods and parameters.

We used the RPC-based mechanism in our sample solution to demonstrate the Direct Connection pattern because of the simpler development effort involved. The RPC-based mechanism can be used for both the Call and Message styles of communication.

Transmission style

Web services support a number of transmission operations. These are the different types of operations that can be defined in a WSDL file:

• One-way - client sends a message to service

• Request-response - client sends a message to service, and awaits response

• Solicit-response - service sends a message to the client, and awaits response

• Notification operation - service sends a message to the client

The Direct Connection Call variation is a Request-response operation, while the Message variation is one-way.

SOAP transport protocol

In principle, SOAP is transport protocol independent and can therefore potentially use a variety of protocols (such as HTTP, JMS, SMTP, and others) to connect the Web service requestor and the provider.

HTTP is currently the most popular transport protocol for SOAP. The reasons for this mainly result from the following advantages:

• HTTP is the de facto standard on the Internet

• HTTP is wide spread

• HTTP is supported from most programming languages

• HTTP has a simple extension for security, HTTPS

• HTTP needs no complex infrastructure

But there are also some important limitations:

• HTTP is optimized for use in browser and end-user scenarios

• HTTP is a stateless communication protocol

• HTTP does not provide reliable communication

• HTTP establishes a point-to-point connection

These limitations are usually acceptable for human-to-machine communication using a Web browser. This may not be valid when switching to machine-to-machine communication. The requirements in machine-to-machine communication are usually more complex and other transport protocols may be more suitable.

For example, if you need assured, once-only delivery, message-oriented middleware may be more suitable. In Java you can use Java Messaging Service (JMS) with IBM WebSphere MQ. The advantages are:

• Reliable messaging

• Option of asynchronous communication

On the other hand you have the following disadvantages:

• More complex infrastructure

• Not generally available for all potential customers

• Message-oriented middleware skills are necessary

• At this time most vendors only have limited support for SOAP over JMS

With the increasing adoption of Web services, the portfolio of supported transport protocols will also increase.

We use the HTTP transport protocol in our sample solution to demonstrate the Direct Connection pattern because HTTP can provide the point-to-point connection we need between source application and target application without the need for added infrastructure.

Static versus dynamic Web services discovery

The source (requester) application can use either static or dynamic discovery of available Web services. The requester has to begin with the WSDL file that describes the interface and implementation specification of the Web service to be invoked. This WSDL file can be retrieved dynamically using a service registry, or statically, as shown in Figure 8-5.

Figure 8-5: Web services discovery methods

Three types of discovery methods for requesters can be identified:

• Static service with no public, private, or shared UDDI registry. The service description is obtained through a proprietary channel (an e-mail, for example).

• Provider-dynamic, where the service interface is dynamically discovered using a UDDI registry, and proxy code is generated from the interface at build time. The service implementation is dynamically discovered at runtime using the same or another UDDI registry.

• Type-dynamic, where the service requester dynamically discovers both the service implementation and interface at runtime. The requester uses generic SOAP APIs to bind to the service provider and invoke the Web service, rather than using generated proxy code.

Although early thinking on Web services asserted that discovery using UDDI would play a significant role in the implementation of the technology, at this time the vast majority of business solutions do not make use of dynamic discovery mechanisms. For this reason, our sample application uses the static service discovery method to access the WSDL file. For further details on dynamic discovery with examples, refer to the following redbook:

• WebSphere Version 5 Web Services Handbook, SG24-6891

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 example we use a simple message structure passing a string representing the part number being ordered in the request message and receiving another string representing the expected delivery date in the response.

For an example using an XML message see "Message structure" on page 187.

8.4.2 Object model

In this section we provide an object model for our RPC-based Web services scenario. We focus on how the source application accesses the target application using the JAX-RPC API in WebSphere V5.0.2.

Class diagram

Figure 8-6 is a class diagram of the main source and target application classes directly involved in initiating the direct connection between the source and target applications.

Figure 8-6: Class diagram of the Web service requester and provider (source and target)

Only the WebServiceBean class and the Inventory interface were developed by hand. The Inventory interface is developed as part of the target EJB application. It is based on the Inventory interface of the InventoryBean session EJB, but is modified to extend java.rmi.Remote rather than javax.ejb.EJBObject, as discussed below in 8.5.1, "Web service enabling the target application" on page 161. This interface is used to generate the target WSDL file, which we use later when generating the client bindings. This is discussed in 8.5.2, "Web service-enabling the source application" on page 166.

The InventoryService, InventoryServiceLocator, and InventorySoapBindingStub shown in Figure 8-6 were generated from the WSDL file. The WebServicesServlet is provided in the WebSphere V5.0.2 Web services runtime.

Interaction diagrams

In this section we provide interaction diagrams for the Message variation and Call variation of our RPC-based Web services scenario.

Message variation

Our implementation of the Update Inventory use case follows the Message variation, where the source application does not expect or wait for a response from the target application.

The interaction diagram in Figure 8-7 shows the sequence of steps performed when the source application uses the WebServiceBean to perform the updateInventory() method:

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

2. WebServiceBean invokes the getInventory method of the InventoryService interface (implemented by InventoryServiceLocator) to get the target service endpoint interface, Inventory.

3. WebServiceBean calls the updateInventory method of the Inventory interface (implemented by InventorySoapBindingStub) to invoke the Web service.

4. The stub implementing the Inventory interface performs a one-way invocation of the remote Web service via SOAP and HTTP using the WebSphere Web services runtime.

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

Figure 8-7: Interaction diagram for Web services Message variation

The one-way invocation of the Web service does not block the client application. Execution control returns back through the chain to the WebServiceBean at step 4, without having to wait for the updateInventory call to the InventoryBean to complete.

Call variation

Our implementation of the Get Delivery Date use case follows the Call variation, where the source application expects and waits for a response from the target application.

The interaction diagram in Figure 8-8 shows the sequence of steps performed when the source application uses the WebServiceBean to perform the getDeliveryDate() method:

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

2. WebServiceBean invokes the getInventory method of the InventoryService interface (implemented by InventoryServiceLocator) to get the target service endpoint interface, Inventory.

3. WebServiceBean calls the getDeliveryDate method of the Inventory interface (implemented by InventorySoapBindingStub) to invoke the Web service.

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

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

Figure 8-8: Interaction diagram for Web services Call variation

The delivery date then gets passed back through the chain to the requester side and to the WebServiceBean that made the request to begin with.

---