Leading-Edge Java
Three Minutes to a Web Service
Write a Web service in 15 lines of code with JAX-RPC 2.0 Early Access
by Frank Sommers
May 23, 2005

<< Page 3 of 3

Making a "raw" WAR

Next, we need to package these artifacts into a WAR file, along with one or more deployment descriptors. J2EE deployment descriptors may convey information not only to an application server, but possibly to other tools and even to people interacting with the service.

For a JAX-RPC 2.0 Web app, a deployment descriptor bundled in the WAR should be called jaxrpc-ri.xml. This file conveys both runtime information about a Web service, and also communicates information to a deployment compiler tool discussed in the final deployment step. The content of the jaxrpc-ri.xml file may be as simple as the following, fashioned after a sample in the JAX-RPC 2.0 reference implementation:

<?xml version="1.0" encoding="UTF-8"?>

<webServices
   xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd"
   version="1.0"
   targetNamespaceBase="http://artima.com"
   typeNamespaceBase="http://artima.com"
   urlPatternBase="/ws">

  <endpoint
    name="sayhello"
    displayName="A Java Web service"
    interface="server.HelloImpl"
    implementation="server.HelloImpl"
    wsdl="/WEB-INF/HelloImplService.wsdl"/>

  <endpointMapping
    endpointName="sayhello"
    urlPattern="/sayhello"/>

</webServices>

This descriptor defines a single endpoint, sayhello, and maps that endpoint to the URL pattern /sayhello. Note that the service interface and implementation refer to the same class.

To make this WAR file work inside a servlet container, you would also want to package a web.xml file in the WAR, too:

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>
  <display-name>Hello, JAX-RPC 2.0!</display-name>
  <description>A hello, world, Web service.</description>
  <session-config>
    <session-timeout>60</session-timeout>
  </session-config>
</web-app>

Creating a WAR file is easily accomplished with the Ant war task. Note that in the resulting Web archive, the schema file is located in the Web app's root directory so it can be downloaded by clients that require access to the WSDL. The WSDL itself will be served up by the JAX-RPC servlet, which will attach the service endpoint address to the WSDL at runtime. The following is the structure of the resulting WAR:

schema1.xsd
WEB-INF/web.xml
WEB-INF/jaxrpc-ri.xml
WEB-INF/HelloImplService.wsdl
WEB-INF/classes/server/HelloImpl.class
WEB-INF/classes/server/jaxrpc/SayHello.class
WEB-INF/classes/server/jaxrpc/SayHello.java
WEB-INF/classes/server/jaxrpc/SayHelloResponse.class
WEB-INF/classes/server/jaxrpc/SayHelloResponse.java

"Cooking" the WAR

The final step is to deploy the Web service WAR archive. That requires "cooking" the initial WAR: modifying the deployment descriptor, and adding several runtime artifacts to facilitate the XML-Java data binding.

The JAX-RPC 2.0 reference implementation includes the wsdeploy tool that operates an a single "raw" WAR file, performs the deployment tasks on elements in that WAR, and produces a new, deployment-ready, or "cooked," WAR file.

wsdeploy reads the jaxrpc-ri.xml inside the WAR, and then invokes another JAX-RPC tool, wscompile with an option to generate deployment-time Web service implementation artifacts. Running wsdeploy is as simple as invoking the wsdeploy Ant task, which is also part of the JAX-RPC 2.0 reference implementation. I will not discuss the individual files generated for the deployment-ready WAR, partly because they are dependent on the current, early-access release of the reference implementation.

Deploying the Web service

The WAR "cooked" by wsdeploy can be copied to the webapps directory of a servlet container. The Web service is now ready to be used.

In order for a servlet container to serve JAX-RPC 2.0-based Web services, all JAR files from the reference implementation must be copied to a library directory the servlet engine looks in for classes. With Jakarta Tomcat, for instance, you can copy the JAX-RPC reference implementation JARs to the /shared/lib directory.

The JAX-RPC servlet provides a summary page for the newly installed Web service. For this example app, that summary page can be accessed at the following URL:

http://localhost:8080/jaxrpc-hello/hello
(substitute the host name, the port number, and the context root with appropriate values for your server). The following Web page is displayed at that URL:

Figure 1. Web service summary displayed by the JAX-RPC 2.0 servlet.

The Web service's WSDL, in turn, is accessible via this URL, which is where clients would download that WSDL. Note that clients would also need the XML schema file imported in the WSDL, which is why that schema file had to reside in the Web archive's root:

http://localhost:8080/jaxrpc-hello/hello?WSDL

If you inspect the resulting WSDL with a browser, you will note that the WSDL correctly indicates the service's endpoint address:

<service name="HelloImplService">
	<port name="HelloImplPort" 
           binding="tns:HelloImplBinding">
         <soap:address 
            location="http://localhost:8080/jaxrpc-hello/hello"/>
      </port>
</service>

Summary

This brief tutorial demonstrated that JAX-RPC 2.0's use of annotations greatly simplifies writing a Web service. Typing in the example code, and running the Ant tasks defined in JAX-RPC 2.0, should yield a fully working Web service in less than three minutes. All the while, you can concern yourself with the Java code that implements the business logic, and let JAX-RPC 2.0 tools handle the rest of the Web-service-related classes and files. Download the JAX-RPC 2.0 reference implementation for an example of how to write Web service client for a similar Web service.

Talk back!

Have an opinion about JAX-RPC 2.0's programming model? Discuss this article in the Articles Forum topic, Three Minutes to a Web Service.

Resources

The JAX-RPC 2.0 reference implementation and community Web site
https://jaxrpc.dev.java.net/

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: Java API for XML-Based RPC (JAX-RPC) 2.0
http://www.jcp.org/en/jsr/detail?id=224

Annotation Processing Tool (apt)
http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html

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.

<< Page 3 of 3


	Web Artima.com