8.3. Endpoint Design Issues

The adventure builder developers considered a set of issues when designing a Web service. These issues encompassed such areas as the development approach for the Web service interface, the type of endpoint to use, the granularity of the service, the types of parameters to pass to the interface, the structure of the service's interaction and business processing layers, delegating to the business logic, the types of clients accessing the service endpoint, and deployment issues.

Earlier chapters addressed many of these issues. Here we try to show how such decisions are made in a real-world, comprehensive application. Note that this chapter bases its discussion using three of adventure builder's Web service interfaces:

8.3.1. Web Service Interface Development Approach

When you implement a Web service, one of the first decisions you must make is the approach to use for developing the service interfaces. We followed the guidelines suggested in Chapter 3, particularly those in “Designing the Interface” on page 66. Let's look at the Web service interactions between the customer Web site and the order processing center, and also between the order processing center and the suppliers. Different issues pertain to the design of these service interfaces.

Because the same organization develops and controls the customer Web site and the order processing center, it is easy to propagate to the Web site module changes to the Web service interface that the order processing center provides to the Web site. Since we have control over all parties that have access to this Web service interface, the issue of stability of the interface is less important. Because it is easier, we opted to use the Java-to-WSDL approach to design and implement the Web service interfaces between the Web site and the order processing center.

The Web service interaction between the order processing center and the suppliers is a business-to-business interaction. Any order processing center changes to the interface affect many different suppliers. A stable interface also enables the participants to evolve in different ways. It is of paramount importance with such interactions that the interface between the communicating entities be stable. Since legal issues (see “Handling XML Documents in a Web Service” on page 105 for information about legal issues) may be important with business-to-business interactions, exchanged business documents should have an agreed-upon format and content, and for this it is best to use documents with existing standard schemas. For these reasons we used the WSDL-to-Java approach for the Web service interface between the order processing center and its suppliers.

• Although somewhat more complex, the WSDL-to-Java approach satisfies the overriding need for a stable Web service interface.

• To ensure that the WSDL-to-Java approach did not break interoperability, use various WSDL and schema editing tools to ensure that the WSDL and other artifacts comply with WS-I standards.

8.3.2. Endpoint Type Considerations

After you settle on the service interface development approach, you need to choose the type of endpoint for the interface. Recall from “Choice of the Interface Endpoint Type” on page 67 that you may implement a Web service endpoint either as a JAX-RPC service endpoint on a Web tier or as an EJB service endpoint on an EJB tier. The choice of endpoint type is primarily based on whether or not the business logic uses enterprise beans. If the business logic does use enterprise beans, it is often convenient to use an EJB service endpoint. If the application is primarily Web tier based, then it is best to use a JAX-RPC service endpoint.

The order processing center module exposes all of the Web services in the adventure builder application. Since the order processing center is implemented with a set of enterprise beans, it makes sense to implement these Web services as EJB service endpoints. Using a JAX-RPC service endpoint would introduce a Web layer that acts merely as a proxy, directing requests from the Web tier to the EJB tier and adding no value.

Using EJB service endpoints has some additional minor advantages as well. You can declare an EJB method to be transactional, resulting in the method body executing within a transaction. We found this useful since the order processing center requires transactional access to the database. An EJB service endpoint also allows method-based security controls, which is useful if you want certain methods to be publicly accessible but other methods to be restricted to authenticated users. You need to do additional work to get the equivalent capabilities in a JAX-RPC service endpoint.

8.3.3. Granularity of Service

It is important to design the service interface with the proper level of granularity. Because we want our application to perform well, we use coarse-grained interfaces for the Web services. When adding a Web service interface to existing applications, you want to identify the Web service interfaces that can be exposed. To do so, it is useful to look at the session bean-based application façades. Generally, it is not a good idea to convert each such application façade session bean into a Web service interface. You should design Web services to be more coarse grained than individual session beans. A good way to achieve a coarse-grained interface is to design the Web service around the documents it handles, since documents are naturally coarse grained. The adventure builder application applies these principles by exposing Web services that primarily exchange well-defined documents—purchase orders and invoices. These Web services may call multiple session bean methods to implement the services' business logic.

8.3.4. Passing Parameters as Documents or Java Objects

