Best Practices and Pitfalls

This chapter next takes a look at various systemic qualities, such as manageability and scalability, which have to be addressed when building asynchronous Java EE .NET integration. Prior to that, the chapter discusses asynchronous communication support introduced in SOAP 1.2. Upcoming Java support of SOAP 1.2 and new features of Microsoft Indigo that simplify asynchronous programming are discussed, as well as the top-down development approach and industry standard compliance, which are discussed toward the end of the chapter.

Document-Oriented Approach

There are two main ways to submit a request to a Web serviceeither as a remote procedure call or as an XML document. A document-oriented approach is primarily intended for use with asynchronous Web services. A document, acting as a service request, is exchanged between a Web service client and the endpoint. In the Replenish Stock scenario, a Web service client, that is, Warehouse, asynchronously submits a Purchase Order document to the ManufacturerFaçade Web service. The Purchase Order is represented in XML format. The content of the document determines the processing steps required by the actual service, such as verifying validity of the request, submitting the request further for replenish stock, generating an invoice, and sending invoice information back to the service consumer.

Soap Messages with Attachments

The document-oriented approach can be used in conjunction with the SOAP with Attachments (SwA) specification, which allows exchanging official documents in binary format. Should an invoice for a purchase order be submitted along with an image of an item being shipped, SwA can be used. To consistently process attachments, the WS-I Basic Profile is extended with the WS-I Attachment Profile, which profiles SwA and WSDL MIME bindings in order to guarantee interoperability when sending documents as attachments. JAXRPC 1.1 implements these specifications, which provide Java and .NET developers with means of freely passing MIME types as an attachment to the SOAP message. This approach yields a smaller footprint SOAP message, which simplifies troubleshooting and minimizes the amount of memory required when processing the SOAP message.

Some limitations will likely be hit when using SwA between Java EE and .NET. Java supports MIME types, whereas Microsoft introduced the Direct Internet Message Encapsulation (DIME) type built into the .NET Framework. Specifically, Java-supported attachment types include images in .gif or .jpeg formats, plain text, XML document, and multipart typeall with the corresponding Java mapping. DIME basically supports the same types and provides mapping within the .NET Framework but does not interoperate with MIME. Thus having to agree on the transport binding using HTTP and a data format with a common schema does not indicate the end of interoperability concerns. The next problem resides in the packaging protocol: MIME versus DIME. There are third-party tools that can perform MIME to/from DIME translation. As an example, Smart421 offers a .NET extension to interoperate between MIME and DIME. The good news is that maturity and wide industry adoption of the MIME format caused Microsoft and other vendors to also support the MIME format. The Proposed Infoset Addendum to SOAP Messages with Attachments document [PASWA] discusses details of passing MIME formatted documents using Soap with Attachments, valid both for Java and .NET. Having a unified attachment format would allow developers to use SwA/MIME without having to solve yet another integration puzzle. MTOM, that was discussed in Chapter 4, "Web Services for Synchronous Integration," offers the interoperability of exchanging binary documents across Java EE and .NET Web services.

SOAP 1.2 Enhancements

SOAP 1.2 support for asynchronous communication has already been discussed. In addition to that, SOAP 1.2 abstracts out the transport bindings. While in SOAP 1.1 HTTP is the only supported binding, the new specification of SOAP 1.2 is designed to be fairly generic and support various transport protocols including SMTP, for example. A system may send an acknowledgment via e-mail, for which SMTP would be the necessary transport binding. Therefore, from an asynchronous Web services design standpoint, it is important to review supported bindings to identify the most suitable transport protocol prior to building the actual services. Additionally, SOAP 1.2 introduces a SOAP Response Message Exchange Pattern where a non-SOAP request can be followed by a SOAP response message, which may be important for designing asynchronous communication. Evaluating business requirements against new options in SOAP 1.2 can yield a simpler architecture.

Java Web Services Asynchronous Support

Both J2EE 1.4 and JWSDP 1.4 support JAX-RPC 1.1. The upcoming Java EE 1.5 will support JAX-RPC 2.0, which implements the SOAP 1.2 specification. With respect to asynchronous integration, JAX-RPC 2.0 will support the following new features:

• Non-Blocking RPC invocation, which allows an asynchronous Web services call not to have any return parameters.

