Web Services in Java

To develop a Web service in Java, you can either start with a WSDL document describing the Web service interface and supply the Java implementation code or start with an existing Java program and generate the corresponding WSDL document. The choice largely depends on whether you are developing a Web service interface from scratch or you already have a Java-based interface defined.

A Web service implementation can either work with raw SOAP messages or the corresponding Java objects as input. In the later case, a layer of software, commonly referred to as a SOAP engine, converts SOAP documents to Java objects. For output, the same engine converts the output objects to response SOAP document.

These conversions require XML data types defined in WSDL documents to be mapped to Java types and vice versa. JAX-RPC (Java API for XML-Based RPC) specification defines these mappings. Besides data type mappings, JAX-RPC also defines the programming model for a Web service client. A JAX-RPC client can use stub-based, dynamic proxy or DII (Dynamic Invocation Interface) programming models to invoke a Web service endpoint. In stub-based programming model, you generate client side stub classes from WSDL description and place them in the CLASSPATH of the client program. A dynamic proxy avoids separate generation of source files and their compilation, still allows the client program to invoke methods on a local instance. The DII model works at much lower level and requires the client program to pass operation and parameter names as String and parameter values as an array of Java Object instances. Refer to the JAX-RPC specification for more details on these programming models.

JAX-RPC also defines a lifecycle model for a servlet-based Web service endpoint. Keep in mind that a Web service endpoint could be developed as a Servlet or EJB and deployed in a Web container or EJB container.

JAX-RPC also defines a handler mechanism to process SOAP Header elements at both the client and service ends. This mechanism allows one or more handler objects, forming a chain of handlers, to be specified to process request and/or response SOAP messages. As we see later in this chapter, handlers expect a tree-like object representation of SOAP documents, specified by SAAJ (SOAP with Attachments API for Java) specification. In certain respects, SAAJ is similar to W3C DOM API discussed in Chapter 7, Securing the Message. However, there are significant differences: SAAJ doesn't support valid XML constructs such as DTDs (Document Type Declarations) and PIs (Processing Instructions) but supports binary attachments specified by the specification SOAP Messages with Attachments (a W3C Note). Most importantly, a SAAJ tree node is not a W3C DOM tree node.^[1] This difference does cause a problem if you want to reuse code in a handler that expects W3C DOM structure. We outline a mechanism to address this problem while writing handlers for WS Security later in the chapter.

^[1] This problem has been taken care of in SAAJ 1.2, a maintenance release made available in April 2003.

The packaging of Web service endpoint implementations and corresponding deployment descriptors are specified in the specification Web Services for J2EE (JSR 109). JAX-RPC, SAAJ and Web Services for J2EE are all going to be part of J2EE 1.4. However, we do not use any Web Services for J2EE features in this chapter.

Invocation of Web Services based on JAX-RPC runtime systems is illustrated in Figure 11-1.

JAX-RPC-compliant SOAP engines include the client and service runtime systems and tools to generate Java stubs from WSDL documents and WSDL documents from Java classes. We use Apache Axis, an open source JAX-RPC-compliant SOAP engine for our example programs.