A Brief Review of JAX-RPC 2.0

With a myriad of new Java features currently winding their way through the Java Community Process (JCP), many proposed technologies and APIs may appear at first as extra "fluff," threatening to make Java overly complex. After all, you've been writing Java code for years—how could learning those new APIs possibly make your life easier?

A deeper look at some new JSRs, however, reveals that sometimes more is less: Some new and proposed APIs enable us to write less code, chiefly by automating a lot of tedious work. The effort of learning those new Java features pays dividends by making us more productive. In this article, I will show how new JDK 1.5 features, such as annotations and the concurrency API, can make writing Java web services much simpler.

Simplifying Web services programming

When it comes to tedious work, writing Web services seem destined to occupy an especially painful spot. Since a Web service is a combination of Java code, configuration files, and deployment-time options, managing all those artifacts takes time and effort away from focusing on code that provides the business benefits, often the Web service's sole raison d'etre.

Last month, the JAX-RPC 2.0 project on java.net released an early access version [see Resources] of the reference implementation of the Java API for XML-Based RPC (JAX-RPC) 2.0 specification (JSR 224), currently in early draft review stage in the JCP. Among JAX-RPC 2.0's key aims: vastly simplify Web service development.

An exciting feature of JAX-RPC 2.0 is that it achieves a simpler Web services programming model by taking advantage of new J2SE 1.5 capabilities, especially metadata and annotations. JAX-RPC 2.0 also aligns the Java Web services programming model with related Java standards that have emerged since the initial JAX-RPC 1.0 release.

While this article focuses on new JAX-RPC 2.0 features, a companion article, "Three Minutes to a Web Service," illustrates JAX-RPC 2.0's annotation-based Web services programming model, and shows how to create a Web service with just 15 lines of code.

Note of caution: JAX-RPC 2.0 is still in early draft release. Both the specification and reference implementation are subject to change. When this article refers to JAX-RPC 2.0, those references mean the early draft specification available at the time of this writing.

Standards alignment

With the advent of XML-based Web services in the late nineties, Java needed an API for XML-based remote method calls, mainly to facilitate Java interoperability with SOAP-based Web services. To provide a standard Java XML RPC API, JSR 101 was accepted into the JCP in January 2001, and work on JAX-RPC 1.0 started shortly thereafter [see Resources]. While JAX-RPC version 1.0 delivered initial XML Web services support in Java, the version 1.1 maintenance release incorporated the WS-I Basic Profile into JAX-RPC [see Resources].

A key requirement of any XML-based remote method call system is to translate elements of a programming language's type system into an on-the-wire XML-representation, and in the reverse direction, into a language-specific data binding. A standard for Java-XML data binding had been in the works since 1999 (JSR 31), but would not produce an accepted specification until March 2003, due in part to the complexity of defining a general-purpose XML-Java mapping for a large schema [see Resources].

Since data binding was a necessary component of JAX-RPC, the initial JAX-RPC expert group decided to devise Java-XML bindings specific to the JAX-RPC specs, supporting a smaller XML schema needed to process Web service WSDL definitions. That allowed JAX-RPC to become an approved Java standard by mid-summer, 2002. JAX-RPC was subsequently incorporated into the Java Web services stack, and earned its way into a key part of J2EE 1.4 [see Resources]. But that decision also meant, in effect, two standards for turning Java data into XML.

JAX-RPC 2.0 remedies that duplication, and delegates Java-XML data binding to the newly emerging JAXB 2.0 standard (JSR 222) developed concurrently with JSR 224 [see Resources]. "The WSDL-based data binding worked well in the early stages," says Roberto Chinnici, a Sun Microsystems Senior Staff Engineer and JAX-RPC 2.0 spec co-lead. "Independently, JAXB defined data bindings for a much larger set of schemas. We now integrate with JAXB, and are a JAXB client. [On top of JAXB], we add support to do remote invocation. These two JSRs are now aligned."

Service annotations and customization

When creating a Web service, a developer works with a handful of classes and configuration files:

• a WSDL document that describes the Web service's interface in XML,
• the service endpoint interface (SEI) that defines that Web service interface in the Java language,
• a service implementation bean, or service bean, that implements the Java service interface,
• and one or more deployment descriptors that tie the WSDL, the Java interface, and the service bean together.

JAX-RPC 2.0 significantly reduces the complexity of maintaining these artifacts with the help of the JDK 1.5 annotations capability. (Annotations are defined in JSR 175, A Metadata Facility for the Java Programming Language, and JSR 181, Web Services Metadata for the Java Platform [see Resources].) With JAX-RPC 2.0, you need only define a service implementation class, apply annotations to it, and run the class through tools provided in the JAX-RCP 2.0 reference implementation to generate other required Web service artifacts. The result is a dramatically simplified Web service programming model that lets you focus almost exclusively on a Web service's business logic, and relegates other Web service development chores to infrastructure-level tools. (See the companion article, "Three Minutes to a Web Service," for an example.)

In addition to facilitating developer ease, annotations provide more control over how Java-to-WSDL mapping occurs. Prior versions of JAX-RPC tools mapped Java constructs to WSDL in an implementation-specific way, often resulting in awkward class and method names, for instance. You can now associate specific annotations with Java code to affect the resulting WSDL.