As already noted, a client invokes a service's functionality by calling the appropriate method on the service interface and passing the expected parameters. Developers must decide on the type of parameters passed to the Web service interfaces, and the parameter types determine the style of the interface. Parameters may be passed as either JAX-RPC value types or XML documents, which are represented as SOAPElement objects in the service interface. See “Parameter Types for Web Service Operations” on page 72 and “Exchanging XML Documents” on page 107 for detailed discussions on these choices. Note that since on the wire everything is in XML, the JAX-RPC value types are automatically mapped to their equivalent XML representations.

Passing XML documents raises different issues than passing Java objects. XML documents involve a certain amount of complexity, since the requestor must build the document containing the request and the receiver must validate and parse the document before processing the request. However, XML documents are better for addressing the business-to-business transaction considerations.

We used object parameters for the service interfaces between the customer Web site and the order processing center applications. Since both are contained within one enterprise, these services do not encompass business-to-business functionality. Moreover, the parameters map to specific document types that can be mapped easily to their equivalent JAX-RPC value types. Using these JAX-RPC value types eliminates the complexity of creating and manipulating XML documents.

Code Example 8.1 is an example of a Java interface for the order tracking service. It has one method, getOrderDetails, which expects a String argument and returns a Java Object, OrderDetails. A client submits an order identifier to retrieve information about an order, which is much simpler than having the client submit an XML document containing the same information.

Code example 8.1. Interface Using Java Parameters

public interface OrderTrackingIntf extends Remote {
    public OrderDetails getOrderDetails(String orderId)
                 throws OrderNotFoundException, RemoteException;
}

Choosing the return value type is not as straightforward. The getOrderDetails method returns specific order details, such as user name and shipping address, rather than the complete purchase order. It is possible to return this information as either a Java Object or in an XML document. We chose to return the order details in a OrderDetails Java Object since the details returned to the client—user identifier, addresses, and so forth—map to a specific schema. Hence, the service interface can create and use the equivalent JAX-RPC value types. The order fulfillment Web service interface, PurchaseOrderIntf, is designed similarly. (See Code Example 8.1.)

The order processing center service interface with suppliers exchanges XML documents rather than Java objects. Since suppliers are external to the enterprise, the service interface must be stable. Legal issues require exchanging business documents that conform to well-defined schemas. There are times when ensuring a stable interface is worth more than the simplicity of passing Java objects and the complexity of handling XML in the application code. The service interface may also need to support multiple document types in its methods.

Code Example 8.2 illustrates a JAX-RPC interface generated from the WSDL description where the order processing center acts as a client of a supplier and an XML document passes between them. To fulfill part of the customer's order, the order processing center module sends a purchase order to the supplier's Web service. For example, to fulfill a customer's travel request, the order processing center sends an order contained in an XML document to the airline supplier's Web service.

Code example 8.2. Interface Using XML Documents as Parameters

public interface AirlineReservationIntf extends Remote {
   public String submitDocument(SOAPElement reservationRequest)
                                        throws RemoteException;
}

The service has a single method, submitDocument, which takes a reservation request document and returns a status. The service receives the request, does some preprocessing—such as validation of the document and security checks—then stores the request in a database for later processing.

Keep in mind that when a Web service method passes different types of XML documents, the WSDL description should use the generic type anyType to indicate the type of the method's parameters. Code Example 8.2 shows how anyType is mapped to SOAPElement in the generated JAX-RPC interface. Because the WSDL does not have the information to describe these documents, a separate schema holds the complete description of the documents. You need to publish the schemas for all documents that are exchanged. Publishing entails making the schemas available to clients at some known URL or registry.

On the Java platform, it is best to send an XML document as a javax.xml.transform.Source object. (See the discussion in “Java Objects as Parameters” on page 73 and “XML Documents as Parameters” on page 76.) However, we chose to send the XML document as a SOAPElement object because the WS-I Basic Profile does not yet support Source objects. (For more information, see “Interoperability” on page 86.)

8.3.5. Layering the Service

Normally, it's best when designing a service to separate the service's interaction layer from the business logic processing layer. This is especially true when an incoming request uses a different data model than the data model used by the business logic. Recall that a service may divide its processing into layers if it handles requests that require significant preprocessing or when there is extensive mapping between the internal data model and the incoming data.

