The JavaTM Web Services Tutorial
Home
TOC 		PREV TOP NEXT

A Simple Example: HelloWorld

This example shows you how to create a service named HelloWorld. A remote client of the HelloWorld service can invoke the sayHello method, which accepts a string parameter and then returns a string.

HelloWorld at Runtime

Figure 1 shows the structure of the HelloWorld service after it's been deployed. Here's what happens at runtime:

  1. To call a remote procedure, the HelloClient program invokes a method on a stub, a local object that represents the remote service.
  2. The stub invokes routines in the JAX-RPC runtime system of the reference implementation.
  3. The runtime system converts the remote method call into a SOAP message and then transmits the message as an HTTP request.
  4. When the server receives the HTTP request, the JAX-RPC runtime system extracts the SOAP message from the request and translates it into a method call.
  5. The JAX-RPC runtime system invokes the method on the tie object.
  6. The tie object invokes the method on the implementation of the HelloWorld service.

Figure 1 The HelloWorld Example at Runtime

The application developer only provides the top layers in the stacks depicted by Figure 1. Table 1 shows where the layers originate.

Table 1 Who (or What) Provides the Layers
Layer
 		Source
HelloClient Program
 HelloWorld Service (definition interface and implementation class)
 		Provided by the application developer
Stubs
 Ties
 		Generated by the xrpcc tool, which is run by the application developer
JAX-RPC Runtime
 System
 		Included with the reference implementation

HelloWorld Files

To create service, an application developer needs to provide just a few files. For the HelloWorld example, these files are in the docs/tutorial/examples/jaxrpc/hello subdirectory:

Overview of Steps

The basic steps for developing a service definition are as follows:

  1. Code the service definition interface and implementation class.
  2. Compile the service definition code of step 1.
  3. Create the configuration file.
  4. Generate the stubs and ties.
  5. Create the deployment descriptor.
  6. Package the service definition.
  7. Deploy the service definition.

On the client side, these are the steps:

  1. Code the client.
  2. Compile the client code.
  3. Run the client.

Setting Up

Before you try out the HelloWorld example, verify that you've installed the required software and that you've set the necessary environment variables.

Required Software

For a list of the required software and supported operating systems, see the Release Notes of the Java Web Services Developer Pack.

The Java Web Services Developer Pack includes Tomcat and the ant build utility. You must use the included version of Tomcat to run the examples in this tutorial. Although you may use a separate installation of ant, we recommend that you run the included version in order to avoid confusion over incompatible versions.

Environment Variables

Before you try out the HelloWorld example, you must set some environment variables. For more information, see the Release Notes of the Java Web Services Developer Pack.

Setting build.xml Properties

If you are on a Windows system, you may skip this section.

  1. In a text editor, open the docs/tutorial/examples/jaxrpc/common/config-build.properties file.
  2. If you are on a UNIX system, change the value of the script-suffix property to sh. For Windows, the value should be bat, which is the default.
  3. Save the config-build.properties file and exit the editor.

Coding the Service Definition Interface and Implementation Class

A service definition interface declares the methods that a remote client may invoke on the service. The interface must conform to a few rules:

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

package hello;	
	
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 to code the class that implements the interface. In this example, the implementation class is called HelloImpl: 

package hello;	
	
public class HelloImpl implements HelloIF {	
	
    public String message = new String("Hello ");	
	
    public String sayHello(String s) {	
        return new String(message + s);	
    }	
}

Compiling the Service Definition Code

To compile HelloIF.java and HelloImpl.java, go to the docs/tutorial/examples/jaxrpc/hello directory and type the following: 

ant compile-server

This command places the resulting class files in the build subdirectory.

Creating the Configuration File

The config.xml file contains information needed by the xrpcc tool, which you'll run in the next section.

In the file listing that follows, note the values defined in the <service> element. The name of the service, HelloWorld, will be used as the prefix of the HelloWorldImpl class name. Generated by the xrpcc tool, the HelloWorldImpl is instantiated by the client class. (See Coding the Client.) The packageName attribute, hello, is the name of the package of the classes generated by xrpcc. In the <interface> subelement, the name attribute corresponds to the fully qualified name of the service definition interface, hello.HelloIF. The servantName attribute is the name of the interface's implementation class, hello.HelloImpl.

Here is the config.xml file: 

<?xml version="1.0" encoding="UTF-8"?>	
<configuration	
   xmlns="http://java.sun.com/jax-rpc-ri/xrpcc-config">	
   <rmi name="HelloWorldService"	
      targetNamespace="http://hello.org/wsdl"	
      typeNamespace="http://hello.org/types">	
      <service name="HelloWorld" packageName="hello">	
         <interface name="hello.HelloIF"	
         servantName="hello.HelloImpl"/>	
      </service>	
   </rmi>	
</configuration>

For more information about the syntax of the tool's configuration file, see the section Configuration File (page 521).

Note: Although required for the reference implementation of JAX-RPC, the configuration file and xrpcc tool are not defined in the specifications. Their syntax and usage may change in future releases.

Generating the Stubs and Ties

The xrpcc tool generates the stubs and ties, which are lower-level classes that enable the client and server to communicate. The tool also creates a properties file and a WSDL file. Used internally by the reference implementation, the properties file is not defined in the specifications. For information about the relationship between JAX-RPC technology and WSDL files, please refer to the JAX-RPC specifications.

In this example, the tool reads the service definition interface and the configuration file. (Alternatively, the tool may read a WSDL file instead of the interface. See Starting With a WSDL Document (page 523) for more information.)

The xrpcc tool is a script--xrpcc.sh for UNIX or xprcc.bat for Windows. To create the stubs and ties, run the tool as follows:

UNIX: 

xrpcc.sh -classpath build -both -d build config.xml

Windows: 

