The JavaTM Web Services Tutorial
Home
TOC
PREV TOP NEXT

A Simple Example: HelloWorld

This example shows you how to use JAX-RPC to create a Web 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 9-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 9-1 The HelloWorld Example at Runtime

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

Table 9-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 a service with JAX-RPC, 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:

Setting Up

Before you try out the HelloWorld example, you must perform these tasks:

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 problems caused by 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.

Editing common/build.properties

Several of the ant targets that you will run in this chapter rely on values that are set in the common/build.properties file. Before running these targets, you must first make some changes to this file.

  1. In a text editor, open the docs/tutorial/examples/jaxrpc/common/build.properties file.
  2. Change the username and password values to the ones that you entered on the Create Tomcat User dialog of the installer. If you don't remember these values, go to the <JWSDP_HOME>/conf/tomcat-users.xml file and examine the user element that has a roles attribute with the value manager.
  3. If you are on a Windows system, you may skip this step. 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.
  4. Save the common/build.properties file and exit the editor.

Starting Tomcat

To start Tomcat, type the following command in a terminal window:

UNIX:

startup.sh
 

Windows:

startup
 

To shut down (stop) Tomcat, type this command:

UNIX:

shutdown.sh
 

Windows:

shutdown
 

Building and Installing the Service

The basic steps for developing a JAX-RPC Web service 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 ties.
  5. Create the deployment descriptor.
  6. Install the service on Tomcat.

The sections that follow describe each of these steps in more detail.

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/shared 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.


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 Ties

Ties are lower-level classes on the server that enable it to communicate with the client. (On the client, the corresponding classes are called stubs.) To generate the ties, you run the xrpcc tool. 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 Specification.

In this example, the xrpcc 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 for more information.)

The xrpcc tool is a script: xrpcc.sh for UNIX or xprcc.bat for Windows. To create the ties, go to the docs/tutorial/examples/jaxrpc/hello directory and run the tool as follows. (Type the command on a single line.)

UNIX:

xrpcc.sh -classpath build/shared -server -d build/server 
config.xml
 

Windows:

xrpcc.bat -classpath build\shared -server -d build\server 
config.xml
 

The -classpath option refers to the directory into which the server files were compiled. The -d option denotes the destination directory for the generated files. See the section Syntax for the full syntax of the xrpcc tool.

As a shortcut, instead of running the xrpcc command as shown previously, you can simply type the following:

ant xrpcc-server
 

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 Specification.

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>
 

Installing the Service

The HelloWorld service is implemented as a Web application that runs on Tomcat. To install the Web application, go to the docs/tutorial/examples/jaxrpc/hello directory and type the following command:

ant install
 

If this command fails, you should verify that you followed the instructions in Editing common/build.properties and Starting Tomcat.

In this example, the install target depends on another target (setup-web-inf), which copies the class files and the deployment descriptor (web.xml) to the build/WEB-INF directory. The contents of the WEB-INF directory match the contents of the WAR file described in Optional: Packaging the Service.

Verifying the Installation

To verify that the HelloWorld service has been installed, 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)
 

(For an explanation of the elements in the URL, see Running the Client.)

You can use this approach to verify the deployment of any service that is created with the JAX-RPC reference implementation. For example, to verify the service documented in A DII Client Example, you would specify the following URL:

http://localhost:8080/jaxrpc-dynamic/jaxrpc
 

Removing the Service

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

ant remove
 

For information about reloading the service, see the section Iterative Development.

Building and Running the Client

To develop a JAX-RPC client, you follow these steps:

  1. Generate the stubs.
  2. Code the client.
  3. Compile the client code.
  4. Package the client classes into a JAR file.
  5. Run the client.

The following sections describe each of these steps.

Generating the Stubs

In addition to generating the ties for the server, the xrpcc tool also generates the stubs for the client. To create the stubs, go to the docs/tutorial/examples/jaxrpc/hello directory and run the tool as follows. (Type the command on a single line.)

UNIX:

xrpcc.sh -classpath build/shared -client -d build/client 
config.xml
 

Windows:

xrpcc.bat -classpath build\shared -client -d build\client 
config.xml
 

The -classpath option refers to the directory containing the class files that you created in Compiling the Service Definition Code. The -d option denotes the destination directory for the generated files. See the section Syntax for the full syntax of the xrpcc tool.

As a shortcut, instead of running the xrpcc command as shown previously, you can simply type the following:

ant xrpcc-client
 

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 the JAX-RPC Specification. The client gets a reference to the stub by calling the getHelloIF method of the HelloWorldImpl class, which was created when you ran the xrpcc tool.

The args[0] parameter of the stub._setProperty 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 HelloWorld_Impl().getHelloIF());	
            stub._setProperty(	
                javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,	
                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, go to the docs/tutorial/examples/jaxrpc/hello directory and type the following:

ant compile-client 
 

Packaging the Client

To package the client into a JAR file, go to the docs/tutorial/examples/jaxrpc/hello directory and type the following command:

ant jar-client
 

This command creates the dist\hello-client.jar file.

Running the Client

To run the HelloClient program, go to the docs/tutorial/examples/jaxrpc/hello directory and type the following:

ant run
 

The program should display this line:

Hello Duke!
 

The run target of ant executes this command:

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

The classpath includes the hello-client.jar file that you created in the preceding section, as well as several JAR files that are part of the JAX-RPC reference implementation. In order to run the client remotely, all of these JAR files must reside on the remote client's computer.

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.

Iterative Development

In order to show you each step of development, the previous sections instructed you to type several ant commands. To save time, after you've installed the application (with ant install), you can iterate through these steps:

  1. Test the application.
  2. Edit the source files.
  3. Execute ant build.
  4. Execute ant reload.
  5. Execute ant run.

The build target compiles the code, runs the xrpcc tool, and packages the client JAR file. The reload target updates the Web application on Tomcat with your latest changes.

Optional: Packaging the Service

A service is packaged in a Web application archive (WAR), a JAR file whose contents are defined by the Java Servlet Specification. WAR files make it easy to distribute the service for deployment at various sites. 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, go to the docs/tutorial/examples/jaxrpc/hello directory and type the following:

ant package
 

This command creates the dist/jaxrpc-hello.war file. To deploy the WAR file, you copy the WAR file to Tomcat's webapps directory.

On Tomcat, deployment and installation are similar, yet subtly different. (For more information, see the Tomcat documentation on the Manager application.) In this release, you must shut down and restart Tomcat every time you redeploy a WAR file. Because this requirement will slow you down during iterative development, we recommend that you use the ant targets install and reload. The deployment operation is appropriate for production, not development, environments.

Home
TOC
PREV TOP NEXT