HelloWorld SOAP Sample
iPlanet™ Application Server Samples

Updated June 13, 2001

The SOAP Helloworld sample demonstrates how SOAP can be used to access an EJB on the iPlanet Application Server. The following instructions describes how to assemble and deploy the application.

Application Overview

Note: This sample requires that the HelloWorld sample be deployed and exercised prior to running the SOAP interface to the HelloWorld EJB.

A simple command line based Java client uses SOAP RPC over HTTP to access a SOAP service which in turn calls a stateless session bean. This sample should provide a developer with a basic understanding of using SOAP to call EJB components in iPlanet Application Server.

The core part of the application is the GreeterService. This is a SOAP proxy to the HelloWorld stateless EJB and is a simple class that wraps the helloworld EJB business methods. It is registered as a SOAP service. Any client that implements SOAP can call methods on this service.

 public class GreeterSoapService {

    ...

    public String getGreeting() {

       // do JNDI lookup and call ejb home create to create ejb

       ...

       String msg = helloWorldEJB.getGreeting();

       ...// release ejb instance

       return MSG;

    }

 }

As seen above, the method implementation in the proxy service delegates processing to the backend EJB. When a client calls a method on SOAP service, it in turn calls the corresponding method on the EJB.

The GreeterClient, as shown in the diagram below, is simple Java application that acts as a SOAP client. It uses the Apache SOAP RPC router to call the SOAP service. It simply calls a method on the SOAP service and prints the result on console. Although this client is implemented in Java, it can be developed in any language for which a SOAP implementation is available.

Setting Up the Environment

Getting Started includes a checklist of prerequisites for deploying sample applications to iPlanet.
Installing Apache SOAP framework in the application server. This must be done before the HelloWorld SOAP sample is exercised.
Installing Helloworld sample application. This must be done before the HelloWorld sample is exercised.

Deploying and Running the Application

Deploying the Sample describes how to manually register the application in iPlanet using a Command Line Interface (CLI).
Running the Application describes how to start the application, navigate through it and how to troubleshoot in the event of problems.

Further Exploration

Web-based Registration of SOAP Service describes how to use the Apache SOAP administrative web interface to register the sample SOAP service.

Compiling and Assembling the Application describes how to use command line tools to recompile the sources and rebuild the WAR module and the overall EAR file.

Deploying the Sample

After you've deployed and exercised the HelloWorld EJB sample application and verified that your installation of Apache SOAP works properly with the Apache SOAP samples, you are ready to deploy the HelloWorld SOAP service and client program.

Deploying the Client and SOAP Service

The Ant build facility is used to recompile and assemble the web application and SOAP service. For more information about this build facility and its use with the iPlanet Application Server samples, see the Sample Application Build Facility.

To recompile, reassemble, and redeploy the sample application, follow these steps:

1. Change directories to the SOAP Cart sample application: cd install_dir/ias/ias-samples/soap/helloworld/src. Edit the Ant build file for the sample, build.xml, to ensure the appropriate libraries are used when compiling and deploying the sample. To do this, ensure the following properties are set correctly at the top of the script:

soap.installpath
xerces.installpath
soap.service.url

2. Compile and assemble the client and SOAP service:

Execute "build" under the install_dir/ias/ias-samples/soap/helloworld/src directory
The default target, core, will be executed to recompile the Java class files.

3. Deploy and Register the SOAP Service

Execute "build install_service" under the install_dir/ias/ias-samples/soap/helloworld/src/ directory

This target copies the SOAP service class, GreeterService, to the SOAP service directory (we use install_dir/ias/APPS/soap-services/ for convenience). The service is then registered with Apache SOAP using the descriptor file install_dir/ias/ias-samples/soap/helloworld/src/DeploymentDescriptor.xml
Alternatively, you can use the Apache SOAP web-based administrative interface to register the SOAP service. Although the administrative interface registers the SOAP service, you must still ensure that the SOAP service classes are deployed to an accessible location within the application server.

4. Install the Client Application

Execute "build install_client" under the install_dir/ias/ias-samples/soap/helloworld/src/ directory.

This command will copy the GreeterClient class to the directory install_dir/ias/soap-client/.

Modify Application Server Classpath

Before running the sample, you need to ensure that the SOAP service and HelloWorld EJB deployment directories are added to the application server's classpath. See the Samples Getting Started Guide for more information on modifying the application server's classpath.

Add SOAP Service

During installation of Apache SOAP on the iPlanet Application Server, you should have added the following directory to the application server's classpath:

install_dir/ias/APPS/soap-services/

If you did not already add this directory to the server's classpath, then add it now based on the instructions in the Installing Apache SOAP on iPlanet. This addition will ensure that the GreeterService class is accessible to the Apache SOAP infrastructure.

Add HelloWorld EJB Classes

Since this sample uses the HelloWorld sample, you need to put HelloWorld sample's EJB directory in the application server's classpath. Add the following directory into application server's classpath, if already not present.:

install_dir/ias/APPS/helloworld/helloworldEjb

Restart Application Server

Restart the application server to pick up the server's classpath changes.