While annotations govern the Java-to-WSDL translation, customizations give a developer control over WSDL-to-Java conversion. Such customizations are specified via binding declarations that mimic a similar customization capability of JAXB 2.0. JAX-RPC 2.0 binding declarations let you specify the package, class, and method names created from a WSDL document, and may be specified either inside a WSDL document inline, or via external files.

No longer just for SOAP

While earlier JAX-RPC specifications aimed to remain independent of a specific transport protocol, in reality they were closely aligned with SOAP. "In JAX-RPC 1.1, we tried to be SOAP-independent, but we ended up having [references] to SOAP types. With JAX- RPC 2.0, what's generated from WSDL is really independent of binding details," says Chinnici, the JAX-RPC 2.0 spec co-lead who also led the earlier JAX-RPC efforts.

The SOAP decoupling is part of the new JAX-RPC 2.0 handler framework that defines both logical and protocol-level handlers. A protocol handler can access the entire XML message transmitted in a JAX-RPC call, while logical handlers have no knowledge of the underlying protocol used to transmit a message, and can access a message's payload only.

"You can plug various handlers in [at deployment time], and create and configure a handler chain [to process JAX-RPC calls]," explains Chinnici. "There are configuration files, for instance, for SOAP message handlers. You would use those configuration files, instead of using the API, to create such handler chains." That approach provides flexibility in service deployment.

For service clients that require access at the XML message level, JAX-RPC 2.0 provides a new Dispatch API as well. At the center of that API, which replaces the old Call API, is the Dispatch interface that can be thought of as a conduit for a method call request. Dispatch enables, for instance, intercepting and examining a method dispatch request.

Asynchronous operations and tools support

The JDK 1.5 concurrency API (JSR 166) defines a Future interface to represent the results of an asynchronous operation [see Resources]. Asynchronous operations come in handy with Web services. "If you are calling on [the] Amazon [Web service], for instance, that Web service may not reply right away. Waiting for such replies is hard in a separate thread. What we're doing in JAX-RPC 2.0 is [that] when a tool maps the WSDL to Java, that tool can generate an asynchronous version of the code," says Chinnici. Asynchronous operations are supported via both polling and a callback mechanism. Examples for generating asynchronous service clients are included in the reference implementation's code samples.

One of the key aspects of JAX-RPC 2.0 is that it standardizes mechanisms that previously varied between each JAX-RPC implementation and tool. Developer tools, for instance, routinely offer customizations of WSDL generation from Java code, but such customizations were specific to each tool.

Defining standard ways to provide more Web service development flexibility will benefit tool vendors as much as developers. "By standardizing those mechanisms, we can get much better tool support much faster," says Sun's Chinnici. "Overall, our hope is that developers will find it a lot simpler to develop Web services with this new JAX-RPC version."

Summary

Web services have not taken off as quickly as once predicted. That lag may partly be due to the complexity of developing and deploying XML Web services. JAX-RPC 2.0 promises to vastly simplify Web service development for Java, chiefly by exploiting recently available Java features.

While the utilities in the JAX-RPC 2.0 reference implementation are very useful by themselves, many JAX-RPC 2.0 features will truly shine when incorporated in developer tools. JAX-RPC 2.0-aware developer tools will finally make developing and deploying a Java Web service almost as easy as writing a simple Java class.

"Three Minutes to a Web Service," is a companion article that illustrates how annotations can simplify Web service creation:
http://www.artima.com/lejava/articles/threeminutes.html

JAX-RPC Project Home on java.net:
https://jax-rpc.dev.java.net/

You can download the JAX-RPC 2.0 early access release from java.net:
https://jax-rpc.dev.java.net/jaxrpc20-ea/

JSR 31: XML Data Binding Specification
http://www.jcp.org/en/jsr/detail?id=31

JSR 101: JavaTM APIs for XML based RPC
http://www.jcp.org/en/jsr/detail?id=101

JSR 109: Implementing Enterprise Web Services
http://www.jcp.org/en/jsr/detail?id=109

JSR 166: Concurrency Utilities
http://www.jcp.org/en/jsr/detail?id=166

JSR 175: A Metadata Facility for the Java Programming Language
http://www.jcp.org/en/jsr/detail?id=175

JSR 181: Web Services Metadata for the Java Platform
http://www.jcp.org/en/jsr/detail?id=181

JSR 222: Java Architecture for XML Binding (JAXB) 2.0
http://www.jcp.org/en/jsr/detail?id=222

JSR 224: JavaTM API for XML-Based RPC (JAX-RPC) 2.0
http://www.jcp.org/en/jsr/detail?id=224

Web Services Interoperability Organization Basic Profile Version 1.0
http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html

Talk back!

Have an opinion? Be the first to post a comment about this article.

About the author

Frank Sommers is a Senior Editor with Artima Developer. He also serves as chief editor of the Web zine ClusterComputing.org, the IEEE Technical Committee on Scalable Computing's newsletter, and is an elected member of the Jini Community's Technical Advisory Committee. Prior to joining Artima, Frank wrote the Jiniology and Web services columns for JavaWorld.