3 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March 2002 Contents Understanding the Architecture Setting Up the Environment Deploying the Sample Running the Sample Troubleshooting Addendum: Web-Based Registration of the SOAP Service Typographic Conventions Used in This Document Typeface Meaning Example AaBbCc123 The names of commands, files, and directories; on-screen computer output Edit your.login file. Use ls -a to list all files. % You have mail. AaBbCc123 AaBbCc123 What you type, when contrasted with on-screen computer output Book and article titles, new words or terms, words to be emphasized Command-line variable; replace with a real name or value % su Password: Read Chapter 6 in the User s Guide. These are called class options. You must be superuser to do this. To delete a file, type rm filename. 1

4 The HelloWorld SOAP sample demonstrates how to use Simple Object Access Protocol (SOAP) to access stateless session Enterprise JavaBeans (EJB ) technology ( beans ) on iplanet Application Server with Apache s Pluggable Provider. For such access, a simple, command-line-based Java technology-based client sends a SOAP remote procedure call (RPC) over HyperText Transfer Protocol (HTTP). Note The Apache SOAP Pluggable Provider is a layer of abstraction between the Apache SOAP server and the service implementation. A Pluggable Provider class acts as a bridge between the SOAP runtime and the service in this case, the HelloWorld bean being invoked. The org.apache.soap.providers.statelessejbprovider class does the following: Locates and loads the service implementation. Invokes the service methods. Returns the results as a SOAP envelope. 2 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March 2002

5 1. Understanding the Architecture FIGURE 1 shows how the HelloWorld client a simple Java application that acts as a SOAP client accesses a stateless session bean. HelloWorld client (Java class) iplanet Application Server rpcrouter servlet Greeter stateless session Enterprise JavaBeans technology FIGURE 1 HelloWorld SOAP Architecture The process is as follows: 1. The SOAP client sends the HTTP request, embedded with a SOAP envelope, to the Apache SOAP rpcrouter servlet. 2. The servlet delegates the request to StatelessEJBProvider, which locates and invokes the method on the Greeter bean and resends the results to the servlet. 3. The servlet returns to the client the result: a SOAP envelope embedded in HTTP. 4. The client extracts the contents of the SOAP envelope with the org.apache.soap.rpc.response object. Note Besides the Java programming language, you can also develop this client in other languages in which you can implement SOAP. HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March

6 2. Setting Up the Environment Before you run the HelloWorld sample, prepare your environment first. Consult the Set Up Your Environment section in Getting Started for prerequisites at Install the SOAP framework on iplanet Application Server, as described in Installing Apache SOAP at Install the HelloWorld sample, as described in the procedures in HelloWorld sample at Note The HelloWorld SOAP sample requires that you deploy and run the HelloWorld sample before running the SOAP interface to the HelloWorld bean. 3. Deploying the Sample To deploy HelloWorld, do the following: 1. Manually register the sample with a command-line interface (CLI); see Deploying the Client Application, below. 2. Run the sample; see Running the Sample on page Verify that your installation of Apache SOAP works with the Apache SOAP samples by using the iplanet Application Server Administration Tool; see ex.html#verify-registration for details. You can then deploy the client application, as described in the next section. 4 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March 2002

7 3.1 Deploying the Client Application You deploy the client Web application and SOAP service by recompiling and assembling them with the Ant build facility. For details, see Sample Application Build Facility at To recompile, reassemble, and redeploy the client application: 1. Change directory to the HelloWorld SOAP sample: % cd install_dir/ias/ias-samples/soap/helloworld/src 2. Edit the Ant build file for the sample, build.xml, to ensure that the appropriate libraries are used for compiling and deploying the sample, as follows: At the top of the script, ensure that the following properties are correctly set: soap.installpath xerces.installpath soap.service.url 3. Compile the client. Type: % build install_dir/ias/ias-samples/soap/helloworld/src The default target, core, is executed to recompile the Java class files. 4. Register the SOAP service. Type: % build install_dir/ias/ias-samples/soap/helloworld/src/ In this step, you register the service with Apache SOAP by using the descriptor file install_dir/ias/iassamples/soap/helloworld/src/deploymentdescriptor.xml Alternatively, you can use the Apache SOAP Web-based administrative interface to register the SOAP service. See page 9 for details. 5. Install the client application. Type: % build install_client install_dir/ias/ias-samples/soap/helloworld/src/ This step copies the HelloWorldClient class to the directory install_dir/ias/soap-client/. 3.2 Modifying the iplanet Application Server CLASSPATH Environment Variable Before running the HelloWorld SOAP sample, add the HelloWorld EJB deployment directory to iplanet Application Server s CLASSPATH environment variable. For more information on modifying the iplanet Application Server HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March