• Automatic callback as part of the JAX-RPC 2.0 that would simplify asynchronous communication.

This book provides core Java samples using JAX-RCP APIs. The JAX-WS, unlike JAX-RPC, encompasses support for asynchronous Web services. Please refer to [JAX-WS_RI] for details. The JAX-WS reference implementation supports JAX-WS 2.0 specification, WS-I Basic Profile 1.1, WS-I Attachments Profile 1.0, and WS-I Simple SOAP Binding Profile 1.0. Following is the pseudocode for asynchronous Web services invocation. The actual Web service is implemented without knowledge of how it will be invoked. Because JAX-WS supports annotations, the Web service implementaion is quite simple:

@WebService(serviceName = "ManufacturerService", targetNamespace = "http://tempuri.org") public class ManufacturerImpl {      public String submitPO(int prodID, int prodQty) {           // String result ="receivedPO";           // Process Purchase Order request           // ...        return result;      } } 

A very similar definition of this service would be in .NET. Now look at the client application that asynchronously invokes this service via callback or response polling strategy. It was already described in Chapter 4 how to obtain a reference to a Web service using JAX-WS:

// Get instance of the Web service     ServiceFactory serviceFactory = ServiceFactory.newInstance();     ManufacturerService  service =                 (ManufacturerService)serviceFactory.createService(                 (java.net.URL)null, ManufacturerService.class); ManufacturerImpl port = service.getManufacturerImpl(); 

Here is a code snipped to access the service via response polling:

Response<SubmitPOResponse> resp = port.submitPOAsync(122, 10); Thread.sleep(2000); SubmitPOResponse result = resp.get(); 

For the callback mechanism, a handler, javax.xml.ws.AsyncHandler, needs to be developed that will be invoked once the service finishes its execution. The response returned by the handler is type of javax.xml.ws.Response:

