helloworld_soap

HelloWorld SOAP Sample:
Accessing Stateless Session Enterprise JavaBeans™
Technology
Sun Microsystems, Inc.
901 San Antonio Road
Palo Alto, CA 94303
U.S.A. 650-960-1300
Copyright 2002 Sun Microsystems, Inc., 901 San Antonio Road • Palo Alto, CA 94303-4900 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 52.227-14(g)(2)(6/87) and
FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-3(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 NONINFRINGEMENT, 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 94303-4900 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.
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
What you type, when contrasted
with on-screen computer output
% su
Password:
AaBbCc123
Book and article titles, new words
or terms, words to be emphasized
Read Chapter 6 in the User’s Guide.
These are called class options.
You must be superuser to do this.
Command-line variable; replace
with a real name or value
To delete a file, type rm filename.
1
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:
•
•
•
2
Locates and loads the service implementation.
Invokes the service methods.
Returns the results as a SOAP envelope.
HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology • March 2002
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 2002
3
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
http://developer.iplanet.com/appserver/samples/docs/gettingstarted.html#environment
■
Install the SOAP framework on iPlanet Application Server, as described in
Installing Apache SOAP at
http://developer.iplanet.com/appserver/samples/soap/docs/soapinstall.html
■
Install the HelloWorld sample, as described in the procedures in HelloWorld
sample at
http://developer.iplanet.com/appserver/samples/helloworld/docs/
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 6.
3. Verify that your installation of Apache SOAP works with the Apache SOAP
samples by using the iPlanet Application Server Administration Tool; see
http://developer.iplanet.com/appserver/samples/helloworld/docs/ind
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
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
http://developer.iplanet.com/appserver/samples/docs/build.html.
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 2002
5
CLASSPATH variable, see Getting Started at
http://developer.iplanet.com/appserver/samples/docs/gettingstarted.html#classpath.
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
http://127.0.0.1/NASApp/soap/rpcrouter 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
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
http://hostname:port/NASApp/soap/servlet/rpcrouter
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
http://developer.iplanet.com/appserver/samples/docs/troubleshootin
g.html.
5.1
Invalid GUID Error
Message:
D:\ias\ias\soap-client>java samples.soap.helloworld.HelloWorldClient
http://sting:9090/NASApp/soap/servlet/rpcrouter 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 2002
7
Remedy: Follow the HelloWorld sample instructions at
http://developer.iplanet.com/appserver/samples/helloworld/docs/ 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
http://sting:9090/NASApp/soap/servlet/rpcrouter 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
With the preceding example, running the client program with the URL—
java samples.soap.helloworld.HelloWorldClient
http://localhost:9090/NASApp/soap/rpcrouter 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:
http://hostname:port/NASApp/soap/admin/index.html
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 2002
9
3. In the form that is displayed, fill in information about the SOAP service:
Field
Enter (or Select)
ID
urn:HelloWorld
Scope
Request
Method List
Create
Provider Type
Select user-defined from the drop-down list because we are
using the Apache SOAP Pluggable Provider.
User-Defined Provider Type, Enter FULL Class
Name
org.apache.soap.providers.StatelessEJBProvider
Number of Options
4
Key Value pairs
Key
Value
JNDIName
ejb/TheGreeter
FullHomeInterfaceName
samples.soap.cart.ejb.
GreeterHome
ContextProviderURL
FullContextFactoryName com.netscape.server.jndi.
RootContextFactory
Java services, Provider class
null
Java services, Use static class
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