Using Web Services Effectively

 

1.1 Web Service Processing and Interaction Models

Before you even begin to design a Web service, you should decide whether you need a Web service solution for your application. Web services should be used when you need interoperability across heterogeneous platforms. That is, when you need to expose all or part of your application to other applications on different platforms. Implementing a Web service makes sense when your application's clients are potentially non-J2EE applications. Even if your application's clients are all J2EE applications, you may still want to use Web services if your clients are scattered across the Web. However, when clients are all J2EE applications, it may be best to use J2EE technologies and avoid the extra performance cost of a Web service. Keep in mind that one of the key advantages to using Web services technologies is the ability to go through firewalls.

Generic Web services follow the service-oriented architecture model shown in Figure 1.1. In this model, a Web service first publishes its interface to a registry. The client then looks up, or discovers, the Web service from the registry. Last, the client binds to the Web service in order to use its services. In a Java programming environment, the Web service uses the Java API for XML Registries (JAXR) to publish itself to the registry. The client uses the same JAXR API to look up the service in the registry. The client uses JAX-RPC to bind to and use the Web service. See Figure 1.1.

Figure 1.1 Publish-Discover-Bind Model

While this architecture showcases generic Web services, when the service provider and the client are known to each other, they can bypass the publish and discover steps of the process. Instead, they can directly bind with each other and directly use each other's services. This document looks at scenarios in which the service provider and the client know each other.