The order fulfillment and order tracking Web service interfaces, since they use parameters that are objects, have no need for document validation or transformation. For both, there is minimal mapping from one data model to another, since the passed data mirrors for the most part the internal data model. Thus, both services do very minimal preprocessing of requests. As a result, we chose to merge the interaction and processing layers for these services.

Consider the order tracking Web service, which receives an order identifier as input and returns some order details. Since little preprocessing is required, the interaction and processing layers are merged into one layer. Although merged into one layer, the order tracker Web service interface does not expose the internal data model. It is important to keep the Web service interface from being tightly coupled to the internal data model, and not exposing the internal data model through the service interface accomplishes this. By avoiding tight coupling, we can change the internal data model without affecting the Web service interface and clients.

Instead, we created an OrderDetails Java object to hold the data in the service interface, thus removing the need to change the order tracker interface if the internal data model changes. The client's view of the OrderDetails object through the order tracker interface remains the same regardless of changes to the data model. See Figure 8.5.

The Web service interfaces between the order processing center and the suppliers must validate and transform incoming XML documents to the internal data model before processing the document contents. We chose to do the validation and transformation in the interaction layer of the service before delegating the request to the processing layer.

8.3.6. Delegating to Business Logic

After receiving and preprocessing (if required) a request, the endpoint must next map the request to the appropriate business logic and delegate it for processing. Recall from “Delegating Web Service Requests to Processing Layer” on page 92 that much of this decision hinges on whether the request is processed synchronously or asynchronously.

The order tracking Web service interface uses a synchronous interaction for handling requests—processing is fast and a client waits for the response. Thus, the service interface maps a request to the appropriate business logic and immediately returns the results. adventure builder's Web services for processing the order workflow are asynchronous in nature since their business processing may be time consuming to complete and the client does not wait for the response. For these other Web service interactions—client submitting purchase order to the order processing center, order processing center placing orders with the suppliers, suppliers invoicing the order processing center—the service interfaces pre-process the requests and then delegate the request to the business logic. The interfaces use JMS messages to send the requests to a JMS queue associated with the business logic.

8.3.7. Client Considerations

For a client, the principal architectural consideration is choosing the best JAX-RPC service interface API to use to access the Web service. Clients can use a stub approach, dynamic proxies, or dynamic invocation interfaces (DII). When choosing a particular API, it is important to consider client requirements such as coupling, portability, the ability to dynamically locate and call services at runtime, and ease of development. Refer to Chapter 5 for more details.

Adventure builder's Web service clients use stubs, which is the simplest of the three modes. The stub mode requires the WSDL document along with the JAX-RPC mapping file to generate a set of proxies at development. A client at runtime uses these generated proxies to access a service. The stub mode of proxy generation provides the client with a tightly coupled view of the Web service, and it is a good choice when the service endpoint interface does not change.

With stubs, adventure builder uses the javax.xml.rpc.Service interface getPort method to access the Web service. Using this method removes port and protocol binding dependencies on the generated service implementation classes. As a result, it improves the portability of the client code since the client does not have to hard code a generated stub class. See “Locating and Accessing a Service” on page 219.

We also implemented exception handling from the client's perspective. To do this, we examined the interface generated from the WSDL file to see what possible exceptions the service might throw and then decided how to handle individual exceptions. See “Handling Exceptions” on page 230. The customer Web site, when it catches exceptions thrown by the order tracking service, maps the exceptions to client-specific exceptions. The client application detects these exceptions and redirects the user to an appropriate error page.

8.3.8. Publishing Web Service Details

A Web service endpoint is described by its WSDL file, and clients of the service need access to the WSDL to obtain basic information about the service. One way to disseminate this information to clients is to publish the WSDL files in a registry, if the service is open to the general public. Or, you can arrange a common location for the WSDL file that is known only to selected clients. You also must decide how to expose other details pertinent to the service, such as the business document schemas.

We decided to make the adventure builder Web services available in a well-known location, which clients can obtain from the deployment environment. These Web service interfaces are meant for specific business interactions between specific entities rather than for consumption by the general public. For this reason, we decided against publishing the services in a registry. Similarly, we decided to place the business document schemas at a well-known location, from which intended clients use these schemas.