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.

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:

• 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.

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