Now you are ready to exercise the application.

Running the Application

The GreeterClient application is a simple Java main program that accepts as arguments the URL for the Apache SOAP RPC Router and a name.

If you ran "build install_client" and have already modified and executed the soap_env script to set SOAP-related environment variables, then you can run the client program in the following manner:

1. Go to your soap-client directory:

install_dir/ias/soap-client/

2. Run the client application:

java samples.soap.helloworld.GreeterClient http://127.0.0.1/NASApp/soap/rpcrouter Chris

Depending on the time of day, the output from the client should resemble the following:

Hello World sample with Soap.
Good evening Chris. Have a great evening.

The client calls the Greeter ejb method through SOAP over HTTP, to get the greeting depending on current time and displays it to client. Behind the scenes:

The client program calls the Apache SOAP rpcrouter servlet and includes a SOAP request envelope.
The Apache SOAP rpcrouter class routes the calls to the SOAP service GreeterService.
GreeterService SOAP service acts as a proxy to GreeterEJB and calls its method and sends the result back to client.
The Apache SOAP rpcrouter converts the response object to a SOAP response envelop and sends it back to the client.

Troubleshooting

If you encounter problems when running the application, review the General Troubleshooting section to learn how to view logs files.

Invalid GUID Error

When you receive the following message, it is most likely the result of having not registered the HelloWorld EJB in the application server prior to running the SOAP sample. Follow the Installing the HelloWorld Sample instructions and then try to run the SOAP client again.

D:\iplanet\ias6\ias\soap-client>java samples.soap.helloworld.GreeterClient http:
//127.0.0.1/NASApp/soap/rpcrouter Chris
Generated fault:
Fault Code = SOAP-ENV:Server
Fault String = Exception from service object: TheGreeter : Invalid guid null in GDS

SOAP Service Exception with GreeterHome

When you receive an exception related to the GreeterHome class, it is most likely caused by the EJB deployment directory not being present in the application server's classpath. See the Modifying the Server's Classpath section for details on setting the classpath of the application server.

D:\iplanet\ias6\ias\soap-client>java samples.soap.helloworld.GreeterClient http:
//127.0.0.1/NASApp/soap/rpcrouter Chris
Generated fault:
Fault Code = SOAP-ENV:Server
Fault String = Exception from service object: samples.helloworld.ejb.GreeterHome

Apache TCP Tunnel/Monitor Tool

You will also find Apache TCP tunnel/monitor tool very useful for debugging SOAP-based applications. The tool is bundled as part of Apache SOAP. To use the tool, run following java program on command line:

java org.apache.soap.util.net.TcpTunnelGui listenport tunnelhost tunnelport

The program opens a port at listenport on local machine which acts as a tunnel to a tunnel (destination) host/port combination specified in command. It displays all request/response messages going back and forth between client and server. For example start the TCP tunnel as follows:

java org.apache.soap.util.net.TcpTunnelGui 9090 localhost 80

Now run the client program with the following URL to direct the request to the TCP tunnel:

java samples.soap.helloworld.GreeterClient http://localhost:9090/NASApp/soap/rpcrouter Chris

In the TCP tunnel window you will see XML messages going back and forth between soap client and soap service.

For more information on TCP tunnel program, refer to Apache SOAP documentation.

Web-based Registration of SOAP Service

With the Apache SOAP web-based Administration Tool, you can use a web browser to deploy/un-deploy services and review the list and the definitions of the services deployed on a given SOAP server. To deploy the HelloWorld SOAP service using the Apache SOAP administration tool, follow these steps:

Point your browse to:

http://hostname:port/NASApp/soap/admin/index.html

Click on Deploy link. (Although the operation is called "Deploy", you are actually only registering the service. In an earlier step you copied the SOAP service to a directory on the application server. The combination of that copy step and this registration step result in the "deployment" of the service to the application server.)
You will be presented with a form, where you can fill the information about your soap service.
For ID enter urn:Greeter.
For Scope of the service enter request.
For Method List enter getGreeting.
For Provider type enter java because our server is implemented in Java language.
For Java services, Provider class enter samples.soap.helloworld.GreeterService (which is the fully qualified name of the service class).
For Java services, Use static class select no.
All other fields in the forms are not required for deploy this service.
Submit the form.
The service is deployed and ready to be used by client.
Click on the List button to verify that the service has been registered.

Compiling and Assembling the Application

To easily recompile, assemble and deploy the application, see the Sample Application Build Facility document for details on using a build facility to quickly perform these tasks.

For example, to rebuild the entire application from scratch, follow these steps:

1. Compile and Assemble Web Application

Execute "build" under install_dir/ias/ias-samples/soap/helloworld/src/
The default target core will be executed to rebuild the SOAP service and client program.

2. Install the SOAP service and client application:

Execute "build install_service" and "build install_client"

3. Restart Application Server

An application server restart will be must if you've modified the SOAP service. For SOAP client modification or during the first install of the service to the server, no restart is is necessary.

HelloWorld SOAP Sample iPlanet™ Application Server Samples