A meta-guide to technical web service design – part III

Back in April 2011 I didn’t intend writing a three part series of blog entries about technical web service design. But here we are in the third installment. In the first post[1] I used a very simple synchronous interface to demonstrate a design process and tool chain; in the second post[2]* I covered the installation and configuration of the tool chain.

Now we will use the process and tools to design interfaces that support various Message Exchange Patterns (MEPs). We will focus on the mapping between the MEP requirement, the JAX-WS based Java interface and the WSDL artifact. Four commonly used MEP’s will be covered:

NOTE: You will need a basic understanding of the design process and guidelines described in the first post to follow the discussion in this post.

1. Synchronous Request-Response-Fault MEP

The image below illustrates the Request-Response-Fault MEP:

MEP Description

In this MEP the service consumer sends a request message and requires a response OR fault message from the service provider on the same thread of execution.

Also note that the fault response is optional i.e not all synchronous exchanges require a fault response definition. That implies that this MEP can also be seen as a simple Synchronous Request-Response MEP.

WSDL Artifact

To successfully communicate the MEP requirements, for both consumers and providers, the resulting WSDL artifact must define the required schema types, messages and portType operation. The code fragment below shows an example WSDL operation definition for this MEP:

1
2
3
4
5
6
7
8
9
<wsdl:portType name="MEPService">
...
  <wsdl:operation name="sayHello">
     <wsdl:input name="sayHello" message="tns:sayHello"/>
     <wsdl:output name="sayHelloResponse" message="tns:sayHelloResponse"/>
     <wsdl:fault name="MEPServiceException" message="tns:MEPServiceException"/>
  </wsdl:operation>
...
</wsdl:portType>

The important thing to note here is the presence of an input, output and fault in the WSDL operation signature(line 4-6).

JAX-WS Interface Design

The following code fragments show the the method and class signatures and annotations that are required to successfully map the JAX-WS based Java interface and exception class to ensure the correctness of the resulting WSDL artifact:

  • Java method with annotations
    1
    2
    3
    4
    5
    6
    7
    
      @WebMethod (action = "sayHello")
      @WebResult (name = "OutputData",
                  targetNamespace = "java:mep.service")
      public OutputData sayHello(
          @WebParam (name = "InputData",
                     targetNamespace = "java:mep.service")
          InputData input) throws MEPServiceException;
    • The WebMethod annotation (line 1) ensures the creation of a WSDL operation.
    • The WebResult annotation (line 2,3) ensures the creation of the relevant response schema type, WSDL message and output operation parameter.
    • The WebParam annotation (line 5-7) ensures the creation of the relevant request schema type, WSDL message and input operation parameter.
    • The throws clause (line 7) ensures the creation of the fault operation parameter.
  • Exception class with annotations
    1
    2
    3
    4
    
    @WebFault(name = "MEPServiceException",
              targetNamespace = "java:mep.service",
              faultBean ="mep.service.data.MEPServiceFault")
    public class MEPServiceException extends Exception

    The WebFault annotation (line 1) ensures the creation of the fault schema type and WSDL message.

2. Asynchronous One-way MEP

The image below illustrates the One-way MEP:

MEP Description

In this MEP the service consumer sends a request to the service provider but does not expect a response in the form of a message (e.g a SOAP envelope containing a message). The consumer will receive some form of acknowledgment at a protocol level (e.g HTTP 202) to indicate that the request message was accepted but not necessarily processed.

This MEP also implies that the actual message processing happens on a separate thread of execution and not on the same thread the message was delivered on to the provider.

WSDL Artifact

In the same way as previously, the resulting WSDL artifact must define the required schema types, messages and portType operation. In this case only an input parameter is required on the WSDL portType operation, as indicated by the code fragment below:

1
2
3
4
5
6
7
<wsdl:portType name="MEPService">
...
  <wsdl:operation name="sayHelloAsync">
        <wsdl:input name="sayHelloAsync" message="tns:sayHelloAsync"/>
  </wsdl:operation>
...
</wsdl:portType>

JAX-WS Interface Design

The following code fragment shows the method signature and annotations that are required to successfully map the JAX-WS based Java interface to ensure the correctness of the resulting WSDL artifact:

1
2
3
4
5
6
  @WebMethod (action = "sayHelloAsync")
  @Oneway
  public void sayHelloAsync(
      @WebParam (name = "InputData",
                 targetNamespace = "java:mep.service")
      InputData input);
  • The WebMethod annotation (line 1) ensures the creation of a WSDL operation.
  • The Oneway annotation (line 2) in combination with the void return type (line 3) ensure that no output schema type, WSDL message or output operation parameter is generated.
  • The WebParam annotation (line 4-6) ensures the creation of the relevant request schema type, WSDL message and input operation parameter.

