Advertisement

Summary
A key aim of JAX-RPC 2.0 (JSR 224) is to simplify Java Web service development. Currently in early draft review stage in the JCP, an early access JAX-RPC 2.0 reference implementation is available from the Java Web services community site on java.net. This article provides a brief preview of writing a JAX-RPC 2.0-based Web service with that reference implementation, and highlights how Java annotations simplify Web service development.

Annotations are a relatively new Java language feature that debuted in the JDK 1.5 [see Resources]. A standard way for a developer to associate arbitrary attributes with classes, interfaces, methods, and fields, annotations are also referred to as a "metadata facility." Annotation-related language additions were introduced in A Metadata Facility for the Java Programming Language (JSR 175). Annotation attributes specific to Web service development were subsequently defined in Web Services Metadata for the Java Platform (JSR 181) [see Resources].

A key benefit of annotations is that they provide a kind of shorthand when programming. Writing Web service code, for instance, often involves defining numerous boiler-plate methods and classes, in addition to configuration elements and deployment-specific data files. Using shorthand for that boiler-plate code, and passing that shorthand to a processor that understands the Web-service-related annotations, reduces the amount of code and configuration data a programmer has to write.

JAX-RPC 2.0 prescribes a set of annotations that, when passed to the JDK's annotation processing utility, apt [see Resources], generate much of a Web service's code automatically. This brief tutorial illustrates how JAX-RPC 2.0's use of annotations allow you to create a simple, working Web service in just 15 lines of code, comments included. Only two lines in the simple example have any reference to Web service-related code in the form of a single annotation. The rest of the code focuses entirely on business logic—the arduous task of saying hello—and JAX-RPC 2.0 tools generate all other required artifacts.

The example presented here is based on code samples included in the JAX-RPC early access reference implementation distribution [see Resources]. Since this is early access code, some details are subject to change. Note that the reference implementation runs only on the Java 5 platform, as it relies on JDK 1.5 tools.

The JAX-RPC 2.0 Web service development process

In the JAX-RPC 2.0 programming model, defining a Web service may start from either Java code or a WSDL document. It is also possible to start with both a WSDL and a Java class, and define a Web service via customizations to either. When starting with a Java class, the JAX-RPC 2.0 programming model consists of these steps:

1. Define a Java service implementation.

2. Generate Web service artifacts, including a WSDL file, by applying annotations to that source file. This step is performed with the help of the apt tool, which is part of JDK 1.5.

3. Package the files created in the previous step into a WAR, along with one or more deployment descriptors. This step is a matter of creating a JAR file with a certain file layout, and is performed with the JAR tool. The resulting archive is often termed as the "raw" WAR, as opposed to the "cooked" one, created in the next step.

4. Deploy the WAR file. In this step, additional classes and configuration data is created in a "cooked" WAR. This task is aided by the wsdeploy utility, which is part of the JAX-RPC 2.0 reference implementation.

An annotated Java class

JAX-RPC 2.0 no longer requires that a Web service bean implement an interface. Thus, you do not need to declare a service interface, but can start coding a Web service directly from the service implementation. Defining the Web service may be as simple writing this Java class:

package server;

import javax.jws.WebService;

@WebService
public class HelloImpl {

  /**
   * @param name
   * @return Say hello to the person.
   */
   public String sayHello(String name) {
     return "Hello, " + name + "!";
   }
}

What turns this class into a Web service is the @WebService annotation. That annotation is one of a handful of Web-service annotations defined in the Web Services Metadata for the Java Platform specification (JSR 181). It marks this Java class as one implementing a Web service.

Note that this class does not implement an interface, and that the sayHello() method does not declare a RemoteException. A Web service implementation class's method parameters and return types must, however, be compatible with JAXB 2.0 mapping schema elements [see Resources]. As well, return types and parameters must not be Java "remote" objects—implement java.rmi.Remote—an important contrast to Java RMI and its most recent implementation, JERI (Jini Extensible Remote Invocation)[see Resources].