Key to Web service design are how a Web service processes requests at the server side (its processing model) and how clients invoke and use the service (the Web service's interaction model). Figure 1.2 shows the categorization of Web services according to their interaction and processing models. Notice that typical Web services mix the different interactions and processing models, along with synchronous and asynchronous communication.

Figure 1.2 Web Service Models

A service's processing model may be business object (or method) centric or it may be document centric. The business object-centric approach (referred to as object centric) is driven by a series of method calls. These method calls apply the business logic of the service to a set of business objects containing the information required for processing the request. An example of an object-centric service might be a credit card authorization Web service. Such a service may receive the credit card details as parameters with the method calls. The methods invoked on the service map directly to specific business logic. The method parameters are used to map to a particular business object (such as a session or entity object) or they are used to pass data to the business logic.

With a document-centric Web service, the business logic is kept separate from the document content. The service receives an XML document, and that document contains only data and no explicit binding to the business logic that is to be applied. There is no mapping of the request to the business logic; that is, specific methods are not invoked on the service. Instead, the Web service applies its business logic to the XML document, and the document content determines the processing workflow. A travel agency Web service is a good example of a document-centric service. The service receives a request: an XML document that contains the details of the desired travel itinerary -- dates, places to visit, preferred accommodations, and so forth. The travel agency service processes the request according to the document content.

The interaction model encompasses the client's interaction with the Web service. A client's interaction with a Web service can be synchronous or asynchronous, or a combination of both types of communication. (That is, some method invocations may be synchronous and others may be asynchronous.) When a synchronous model is followed, the application typically uses an RPC-oriented interaction. With this type of interaction, the client's request is mapped to a method call on the Web service's business logic on the server. Using the credit card service as an example, the client utilizes an RPC call to invoke a method on the credit card service's server. The client passes the method the credit card details as an argument. The client might invoke a method to authorize use of the credit card and pass the method an object containing the card details, such as by invoking the method authorizeCreditCard(CreditCard cardDetails).

Document-centric processing is usually associated with an asynchronous messaging communication. The client's request is sent as a message. The Web service receives the message and processes it, sending the results when it completes its processing. In the case of the travel agency service, the details of the client's travel request are sent to the service as an XML document via a message (or as an attachment to an RPC call). The service receives the document and parses it to determine how to process the request.

The RPC-oriented and document-oriented Web services form two ends of a spectrum. At one end, a Web service may use a totally RPC-oriented interaction model and object-centric processing, in which case you model it as a RPC-oriented Web service. At the other end, a service may be completely document oriented and communicate with asynchronous messaging.

However, keep in mind that most Web services fall somewhere between these two cases and you can mix and match the models. Keep in mind, also, that even a purely RPC-oriented Web service uses XML protocol (Simple Object Access Protocol), though it keeps the use of XML transparent to the client and server. The client and server deal with method calls and objects as parameters to these calls. The underlying platform handles the XML.

1.2 Web Service Interaction Architectures

Recall that the previous discussion of the Web service model referred to synchronous and asynchronous communication. There are two principal architectures for Web service interfaces: synchronous Web services and asynchronous Web services. These two architectures are distinguished by their request-response handling. With synchronous services, clients invoke a request on a service and then suspend their processing while they wait for a response. With asynchronous services, clients initiate a request to a service and then resume their processing without waiting for a response. The service handles the client request and returns a response at some later point, at which time the client retrieves the response and proceeds with its processing.

A Web service may combine synchronous and asynchronous architectures. Often, this architectural decision is made based on the types of work the service performs and the available technologies.

In addition, enterprise application integration (EAI) uses Web services to integrate enterprise information systems. EAI may make use of both synchronous and asynchronous Web services. See EIS Integration with Web Services for a more detailed discussion of EAI.

1.2.1 Synchronous Web Services

Synchronous services are characterized by the client invoking a service and then waiting for a response to the request. Because the client suspends its own processing after making its service request, synchronous services are best when the service can process the request in a small amount of time. Synchronous services are also best when applications require a more immediate response to a request. Web services that rely on synchronous communication are usually RPC-oriented. Generally, consider using an RPC-oriented approach for synchronous Web services.

A credit card service, such as one that might be used in an e-commerce application, is a good example of a synchronous service. Typically, a client -- the e-commerce application at check out time -- invokes the credit card service with the credit card details and then waits for the approval or denial of the credit card transaction. The client cannot continue its processing until the transaction completes, and obtaining credit approval is a prerequisite to completing the transaction. (See Figure 1.3.) A stock quote Web service is another example of a synchronous service. A client invokes the quote service with a particular stock symbol and waits for the stock price response.

Figure 1.3 Synchronous Web Service Interaction

Synchronous Web services are architected using a JAX-RPC servlet endpoint. The servlet endpoint receives the client's request and then delegates the request to the service's appropriate business logic, which may reside in the service's Web tier or Enterprise JavaBeans^TM (EJB^TM) tier. The service's business logic processes the request. It may access the business data through a persistence mechanism, if required. When it completes its processing, the service's business logic formulates a response and the JAX-RPC servlet endpoint returns the response to the client. See Figure 1.4.

Figure 1.4 Synchronous Services With JAX-RPC

A synchronous architecture such as this is also suited to expose a Web service interface to an existing J2EE application that may already have a browser, wireless client, or rich client interface. In such a case, the Web service interface becomes another view (or presentation of) the existing J2EE application.

1.2.2 Asynchronous Web Services

With asynchronous services, the client invokes the service but does not -- or cannot -- wait for the response. Often, with these services, the client does not want to wait for the response because it may take a significant amount of time for the service to process the request. The client can continue with some other processing rather than wait for the response. Later, when it does receive the response, it resumes whatever processing initiated the service request.

Generally, a document-oriented approach is used for asynchronous class of services. Services which process documents tend to use an asynchronous architecture. A document-oriented Web service receives a document as a service request. The document content determines the processing workflow for the Web service. There can be a number of processing steps required to fulfill the request.

A travel agency service is a good example of a document-oriented Web service that might benefit by using asynchronous communication. The client sends a document (such as an XML document) to the travel service requesting arrangements for a particular trip. Based on the document's content, the service performs such steps as verifying the user's account, checking accommodations and transportation availability, building an itinerary, purchasing tickets, and so forth. Since the travel service must perform a series of often time-consuming steps in its normal workflow, the client cannot afford to pause and wait for these steps to complete. The Java Pet Store supplier sample application is another example of a document-oriented service that works well with asynchronous communication. (See Web Services in the BluePrints Application for more details on the supplier application.)

Figure 1.5 shows how an asynchronous Web service might be architected. This figure shows one recommended approach for architecting a Web service to achieve asynchronous communication in the J2EE 1.3 setting. In this architecture, the client sends a request to the JAX-RPC servlet endpoint on the Web container. The servlet endpoint delegates the client's request to the appropriate business logic of the service. It does so by sending the request as a Java Message Service (JMS) message to a designated JMS queue or topic. The JMS layer (along with message-driven beans) makes asynchronous communication possible.

Figure 1.5 Asynchronous Web Service Communication

After the request is successfully delegated to the business logic, the JAX-RPC servlet endpoint may return an ID to the client. Message-driven beans in the EJB tier read the request and initiate processing so that a response can ultimately be formulated. The service may make the result to the client's request available in one of two ways:

• The client that invoked the service periodically checks the status of the request using the ID that was provided at the time the request was submitted. (This is also known as polling.)
• Or, if the client itself is a Web service peer, the service calls back the client's service with the result.

Figure 1.6 shows how the supplier sample application implemented an asynchronous communication such as this. A customer shopping the pet store initiates an order. The pet store application generates a purchase order and sends it via JMS to the Order Processing Center (OPC) application. The OPC has a Web service invoker that sends a supplier purchase order as a request to the supplier application's Web service endpoint. The endpoint receives the request and acknowledges the receipt by sending an ID back to the OPC Web service invoker. Later, when the supplier application fulfills the request, its Web service invoker sends the result to the OPC Web service endpoint.

Figure 1.6 Communication to the Supplier Application

1.3 Designing a Web Service Interface

At this point you have decided that a Web service best meets the needs of your application and environment. You need interoperability across heterogeneous platforms and probably need to go through a firewall. In this case, the constraints on security and performance are not as critical.

Once you've decided that your application needs a Web service, you then make some general decisions about the service, including how to expose the Web service, how the service performs its processing, and its granularity.

1.3.1 Granularity of Web Services

Much of the design of a Web service interface involves designing the service's operations. Once you determine the service's operations, you define the parameters for these operations, their return values, and any errors or exceptions that they can generate. That is, you define the method signatures of the service.

The same issues hold true for designing a service's methods as for methods of a remote enterprise bean, particularly with respect to remote access and the impact on performance. Thus, you should define the Web service's interface for optimal granularity of its operations. While fine-grained service operations, such as an operation to browse a catalog by categories, products, or items offer greater flexibility to the client, they also result in greater network overhead and reduced performance. More coarse-grained service operations, such as returning catalog entries in a set of categories, reduce network overhead and improve performance, though they are less flexible. Generally, you should consolidate fine-grained operations into more coarse-grained ones to minimize expensive remote method calls.

1.3.2 Web Service Interfaces and JAX-RPC

Developers can begin the design of a Web service interface with either a Java service definition or Web Services Description Language (WSDL) definition. It is usually more convenient to start the design of the Web service interface with a Java service definition instead of a WSDL interface.

Generally, the model you choose for your Web service should be driven by the processing requirements. If you decide to use an object-oriented approach, then it is recommended to use JAX-RPC to invoke methods and pass arguments and return values with a Java objects-to-XML binding to ensure maximum interoperability.

At the other end of the spectrum, such as for business-to-business interaction requirements, you may model a service that follows a document-centric interaction and processing model as a document-oriented Web service. In this model, pass documents in JAX-RPC as javax.xml.transform.Source objects.

1.3.2.1 Object-Centric Parameter Binding

Figure 1.7 shows how a service endpoint might pass SOAP requests as a parameter to business logic. (The approaches shown within the dotted lines are not recommended.)

Figure 1.7 Binding Parameters and Return Values in Object-Centric Processing

For the object-centric approach, it is recommended that whenever possible, parameters be passed as Java objects with standard type mapping. Using Java objects that have a standard mapping to SOAP parameter types improves interoperability. The JAX-RPC supported types are:

• Built-in types, including:

-

All primitives and wrapper types (e.g. int, Integer)

-

String, Date, Calendar, BigInteger, BigDecimal, and QName

-

Arrays of all supported types

• User-defined classes (JAX-RPC value types), including any class with JavaBeans^TM component-like properties and public fields
• Any other type for which a pluggable serializer is available. For example, a class without JavaBeans component-like properties requires a custom JAX-RPC serializer.

While it is possible to pass parameters as other Java objects, the service's portability is limited because the pluggable (or extensible) serialization framework is not yet standard. Thus, you should avoid passing parameters that require the user of custom serializers or custom deserializers. Parameters may also be passed as SOAP document fragments. The SOAP fragments must be explicitly bound to Java objects at the Web tier before being passed to the business logic. SOAP document fragments that are not explicitly bound to Java objects should not be passed to the EJB or business tier, because this ties the processing in the business tier to the logic in the Web tier.

1.3.2.2 Document-Centric Parameter Binding

Figure 1.8 shows how requests can be passed as parameters or attachments and handled with document-centric processing. Here, the XML document is wrapped into a Source object (javax.xml.transform.Source) and passed to the next level. It is also possible to pass an URL to the XML source document. In addition to the Source object argument, other JAX-RPC arguments may be used to pass metadata, processing requirements, security information, and so forth.

Figure 1.8 Parameter and Return Value Binding with Document-Centric Processing

1.4 Implementing a Web Service

Once you know how to model your Web service and the design approach you want to take, then you are ready to implement the service. The key steps for implementing a Web service are:

• Receiving a document and generating a response
• Mapping calls to internal representations
• Performing business logic
• Exposing the Web service

Exposing Model Data Via Web Services explains how to design enterprise bean components as reusable Web service components. Web Services in the BluePrints Application shows how the Java Pet Store sample application implemented its Web service.

1.4.1 Receiving and Responding to Requests

The Web tier, through a JAX-RPC endpoint, generally receives client requests. Incoming client requests (in the form of SOAP messages) are mapped to method calls on the classes that implement the Web service interface. This service endpoint should perform security validation, transform parameters, and pre-process the parameters for these requests before delegating the requests to the Web service business logic. Parameters are passed as either Java objects, XML documents (javax.xml.transform.Source objects), or even SOAP document fragments (SOAPElement objects).

While it is straightforward to handle parameters bound to Java objects, additional steps may be required with XML documents. The following steps are recommended:

1. The service endpoint should validate the incoming XML document against its schema.
2. The service endpoint then transforms the XML document to an internally supported schema.
3. Last, the service endpoint disassembles the document and possibly maps it into domain objects.

It is important that security validation be performed as close to the service endpoint as possible, and certainly in the Web tier. Catching errors earlier avoids unnecessary calls to the EJB tier.

Response generation, which is simply constructing the method call return values, is also performed on the Web tier, again as close as possible to the service endpoint. Keeping this functionality in the endpoint enables you to implement caching of data to avoid extra trips to the EJB tier. It also permits centralizing response assembly and XML document transformations, particularly if the document to return to the caller must conform to a different schema from the internal schema.

Figure 1.9 shows the recommended way to handle requests and responses in the Web tier interface.

Figure 1.9 Web Tier Request and Response Processing

The Web service endpoint handles all incoming SOAP requests and delegates to the business logic exposed in the EJB tier, possibly through a Session Facade design pattern in the EJB tier. The Web service interface when implemented in this manner gives you several advantages, since it:

• Manages the handling of requests and serves as the initial point of contact
• Invokes security services, including authentication and authorization
• Delegates business processing
• Handles errors

1.4.2 Mapping Web Service Calls to Business Logic

You should consider several guidelines when mapping Web service calls to business logic. Generally, in RPC-oriented Web services, you want to map calls from a Web service interface implementation to a Session Facade. Following this design pattern will make it easier to move at a later date to an enterprise bean endpoint.

It is also important to consider granularity. A Session Facade method should have a granularity that is finer than the Web service interface. That is, one method call on a Web service should map to one or more calls on a Session Facade. When multiple Web service calls map to one Session Facade call, then the Web service must maintain some context regarding the calls. Maintaining such context is not recommended.

With a document-oriented model using asynchronous messaging, it's best to map the request to a JMS message submission. JMS provides the asynchronous handling.

1.4.3 Performing Business Logic

The EJB tier or business layer is where the business logic is applied to a Web service request. A Web service exists to expose an application's functionality. It typically does not influence the business logic processing. This is particularly true for Web services using an object-centric approach. However, there are some guidelines for performing business logic for Web services with document-centric processing.

It is a good practice to keep an enterprise bean's document manipulation logic separate from the business logic.

With document-centric processing, business logic is applied to data accessed through XML documents. Thus, an enterprise bean must read and modify an XML document to apply the business processing. Abstracting document manipulation logic from business logic allows the bean's developer to switch between different XML document manipulation approaches, such as DOM, SAX, JDOM, and so forth, without affecting the business logic. In addition, it completely hides document processing implementation details from the business logic. This is similar to the Data Access Object (DAO) pattern, which abstracts database access code from the bean's business logic.

In the document-centric processing model, an enterprise bean receives an XML document that contains all information for processing a request. Typically, the XML document has well-defined segments containing details about a specific entity.

Rather than pass the entire document to different components, it's best if the receiving bean breaks the document into fragments and passes only the required fragments to other components that implement portions of the business logic.

Figure 1.10 Fragmenting an XML Document

Figure 1.10 shows how the EJB tier might process an XML document representing a purchase order. The document contains such details as account information, credit card data, line items on the order, and so forth. The business logic involves verifying the account, authorizing the credit card, and processing the line items. It's not necessary to pass all the document details to a workflow stage that is only performing one piece of the logic, such as account verification. Passing the entire purchase order document to all stages of the workflow results in unnecessary information flows and extra processing. It is more efficient to extract the logical fragments -- account fragment, credit card fragment, line item fragment -- from the incoming XML document and then pass these individual fragments to the appropriate workflow stages in the most appropriate format (DOM tree, Java object, serialized XML, and so forth) expected by the receiver.

Fragmenting a document has the following benefits:

• It avoids extra processing of superfluous information throughout the workflow.
• It maximizes security because it limits sending sensitive information through the workflow.
• It centralizes the workflow and simplifies the workflow implementation.
• It provides greater flexibility to workflow error handling.

1.4.4 Exposing a Web Service

Exposing a Web service means publishing a description of the Web service. A Web service description consists of the service's Web Services Description Language (WSDL) description and XML schemas referenced by the service description. (WSDL is the standard language for describing a service.)

You may publish a Web service description on a corporate registry within an enterprise or on a public registry outside the enterprise. You may also publish XML schemas defined by the Web service on the same corporate or public repository. A Java Web service client uses the JAXR APIs to look up the service description on the corporate or public registry.

You do not need to use a registry if all your clients are dedicated partners. Instead, you can publish your Web service description (the WSDL and XML schemas) on the Web tier of your application or at a well-known location with the proper protection. An example might be a client application of a reseller that has an agreement with a particular supplier and has been statically bound at development time to its supplier's Web service. Only authorized parties can retrieve the service description from the Web tier to generate the client code, as well as reference the XML schemas.

1.4.5 Designing for Performance

Good design and proper use of the technologies can greatly improve Web service performance. You should consider the following performance recommendations when designing a Web service.

1.4.5.1 Using Caching and Service Granularity

Web service clients tend to be richer clients and thus can do more work on the client side, such as caching. Web services can maximize performance by correctly using data caching. You should consider using caching in a Web service when the service's requested information is primarily read only or when that information changes at a slower rate than at which it is requested.

Caching at the client side may also be effective when the service's granularity of operation is more coarse grained than that of the client requestor. (See Granularity of Web Services.) In such a situation, the service provides more information than the client needs for a particular request. However, if the client issues similar requests, then caching the data may improve response time. This is especially true for clients making synchronous requests, since they must consider the time to construct the response in addition to the time to transfer the data.

On the other hand, fine-grained Web services transfer smaller sets of data but may handle more requests within the same time frame. The amount of time to handle the SOAP protocol, including parsing the XML document request and constructing the XML response, becomes critical, and caching may be useful on the server side. This is especially true when the service exposes fine-grained operations to distributed applications but internally handles coarse-grained requests. Consider caching on the server the SOAP request and response to the Web service itself (with SOAP message handlers) and any internal requests and responses between the Web tier and the EJB tier.

1.4.5.2 Using XML

XML, while it has many benefits, also has performance disadvantages. XML often demands a great deal of CPU processing. Most XML documents must not only be parsed but also validated, and many require additional processing. Processing XML documents also requires a large amount of memory. Typically, XML processing may require creating large numbers of objects, especially when handling document object models of any kind. XML may also be network intensive. A given document may be the aggregation of different external entities. Parsing the document may require that each entity be retrieved across the network.

The following guidelines help minimize the performance overhead of using XML.

• Use XML judiciously. Use XML when you must interoperate with heterogeneous systems and provide loosely-coupled integration points. Try to rely on XML protocols such as those implemented by JAX-RPC. Maximize interoperability by using existing public vertical schemas. Avoid using XML for unexposed interfaces or for exchanges between components that are tightly coupled.
• Avoid unnecessary parsing and validation. Because processing XML documents may be CPU, network, and memory expensive, it's best to keep to a minimum such operations. You should parse incoming XML documents only when the request is properly formulated, such as documents passed as Source parameters to JAX-RPC calls. Validate the document's meta information, which may have been passed as additional JAX-RPC arguments, and perform the security validation before retrieving the document. Always try to use the proper API to process the document.
• Bind documents to domain Java objects as soon as possible. Then process the Java objects rather than the XML documents.

Additional guidelines apply when implementing an application that spans multiple containers. When the application components interact remotely, try to pass only Java objects. Also consider using the Transfer Object design pattern. With remote interaction, it is expensive to pass DOM trees, plus not all implementations support Java serialization of DOM trees. While using serialized XML is expensive and thus best avoided, it may be required to provide loosely-coupled integration points.

When application components follow a local interaction mode (they reside in the same container or Virtual Machine), then it is highly efficient to pass Java objects. It is also efficient to pass DOM trees by reference, though this may not be the optimal choice from the perspective of the business object interface. Because of the manipulation required, passing DOM trees by reference impacts memory and processing. However, it is acceptable to do so when required by the application processing model, especially for document-centric models. However, local components should not pass serialized XML among themselves. In the context of a local call, there is no reason to serialize XML and later deserialize it.

1.5 Exposing Model Data Via Web Services

Your Web service may need to expose model data in its interface. Often, model data is implemented as reusable components. This section discusses how to organize the XML representation of these objects. It's possible to create enterprise bean components that are easily reusable as Web service components. For example, your application might pass an Account XML document that maps to an AccountEJB enterprise bean. There are two general guidelines to accomplish this.

• Create and expose a Session Facade for the application. Using a Session Facade to expose an application's operations will make it easier to migrate to enterprise bean endpoints at a later date.
• Create reusable enterprise bean components that expose an XML interface in the form of a generic XML schema. This allows the enterprise bean component to be reused in the context of a Web service. For document-centric Web services, a document can flow to the EJB tier and enterprise bean components can manipulate the document. Object-centric Web services deserialize documents at the service endpoint.

Consider an application that has an account component with two sub-components: a credit card and a profile component. Together, there are three entities: Account, CreditCard, and Profile. Account is a composite entity composed of two generic entities, CreditCard and Profile. The application implements these three entities as three enterprise beans: AccountEJB, CreditCardEJB, and ProfileEJB. Furthermore, AccountEJB has a one-to-one relationship with both CreditCardEJB and ProfileEJB.

To make these enterprise bean components Web-service ready, you may create a generic XML schema or use an existing public schema along with an XML serializable domain object for the CreditCard and Profile components. The generic schema is an XML representation of the component state. The XML serializable domain object is an object representation of the component state, and it provides the facility to obtain the component state in a serialized XML form. Once you create the generic schemas, you can represent the composite Account entity with a composite schema and its own XML serializable domain object. You derive the composite schema from the generic schemas of the composite entity's two components.

Should you consider designing Web service-ready enterprise bean components, you must take three additional steps for each enterprise bean component to make it a service endpoint:

• Create a generic XML schema for the component state
• Create XML serializable domain objects using the Java API for XML Binding (JAXB). Or, create a JAX-RPC serializer/deserializer (when the serialization framework is standardized).
• Create composite XML schemas for composite entities

See Figure 1.11.

Figure 1.11 Generating a Composite Schema

Once you've set up the enterprise beans in the business tier as just shown, you can easily create vertical XML schemas from these generic schemas. You do this using XSLT and style sheets, as shown in Figure 1.12.

Figure 1.12 Creating Vertical Schemas

There are advantages to designing your business tier in this manner.

• Having a generic internal schema separates the application's model from the presentation aspects. The application's business logic can remain the same for different types of clients and different presentation approaches. The application internally processes documents conforming to a generic schema, transforming the documents from the generic schema to the clients' specific XML schemas.
• You can implement more efficient caching in the Web tier.
• You build more flexibility into the design of the application.
• It promotes reusability of generic components.
• It maintains separation of developers' skills.

1.6 EIS Integration with Web Services

More and more, Web services are used for enterprise application integration. The J2EE platform already provides the Java Connector architecture for enabling components in a J2EE container to access and use resources in enterprise information systems and other legacy systems. A Web service uses the Java Connector architecture capabilities to expose these EIS and legacy resources to other non-J2EE clients.

A Web service for EIS integration can be a synchronous or asynchronous service, and this decision is based on the nature of the service's workflow. The architecture of a Web service providing EIS integration might have a JAX-RPC servlet endpoint to receive the client request. The endpoint delegates the request to the service's business logic, which in turn accesses the EIS or legacy system through the Connector architecture. The business logic formulates a response and the endpoint communicates that response to the client. See Figure 1.13.

Figure 1.13 EAI Architecture With JAX-RPC

Keep in mind that you can combine architectures in any given Web service. For example, you can wrap either a synchronous or asynchronous service around a legacy system or EIS. You can implement a JAX-RPC servlet endpoint to extend existing J2EE applications to expose a Web service interface. The servlet endpoint uses an application's existing business logic for processing client requests.

1.7 Web Services in the BluePrints Application

The Java BluePrints Pet Store sample application uses Web services to communicate between its Order Processing Controller (OPC) and external supplier applications. This section examines the sample application's use of Web services to illustrate the architectural models and technologies discussed previously.

The sample application follows a document exchange for a purchase order initiated in the Java Pet Store front end. The Order Processing Center (OPC) application manages the order, sending every purchase order through a defined sequence: the OPC first ensures that the buyer has sufficient funds for the purchase and then orders the product from the supplier. The OPC defines the business process for handling purchase orders. The business process consists of a workflow, which is a sequence of steps with transitions between steps. Transition delegates are classes that handle the transitions between workflow steps. The sample application uses a document-oriented business process to co-ordinate its internal workflow and to communicate with its supplier application -- its transition delegates pass XML documents between workflow steps by placing JMS messages in message queues, a form of asynchronous communication. These JMS queues (and topics) are the transition points between steps. The XML documents serve as the internal data model for the applications, and they may be validated against specific public XML schemas (DTDs or XSDs).

The application was developed using an asynchronous architecture because of the amount of time it takes to process an order through the workflow. A document-centric approach was used because passing XML documents works best with asynchronous communication.

The Supplier is an external application that ships orders to customers and invoices the OPC. Because these applications are potentially on different platforms, communication between the Supplier and OPC is through a Web service. The two applications pass XML documents between them. These XML documents conform to a pre-defined public XML schema which is accessible through a public URL. Such schemas ensure proper document exchange and allow documents to be validated.

The communication between the OPC and Supplier applications is also asynchronous. With asynchronous communication, the OPC does not have to wait for the Supplier to complete its order processing. Figure 1.14 shows a high-level view of the communication between the OPC and the Supplier applications.

Figure 1.14 High Level View of Web Services in the Sample Application

The OPC application processes documents through its internal workflow using a series of message-driven beans and JMS queues. Each message-driven bean uses a pluggable transition delegate to determine the next step in the workflow. Using transition delegates allows for flexibility if the type of communication changes between workflow steps.

The OPC receives the purchase order through its Purchase Order Queue and obtains an order approval by sending a message to the Order Approval Queue. The Order Approval message-driven bean confirms if funds are available for the order.

Once the order is approved, the OPC then sends the order to the external Supplier application. To do this, the Order Approval message-driven bean invokes the Web Service Transition Delegate, which looks up the Supplier's Web service endpoint and the public XML schema for the document. The bean then sends the purchase order as an XML document to the Supplier's service endpoint.

The Supplier Web service endpoint receives the document and validates it against its public XML schema. It transitions valid purchase orders to the next step in the Supplier's workflow, using an approach similar to that of the OPC: JMS messaging with message-driven beans and transition delegates. The Supplier fills valid orders and ships products to the user. It also creates and returns an invoice as an XML document to the OPC. The Supplier sends the invoice document as an attachment to a request sent to the OPC's Web service.

The OPC Invoice Receiver Web service endpoint receives the invoice, validates it against the public XML schema, and places it in the JMS Invoice topic. The invoice now moves through the OPC's invoice processing workflow. Two message-driven beans, Invoice and Mail Invoice, both listen to the Invoice topic and both process an invoice placed in the topic. Mail Invoice sends an XML message that is used to generate an email message notifying the customer that the order is complete.

The sample application shows how to use an asynchronous messaging infrastructure with transition delegates to handle XML document exchanges. The process can encompass Web services. Let's look more closely at Web services and the XML document exchange between the applications.

Figure 1.15 The XML Document Flow in the BluePrints Application

Figure 1.15 shows how the OPC and Supplier exchange XML documents and use Web services. XML documents are used to pass information between these two applications. The document exchange starts with the TPASupplierOrder.xml document. Before sending this document to the Supplier, the OPC applies a stylesheet to the document to extracts its data or to convert it. Data must be extracted so that the proper steps may be taken to process the order. The OPC separates XML document validation and manipulation from Java code. The OPC also converts XML to Java objects.

Once the OPC has formatted the TPASupplierOrder.xml document to conform with the TPASupplierORder.xsd XML schema, the Supplier Order Sender JAX-RPC client sends the document to the Supplier's Web service endpoint. It reformats the document to the required schema definition for the Supplier. The Supplier Order Sender then sends the document as an attachment to the Supplier service JAX-RPC endpoint.

The endpoint receives the TPASupplierOrder.xml document. Before doing any processing to the document, the endpoint validates the document against the TPASupplierOrder.xsd XML schema, which it accesses from the OPC via a public URL. Once it determines the document is valid, it uses the XDE pattern to convert the document to its internal format. The endpoint then passes the internally formatted document to the next step in the workflow, SupplierOrderRcvr.

The order's contents determines how it moves through the Supplier workflow, and steps in the workflow communicate to each other asynchronously. Subsequent steps in the workflow do not have to validate the document because the service endpoint already converted it to the application's internal format. Once the order is filled and the invoice prepared, the Supplier sends the invoice to the OPC Web service endpoint. Its Invoice Sender JAX-RPC client follows steps similar to the OPC's Supplier Order Sender JAX-RPC client.

The service endpoint receives the document and validates it against the TPAInvoice.xsd XML schema. If valid, it sends the document to the InvoiceRcvr step, which asynchronously passes it to the next step in the invoice handling workflow.

1.8 Conclusion

This document describes those situations for which Web services provide a best solution. It illustrates how Web services may use object-centric or document-centric processing, and that their interactions may be based on RPC or asynchronous messaging. The choice of Web service design is often a matter of the existing applications or the purpose of the service. The document recommends guidelines for designing Web services to meet particular needs and for optimal implementation of these services.