3. Asynchronous Request-Callback MEP

The image below illustrates the Request-Callback MEP:

MEP Description

In short, this MEP can be described as two Asynchronous One-way exchanges. The service consumer sends an asynchronous one-way request to the service provider and expects a response at some point in the future, on a different thread of execution. The service provider, after processing the initial request message, sends an asynchronous one-way request to the service consumer to serve as a callback or response to the consumer’s initial request message.

In this MEP it is implied that request and callback (response) message processing occur on separate threads of execution on both the service consumer and provider. In most cases this means that message correlation will be required to ensure that response messages are matched to the correct request messages. The WS-Addressing[3] specification is commonly used to facilitate message correlation and endpoint identification for web services.

WSDL Artifact

We have established that this MEP is made up of two asynchronous one-way exchanges. To successfully communicate this requirement the resulting WSDL artifact must contain two portType (interface) definitions.

  • The first portType must be implemented by the provider to receive requests from the service consumer.
  • The second portType must be implemented by the consumer to receive the callback or response from the provider.

The code fragment below shows the portType definitions with the corresponding request and callback operations. We have already addressed the provider portType definition in the Asynchronous One-way MEP, it is included again to clearly illustrate the WSDL requirements for this MEP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<wsdl:portType name="MEPService">
...
  <wsdl:operation name="sayHelloAsync">
        <wsdl:input name="sayHelloAsync" message="tns:sayHelloAsync"/>
  </wsdl:operation>
...
</wsdl:portType>
 
<wsdl:portType name="MEPServiceCallback">
...
  <wsdl:operation name="sayHelloCallback">
        <wsdl:input name="sayHelloCallback" message="tns:sayHelloCallback"/>
  </wsdl:operation>
...
</wsdl:portType>

JAX-WS Interface Design

To my knowledge it is not possible to specify more than one portType on a single Java interface using JAX-WS annotations. This means that we have to create a new JAX-WS based Java interface to define all the callback operations for a service. The code fragment below shows the additional Java interface that must be created to ensure that the callback portType is included in the resulting WSDL artifact.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@WebService(name = "MEPServiceCallback",
            serviceName = "MEPServiceCallback",
            targetNamespace = "java:mep.service")
public interface MEPServiceCallback
{
...
  @WebMethod (action = "sayHelloCallback")
  @Oneway
  public void sayHelloCallback(
              @WebParam (name = "OutputData",
                         targetNamespace = "java:mep.service")
              OutputData output);
...
}
  • The WebService annotation (line 1 – 3) ensures that an additional WSDL portType containing all the callback operations is created.
  • The remaining annotations (line 7 – 11) serve the exact same purpose as explained in the Asynchronous One-way MEP. Remember, the callback operation is just another one-way request.

NOTE: It is important to note that this MEP supports multiple callback operations and/or invocations i.e a single request message resulting in multiple callback (response) messages.

4. Asynchronous Request-Response-Callback MEP

The image below illustrates the Request-Response-Callback MEP:

MEP Description

In the same way the Asynchronous Request-Callback MEP can be seen as two Asynchronous One-way exchanges; this MEP can be seen as a combination of the Synchronous Request-Response and Asynchronous Request-Callback MEP’s.

In this MEP the service consumer sends a request message and expects an initial response message from the service provider, on the same thread of execution, to serve as an acknowledgment of receipt (This is different from the Asynchronous one-way exchange where the service consumer receives an acknowledgment at a protocol level). At some point in the future the service provider sends an asynchronous one-way request back to the service consumer, on a different thread of execution, which serves as the callback to the initial request message.

WSDL Artifact

Similar to the Asynchronous Request-Callback exchange, this MEP also requires two portTypes; one for the request and one for the callback. The request operation must however be synchronous.

The code fragment below shows the portType definitions with the corresponding (synchronous) request and (asynchronous) callback operations. We have already addressed the callback portType definition in the Asynchronous Request-Callback MEP, it is included again to clearly illustrate the WSDL requirements for this MEP.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<wsdl:portType name="MEPService">
...
  <wsdl:operation name="sayHelloSync">
      <wsdl:input name="sayHelloSync" message="tns:sayHelloSync"/>
      <wsdl:output name="sayHelloSyncResponse" message="tns:sayHelloSyncResponse"/>
  </wsdl:operation>