   public class SubmitPOCallbackHandler implements AsyncHandler<SubmitPOResponse> {        private SubmitPOResponse result;        public void handleResponse(Response< SubmitPOResponse > res){           try {               result = res.get();           } catch (ExecutionException exe) {               exe.printStackTrace();           } catch (InterruptedException exe) {               exe.printStackTrace();           }        }        SubmitPOResponse getResponse(){           return result;        }    } 

Next is to implement a callback client that uses the handler and the java.util.concurrent.Future API that should already be familiar:

SubmitPOCallbackHandler callbackHandler = new SubmitPOCallbackHandler(); Future<String> response = port.submitPOAsync(122, 10, callbackHandler); Thread.sleep(2000); SubmitPOResponse result = callbackHandler.getResponse(); 

This example shows how JAX-WS can be leveraged to simplify implementation of the callback and response polling strategies.

Asynchronous Processing with Windows Communication Foundation

Microsoft is working on a new communication infrastructure called the Windows Communication Foundation (WCF, formerly known as Indigo) that modifies the programming models that Microsoft introduced in the past, such as support for asynchronous communication and bi-directional callback. The purpose of WCF is to realize SOA and provide developers with tools to build their business applications transparently to the underlying infrastructure. Along with WCF, Microsoft plans to release a new development environment called the Windows Presentation Foundation (WPF). WCF and WPF are aimed at simplifying the effort of building asynchronous Web services and adding security or reliability to the service. Once .NET and Java EE platforms support the same set of standards and specifications, for example WS-*, Java EE, and .NET, developers will be able to more easily build interoperable code.

While asynchronous processing simplifies remote system integration, it should be used with caution to ensure that requests processed asynchronously meet all required System Level Agreements (SLAs). Reliability is frequently a highlighted, necessary feature of asynchronous communication.

Reliability

The asynchronous callback strategy is a straightforward way of designing asynchronous communication. It is important, though, to ensure that a response eventually comes back to the original caller, which often is critical for the business flow. Having both Java EE and .NET support WS-Reliable Messaging would be ideal, but unfortunately this is not the case yet. Therefore architects may consider persisting incoming requests to be able to track them down later and ensure that the request did not get lost. A certain degree of reliability can be realized by setting up a time out mechanism. A worker thread on the server side may iterate over persisted requests and check for whether or not they have been processed. Each request may stay in the queue for only so long. A worker thread can propagate an error to the client callback service once requests have reached their time out interval.

A client application may incorporate retry logic to resubmit the request if a response did not arrive within a certain timeframe. In this case the remote system has to be able to identify the incoming request to avoid duplicate processing. For example, creating two invoices for the same purchase order would violate the business logic.

Manageability

Distributed computing with Web services introduces a new challenge of effectively tracing calls across multiple remote systems. Asynchronous processing adds more complexity since not only the request and its acknowledgement have to be traced, but also the callback call. Some of the products today address manageability by offering solutions that track down the call chain. For example, AmberPoint Solutions ships products that are available for both Java and the .NET Framework. These tools allow troubleshooting distributed service infrastructure and later, once Web services are deployed, monitoring and measuring the performance of the call.

Security

Addressing security is as important with asynchronous communication as with synchronous communicationeven more so with asynchronous processing, a server spends much more time dealing with each request, say a few hours or a few days. Thus it is imperative to prevent unauthorized requests from consuming server-side resources or causing a denial of service attack. Additionally, because it is likely that there will be two separate remote transactions for request and response, getting sensitive information transferred over a secure communication channel such as HTTPS is essential. In general, it is important to carefully analyze security requirements to address them early on during the design stage.

Scalability and Performance

It is often the case that the remote server should be able to process a high volume of asynchronous calls. For instance, an e-commerce site may redirect requests to a remote server for asynchronous processing. During the peak hours, the remote server would experience a high volume of requests that it would have to process. From a design standpoint it needs to be addressed that the remote server is capable of sustaining an increasing volume of requests. Additionally, assurance needs to be given that the volume of requests does not affect the response time, should it be a few seconds or a few hours. To ensure server scalability, it may be worth leveraging multi-threading. As a request comes in (in this chapter's example a ManufacturerFaçade), it may access a pool of worker threads to hand the request to an available thread in a pool. Java and .NET provide threading support that is explored later on.

Top-Down Approach in Web Service Development

The top-down approach to Web service development often is a good starting point to address developers' specific skill sets such as Java and .NET. As a best practice it is useful to start the Web services integration project with defining the Web Services Description Language (WSDL), based on the business and non-functional requirements. Defining actual service, request, and response parameters in XML can be the first step in defining the WSDL.

An XML document, understood well by both Java EE and .NET developers, can be easily understood and exchanged across development groups until everyone agrees on the semantics of a service. Sometimes a service provider group posts a WSDL corresponding to the existing service, and the service consumer group would only have to create a client compliant with the published WSDL.

With this top-down approach to Web services, Java EE and .NET developers can easily achieve a language and platform-independent level of interoperability. There are a number of tools available in the market to allow WSDL conversion into the corresponding language code and vice versa, to build the code as the next step in the development process. For example, the .NET Framework supplies a tool, xsd.exe, that can generate a Data Transfer object from the XML schema. On the Java side, the JAX-RPC tools follow the Java Architecture for XML Binding (JAXB), which defines open standard APIs for two-way mapping between XML documents and Java objects.

Implementing the Replenish Stock scenario may be involved if Java EE and .NET systems have an internal definition of the same business domain objects, such as Purchase Order and Invoice. This is a limitation that often has to be overcome within the scope of the integration project. In such a case, the Manufacturing system would have to convert the Purchase Order to map its internal representation. Likewise, the Retailer system would have to convert the Invoice into its internal representation. To achieve a higher degree of interoperability, it is suggested to create a schema of the Service being used in compliance with industry standards.

Universal Business Language (UBL) for Interoperability

UBL is one of the leading industry standards that identify multiple schemas to define a wide range of business domain objects. The Java Web services Development Pack, for example, extends Java binding with a sample application that demonstrates how to utilize the Universal Business Language (UBL) schemas in business applications. Most of the business applications require exchanging business related data, such as Order, Invoice, or Report. At the same time nearly all of the industry verticals have their own schemas specific to their industry. Individual companies extend those schemas with their business-specific domain objects. The interoperability between Java EE and .NET requires not only understanding of the integration technology, for example, Web services, but also the ability to interoperate across different heterogeneous domains. Therefore it is important to closely analyze the initial set of requirements to ensure interoperability at all levels.