8 CLASSPATH variable, see Getting Started at 1. Put the EJB directory of the HelloWorld sample in iplanet Application Server s CLASSPATH variable if the directory is not already present: install_dir/ias/apps/helloworld/helloworldejb (The HelloWorld SOAP sample uses the HelloWorld sample.) 2. Restart iplanet Application Server to activate the CLASSPATH changes. Now you are ready to run the sample. 4. Running the Sample The HelloWorldClient sample is a simple Java main program that accepts as arguments the URL for the Apache SOAP rpcrouter and a name, such as the name of the person greeted by iplanet Application Server when you run the client. To start and run the HelloWorld sample: 1. Change directory to soap-client: % cd install_dir/ias/soap-client/ 2. Run the client application. Type: % java samples.soap.helloworld.helloworldclient Rakesh The client calls the Greeter EJB method through SOAP over HTTP. The method returns the greeting, reflecting the current time, and displays it to the client. Behind the scenes: a. The client program builds the call and sends the call.invoke request to the Apache SOAP rpcrouter servlet. b. The Apache SOAP rpcrouter servlet class calls the ServiceManager class to look up DeploymentDescriptor. c. The Apache SOAP rpcrouter servlet passes the request to StatelessEJBPluggableProvider. d. The StatelessEJBPluggableProvider locates and invokes the EJB methods. 6 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March 2002

9 e. The Apache SOAP rpcrouter converts the response object to a SOAP response envelope and returns it to the client. Depending on the time of day, the output from the client looks like this: Got SOAP response from Hello Rakesh! Good evening. Have a great evening. 5. Troubleshooting Error messages posted to the log files and debugging tools can help identify problems you encounter when running HelloWorld. In this section, we describe the two most common error situations and how to resolve them. To learn how to view log files, review the description of other common error situations and their remedies in General Troubleshooting at g.html. 5.1 Invalid GUID Error Message: D:\ias\ias\soap-client>java samples.soap.helloworld.helloworldclient rakesh Generated fault: Fault Code = SOAP-ENV:Server Fault String = Error in connecting to EJB KJS logs: In TemplateProvider.locate() URI: urn:helloworld DD.ServiceClass: org.apache.soap.providers.statelessejbprovider DD.ProviderClass: null Call.MethodName: getgreeting Exception caught: javax.naming.namenotfoundexception: TheGreeter : Invalid guid null in GDS Cause: The invalid GUID error most likely resulted from a failure to register the HelloWorld bean in iplanet Application Server before the SOAP sample was run. HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March

10 Remedy: Follow the HelloWorld sample instructions at and then run the SOAP client again. 5.2 SOAP Service Exception with GreeterHome Message: D:\ias\ias\soap-client> java samples.soap.helloworld.helloworldclient rakesh Generated fault: Fault Code = SOAP-ENV:Server Fault String = Error in connecting to EJB Cause: The SOAP service exception related to the GreeterHome class was most likely caused by the absence of the EJB deployment directory from iplanet Application Server s CLASSPATH environment variable. Remedy: Set the CLASSPATH variable of iplanet Application Server; see Modifying the iplanet Application Server CLASSPATH Environment Variable on page 5 for details. 5.3 Apache TCP Tunnel-Monitor Tool The Apache TCP tunnel-monitor tool for debugging SOAP-based applications is bundled as part of Apache SOAP. To use the tool: Run the Java program on the command line: % java org.apache.soap.util.net.tcptunnelgui listenport tunnelhost tunnelport The program opens a port at listenport on your local machine. The port acts as a tunnel to a tunnel (destination) host-port combination specified in the command. It displays all request-response messages that are exchanged between the SOAP client and the SOAP server. For example: java org.apache.soap.util.net.tcptunnelgui 9090 localhost 80 opens a listening port at 9090 of your local machine to port 80 of the tunnel host, localhost. 8 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March 2002

11 With the preceding example, running the client program with the URL java samples.soap.helloworld.helloworldclient Rakesh directs the request to the TCP tunnel. For more information on TCP tunnel programs, refer to the Apache SOAP documentation. 6. Addendum: Web-Based Registration of the SOAP Service With the Apache SOAP Web-based Administration Tool, you can use a Web browser to deploy or withdraw services and to review the list and the definitions of the services deployed on a given SOAP server. To deploy the HelloWorld SOAP service with the Apache SOAP Administration Tool: 1. Direct your browser to: 2. Click Deploy. Note 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 iplanet Application Server. The combination of the copying step and this registration step results in the deployment of the service to iplanet Application Server. HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March

12 Field ID Scope Method List Provider Type 3. In the form that is displayed, fill in information about the SOAP service: Enter (or Select) User-Defined Provider Type, Enter FULL Class Name urn:helloworld Request Create Number of Options 4 Key Value pairs Key JNDIName FullHomeInterfaceName Select user-defined from the drop-down list because we are using the Apache SOAP Pluggable Provider. org.apache.soap.providers.statelessejbprovider Value ejb/thegreeter samples.soap.cart.ejb. GreeterHome ContextProviderURL FullContextFactoryName com.netscape.server.jndi. RootContextFactory Java services, Provider class Java services, Use static class null Select no No other fields in the forms are required for deployment of this service. 4. Submit the form. The service is deployed and ready to be used by the client. 5. Click List to verify that the service has been registered. 10 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology March 2002

Important Note on New Product Names As part of Sun s new developer product strategy, we have changed the names of our development tools from Sun WorkShop to Forte Developer products. The products, as you

RAID Controller PCI Card for the Sun Fire V60x and V65x Servers Release Notes CAUTION: Read this document before installing the RAID Controller PCI Card. Failure to use the correct firmware version with

Solaris 9 Installation Roadmap This document is a guide to the DVD, CDs and documents involved in installing the Solaris 9 software. Unless otherwise specified, this document refers to both DVDs and CDs