HelloWorld SOAP Sample:

Transcription

1 HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology Sun Microsystems, Inc. 901 San Antonio Road Palo Alto, CA U.S.A

2 Copyright 2002 Sun Microsystems, Inc., 901 San Antonio Road Palo Alto, CA USA. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. For Netscape Communicator, the following notice applies: Copyright 1995 Netscape Communications Corporation. All rights reserved. Sun, Sun Microsystems, the Sun logo, Enterprise JavaBeans, EJB, iplanet, Java, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc The OPEN LOOK and Sun Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun s written license agreements. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR (g)(2)(6/87) and FAR (6/87), or DFAR (b)(6/95) and DFAR (a). DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON- INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 2002 Sun Microsystems, Inc., 901 San Antonio Road Palo Alto, CA Etats-Unis. Tous droits réservés. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l autorisation préalable et écrite de Sun et de ses bailleurs de licence, s il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Des parties de ce produit pourront être dérivées des systèmes Berkeley BSD licenciés par l Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d autres pays et licenciée exclusivement par X/Open Company, Ltd. La notice suivante est applicable à Netscape Communicator : Copyright 1995 Netscape Communications Corporation. Tous droits réservés. Sun, Sun Microsystems, the Sun logo, Enterprise JavaBeans, EJB, iplanet, Java, et Solaris sont des marques de fabrique ou des marques déposées, ou marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. L interface d utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d utilisation visuelle ou graphique pour l industrie de l informatique. Sun détient une licence non exclusive de Xerox sur l interface d utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l interface d utilisation graphique OPEN LOOK et qui en outre se conforment aux licences écrites de Sun. CETTE PUBLICATION EST FOURNIE "EN L ETAT" ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N EST ACCORDEE, Y COMPRIS DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L APTITUDE DE LA PUBLICATION A REPONDRE A UNE UTILISATION PARTICULIERE, OU LE FAIT QU ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DE GARANTIE NE S APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU.

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