xrpcc.bat -classpath build -both -d build config.xml

The -both option instructs xrpcc to generate both stubs and ties. The -d option denotes the destination directory for the generated files. See the section Syntax (page 519) for the full syntax of the xrpcc tool.

Creating the Deployment Descriptor

A deployment descriptor is an XML file that provides configuration information for the Web server about the Web components (JSP pages or servlets) that are in a Web application. Because the HelloWorld service is deployed as a servlet, the deployment descriptor has some elements that are related to the service. This section describes only those elements; for more information about deployment descriptors, see the Java Servlet Specifications.

Let's take a quick look at a couple of the elements in the deployment descriptor (web.xml). First, note the HelloWorld_Config.properties value of the <init-param> element. This properties file was generated by the xrpcc tool. The name of the file is the HelloWorld service name (which was defined in the configuration file) appended by the _Config.properties string. The value of the <url-pattern> element, /jaxrpc/*, is part of the URL that designates the service's endpoint. This URL is passed to the HelloClient program as a command-line parameter. See Running the Client.

The web.xml deployment descriptor follows: 

<?xml version="1.0" encoding="UTF-8"?> 	
	
 <!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>HelloWorldApplication</display-name> 	
   <description>Hello World Application</description> 	
   <servlet> 	
      <servlet-name>JAXRPCEndpoint</servlet-name> 	
      <display-name>JAXRPCEndpoint</display-name> 	
      <description>	
         Endpoint for Hello World Application	
      </description> 	
      <servlet-class>	
        com.sun.xml.rpc.server.http.JAXRPCServlet	
      </servlet-class> 	
      <init-param> 	
         <param-name>configuration.file</param-name> 	
         <param-value>	
          /WEB_INF/HelloWorld_Config.properties	
        </param-value> 	
      </init-param> 	
      <load-on-startup>0</load-on-startup> 	
   </servlet> 	
   <servlet-mapping> 	
      <servlet-name>JAXRPCEndpoint</servlet-name> 	
      <url-pattern>/jaxrpc/*</url-pattern> 	
   </servlet-mapping> 	
   <session-config> 	
      <session-timeout>60</session-timeout> 	
   </session-config> 	
</web-app>

Packaging the Service Definition

A service definition is packaged in a Web application archive (WAR), a JAR file whose contents is defined by the Java Servlet specifications. WAR files make it easy to distribute and install (deploy) the service on various sites. In a later step, you will deploy the jaxrpc-hello.war file on Tomcat. For JAX-RPC, a WAR file contains the following files:

In addition to the preceding list of files, in the JAX-RPC reference implementation a WAR file also contains several files generated by the xrpcc tool: tie, servlet, and helper classes; and a server configuration file (HelloWorld_Config.properties).

To package the HelloWorld service definition, type the following: 

ant package

This command creates the jaxrpc-hello.war file.

Deploying the Service Definition

To deploy the service definition, you simply copy the WAR file to Tomcat's webapps directory: 

ant deploy

The first time you deploy a WAR file, Tomcat must be started. For subsequent deployments of the same WAR file, you do not need to start or restart Tomcat. Because you are about to deploy the jaxrpc-hello.war file for the first time, if Tomcat is running now, you must shut it down and then restart it.

To shut down (stop) Tomcat, type the following command in a terminal window:

UNIX: 

shutdown.sh

Windows: 

shutdown

To start Tomcat, type this command:

UNIX: 

startup.sh

Windows: 

startup

To verify that the HelloWorld service has been deployed, open a browser window and specify this URL: 

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

The browser should display these lines: 

A Web Service is installed at this URL.
 
It supports the following ports: "HelloIF"	
(http://localhost:8080/jaxrpc-hello/jaxrpc/HelloIF)

Coding the Client

The HelloClient is a stand-alone program that calls the sayHello method of the HelloWorld service. It makes this call through a stub, a local object which acts as a proxy for the remote service.

In the code listing that follows, note the names of the HelloIF_Stub and HelloWorldImpl classes, which were generated by the xrpcc tool. The HelloIF prefix matches the name of the service definition interface and the HelloWorld prefix corresponds to the service name specified in the configuration file. The HelloWorldImpl class is the implementation of a service as described in section 9.3 of the JAX-RPC specifications. The client gets a reference to the stub by calling the getHelloIF method of HelloWorldImpl.

The parameter of the _setTargetEndpoint method is a URI that denotes the address of the target service port. For details on this URI, see Running the Client.

The source code for the HelloClient follows: 

package hello;	
	
public class HelloClient {	
    public static void main(String[] args) {	
        try {	
            HelloIF_Stub stub = 	
                (HelloIF_Stub)(new HelloWorldImpl().getHelloIF());	
            stub._setTargetEndpoint(args[0]);	
            System.out.println(stub.sayHello("Duke!"));	
        } catch (Exception ex) {	
            ex.printStackTrace();	
        }	
    }	
}

Compiling the Client Code

Because the client code refers to classes generated by the xrpcc tool, be sure to run the tool before compiling the client. To compile the client, type the following: 

ant compile-client

Running the Client

To run the HelloClient program, type the following: 

ant run

The program should display this line: 

Hello Duke!

The run target executes this command: 

java -classpath <cpath> hello.HelloClient <endpoint>

We created the run-hello target because the classpath includes many JAR files. (The classpath will be simplified in a later release.) The command-line parameter for the HelloClient program is the service endpoint: 

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

The jaxrpc-hello portion of the URL is the context of the servlet that implements the HelloWorld service. This portion corresponds to the prefix of the jaxrpc-hello.war file. The jaxrpc string matches the value of the <url-pattern> element of the web.xml deployment descriptor. And finally, HelloIF is the name of the interface that defines the service.

Home
TOC 		PREV TOP NEXT