...
</wsdl:portType>
 
<wsdl:portType name="MEPServiceCallback">
...
  <wsdl:operation name="sayHelloCallback">
      <wsdl:input name="sayHelloCallback" message="tns:sayHelloCallback"/>    
  </wsdl:operation>
...
</wsdl:portType>

The important thing to note here is the definition of both an input(line 4) and output (line 5) parameter on the sayHelloSync (line 3) operation of the MEPService (line 1) portType.

JAX-WS Interface Design

I have purposefully introduced a new operation for the initial synchronous exchange in this example. This is to illustrate clearly that the response on the synchronous exchange is not the actual response, but only serves as an acknowledgment of receipt.

The following code fragment shows the method signature and annotations for the initial synchronous exchange to successfully map the JAX-WS based Java interface to ensure the correctness of the resulting WSDL artifact:

1
2
3
4
5
 @WebMethod (action = "sayHelloSync")
  public void sayHelloSync(
      @WebParam (name = "InputData",
                 targetNamespace = "java:mep.service")
      InputData input);

Comparing this code fragment to the ones used in the Synchronous Request-Response-Fault and Asynchronous One-way MEP’s you will notice that I have omitted both the WebResult and Oneway annotations. This instructs the tool chain to generate a simple synchronous interface where the response message is an empty document i.e a SOAP envelope with one empty element in the body. An example is shown below:

<soap:Body>
   <tns:sayHelloSyncResponse/>
</soapBody>

This again reinforces the notion that the synchronous response is only an acknowledgment. This simple response can be combined with SOAP headers to communicate meta data back to the consumer.

MEP Service Design Example

I created a service design project that contain working examples of all the MEP’s discussed here. The design output can be viewed here[4].

You can build the examples yourself by downloading the MEP source[5] and configuring your own environment*. Unzip the downloaded source and perform the following commands from inside the extracted mep directory:

  cd xsd
  ant
  cd ../java
  ant
  cd ../
  ant

The build artifacts should be available in the doc directory.

Notes

  1. * Please note that I have posted software version related updates to the blog entry titled: A meta-guide to technical web service design – part II[2], subsequent to it’s initial posting in June 2011. The blog entry detail the steps required to configure your own environment to execute service designs.

Links

Happy Hacking!

This entry was posted in programming, SOA, Web Services and tagged , , , , , . Bookmark the permalink.

51 Responses to A meta-guide to technical web service design – part III

  1. Pingback: lace wig

  2. Pingback: IdxjlTIZ

  3. Pingback: zTehCecQ

  4. Pingback: scrapebox

  5. Pingback: Chanel Outlet Bags

  6. Pingback: Scrapebox

  7. Pingback: Www.Footweares.Com

  8. Pingback: プラダ財布

  9. Pingback: Chanel Outlet

  10. Pingback: cabas Vanessa Bruno

  11. Pingback: payday loans toronto

  12. Pingback: direct payday loan easy approval lender

  13. Pingback: drugrehabcentershotline.com alcohol rehab centers

  14. Pingback: wayne

  15. Pingback: jesse

  16. Pingback: Vanessa Smith

  17. Pingback: Blue Coaster33

  18. Pingback: tv online, online tv

  19. Pingback: watch tv show episodes

  20. Pingback: tv online, online tv

  21. Pingback: stream movies

  22. Pingback: stream movies

  23. Pingback: watch movies online

  24. Pingback: tv online, online tv

  25. Pingback: tv online, online tv

  26. Pingback: watch movies online

  27. Pingback: watch movies online

  28. Pingback: Website

  29. Pingback: parking

  30. Pingback: her og nu lan

  31. Pingback: mp4 mobile porn

  32. Pingback: laane penge

  33. Pingback: water ionizer

  34. Pingback: car parking

  35. Pingback: water ionizer pay plan loans

  36. Pingback: house blue

  37. Pingback: apprentice electrician license

  38. Pingback: ionizer payment plan

  39. Pingback: water ionizer

  40. Pingback: wyroby szklane piotrków trybunalski

  41. Pingback: pay per day loan plans

  42. Pingback: pay per day loans plan

  43. Pingback: water ionizer payment plan

  44. Pingback: alkaline water

  45. Pingback: learn more

  46. Pingback: here

  47. Pingback: budowa

  48. Pingback: tier2

  49. Pingback: tier2 junk

  50. Pingback: Ruksis450

  51. Pingback: Ruksis780

Leave a Reply