Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

Creating a Web Service with JAX-RPC

This section shows how to build and deploy a simple Web service called MyHelloService. A later section, Creating Web Service Clients with JAX-RPC, provides examples of JAX-RPC clients that access this service. The source code required by MyHelloService is in <INSTALL>/jwstutorial13/examples/jaxrpc/helloservice/.

These are the basic steps for creating the service:

  1. Code the service endpoint interface and implementation class.
  2. Build, generate, and package the files required by the service.
  3. Deploy the WAR file that contains the service.

The sections that follow cover these steps in greater detail.


Note: Before proceeding, you should try out the introductory examples in Chapter 3. Make sure that you've followed the instructions in Setting Up.


Coding the Service Endpoint Interface and Implementation Class

A service endpoint interface declares the methods that a remote client may invoke on the service. In this example, the interface declares a single method named sayHello.

A service endpoint interface must conform to a few rules:

In this example, the service endpoint interface is HelloIF.java:

package helloservice;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface HelloIF extends Remote {
    public String sayHello(String s) throws RemoteException;
} 

In addition to the interface, you'll need the class that implements the interface. In this example, the implementation class is called HelloImpl:

package helloservice;

public class HelloImpl implements HelloIF {

    public String message ="Hello";

    public String sayHello(String s) {
        return message + s;
    }
} 

Building the Service

To build MyHelloService, in a terminal window go to the <INSTALL>/jwstutorial13/examples/jaxrpc/helloservice/ directory and type the following:

ant build 

The preceding command executes these ant tasks:

compile-service

This task compiles HelloIF.java and HelloImpl.java, writing the class files to the build subdirectory.

generate-sei-service

The generate-sei-service task runs the wscompile tool, which defines the service by creating the model.gz file in the build directory. The model.gz file contains the internal data structures that describe the service. The generate-sei-service task runs wscompile as follows:

wscompile -define -d build -nd build 
-classpath build config-interface.xml -model build/model.gz 

The -define flag instructs the tool to read the service endpoint interface and to create a WSDL file. The -d and -nd flags tell the tool to write output to the build subdirectory. The tool reads the following config-interface.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
  xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  <service 
      name="MyHelloService" 
      targetNamespace="urn:Foo" 
      typeNamespace="urn:Foo" 
      packageName="helloservice">
      <interface name="helloservice.HelloIF"/>
  </service>
</configuration> 

The config.xml-interface file tells wscompile to create a model file with the following information:

(If you are familiar with SOAP and WSDL, note that by default the service will be rpc/encoded. For doc/literal, see Advanced JAX-RPC Examples.)

package-service

The package-service target runs the jar command and bundles the files into a WAR file named dist/hello-portable.war. This WAR file is not ready for deployment because it does not contain the tie classes. You'll learn how to create a deployable WAR file in the next section. The hello-portable.war contains the following files:

WEB-INF/classes/hello/HelloIF.class
WEB-INF/classes/hello/HelloImpl.class
WEB-INF/jaxrpc-ri.xml
WEB-INF/model.gz
WEB-INF/web.xml 

The class files were created by the compile-service target discussed in a previous section. The web.xml file is the deployment descriptor for the Web application that implements the service. Unlike the web.xml file, the jaxrpc-ri.xml file is not part of the specifications and is implementation-specific. The jaxrpc-ri.xml file for this example follows:

<?xml version="1.0" encoding="UTF-8"?>
<webServices
    xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd"
    version="1.0"
    targetNamespaceBase="urn:Foo"
    typeNamespaceBase="urn:Foo"
    urlPatternBase="/ws">

    <endpoint
        name="MyHello"
        displayName="HelloWorld Service"
        description="A simple web service" 
        interface="helloservice.HelloIF"  
        model="/WEB-INF/model.gz"
        implementation="hello.HelloImpl"/> 
 
    <endpointMapping
        endpointName="MyHello"
        urlPattern="/hello"/>

</webServices> 

Several of the webServices attributes, such as targetNamespaceBase, are used in the WSDL file, which is created by the process-war task described in the next section. (WSDL files can be complex and are not discussed in this tutorial. See Types Supported By JAX-RPC). Note that the urlPattern value (/hello) is part of the service's URL, which is described in the section Verifying the Deployment).

process-war

This ant task runs the wsdeploy tool as follows:

wsdeploy -o dist/hello-jaxrpc.war 
dist/hello-jaxrpc-portable.war 

The wsdeploy tool performs these tasks:

Note that the wsdeploy tool does not deploy the service; instead, it creates a WAR file that is ready for deployment. In the next section, you will deploy the service in the hello-jaxrpc.war file that was created by wsdeploy.

Deploying the Service

Type the following command:

ant deploy 

Verifying the Deployment

To verify that the service has been successfully deployed, open a browser window and specify the service endpoint's URL:

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

The browser should display a page titled Web Services, which lists the port name MyHello with a status of ACTIVE. This page also lists the URL of the service's WSDL file.

The hello-jaxrpc portion of the URL is the context path of the servlet that implements the HelloWorld service. This portion corresponds to the prefix of the hello-jaxrpc.war file. The /hello string of the URL is the alias of the servlet. This string matches the value of the urlPattern attribute of the jaxrpc-ri.xml file. Note that the forward slash in the /hello value of urlPattern is required. For a full listing of the jaxrpc-ri.xml file, see the section, package-service.

Undeploying the Service

At this point in the tutorial, do not undeploy the service. When you are finished with this example, you can undeploy the service by typing this command:

ant undeploy 
Divider
Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.