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>/jwstutorial12/examples/jaxrpc/helloservice/.

Code the service endpoint interface and implementation class.

Build, generate, and package the files required by the service.

Deploy the WAR file that contains the service.

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.

It extends the java.rmi.Remote interface.

It must not have constant declarations, such as public final static.

The methods must throw the java.rmi.RemoteException or one of its subclasses. (The methods may also throw service-specific exceptions.)

Method parameters and return types must be supported JAX-RPC types. See the section Types Supported By JAX-RPC.

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>/jwstutorial12/examples/jaxrpc/helloservice/ directory and type the following:

compile-service

generate-sei-service

package-service

process-war

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:

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:

The service name is MyHelloService.

The WSDL namespace is urn:Foo. (To understand this namespace, you need to be familiar with WSDL technology. See Further Information)

The classes for the MyHelloService are in the helloservice package.

The service endpoint interface is helloservice.HelloIF.

(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

Reads the dist/hello-jaxrpc-portable.war file as input

Gets information from the jaxrpc-ri.xml file that's inside the hello-jaxrpc-portable.war file

Generates the tie classes for the service

Generates a WSDL file named MyHelloService.wsdl

Packages the tie classes, the MyHelloService.wsdl file, and the contents of hello-jaxrpc-portable.war file into a deployable WAR file named dist/hello-jaxrpc.war

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

Verifying the Deployment

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

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: