HelloWorld SOAP Sample:

Full text

(1)

Sun Microsystems, Inc. 901 San Antonio Road Palo Alto, CA 94303 U.S.A. 650-960-1300

HelloWorld

SOAP Sample:

Accessing Stateless Session Enterprise JavaBeans™

Technology

(2)

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

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

(3)

1

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.loginfile. Usels -ato 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

(4)

TheHelloWorldSOAP 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

HelloWorldbean—being invoked.

Theorg.apache.soap.providers.StatelessEJBProviderclass does the following:

• Locates and loads the service implementation.

• Invokes the service methods.

(5)

HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology • March 2002 3

1.

Understanding the Architecture

FIGURE 1shows how theHelloWorldclient—a simple Java application that acts as a SOAP client—accesses a stateless session bean.

FIGURE 1 HelloWorldSOAP Architecture

The process is as follows:

1. The SOAP client sends the HTTP request, embedded with a SOAP envelope, to the Apache SOAPrpcrouterservlet.

2. The servlet delegates the request toStatelessEJBProvider, which locates and invokes the method on theGreeterbean 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.Responseobject.

Note – Besides the Java programming language, you can also develop this client in other languages in which you can implement SOAP.

HelloWorld client (Java class)

rpcrouter servlet

Greeter stateless session Enterprise JavaBeans technology

(6)

2.

Setting Up the Environment

Before you run theHelloWorldsample, prepare your environment first.

Consult the “Set Up Your Environment” section in Getting Started for prerequisites at

http://developer.iplanet.com/appserver/samples/docs/getting-started.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/soap-install.html

■ Install theHelloWorldsample, as described in the procedures inHelloWorld

sample at

http://developer.iplanet.com/appserver/samples/helloworld/docs/

Note – TheHelloWorldSOAP sample requires that you deploy and run the

HelloWorldsample before running the SOAP interface to theHelloWorldbean.

3.

Deploying the Sample

To deployHelloWorld, 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-registrationfor details.

(7)

HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology • March 2002 5

3.1

Deploying the Client Application

You deploy the client Web application and SOAP service by recompiling and assembling them with the Antbuildfacility. 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 theHelloWorldSOAP sample:

% cd install_dir/ias/ias-samples/soap/helloworld/src

2. Edit the Antbuildfile 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.installpathsoap.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/ias-samples/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 theHelloWorldClientclass to the directory

install_dir/ias/soap-client/.

3.2

Modifying the iPlanet Application Server

CLASSPATH

Environment Variable

Before running theHelloWorldSOAP sample, add theHelloWorldEJB deployment directory to iPlanet Application Server’sCLASSPATHenvironment variable. For more information on modifying the iPlanet Application Server

(8)

CLASSPATHvariable, see Getting Started at

http://developer.iplanet.com/appserver/samples/docs/getting-started.html#classpath.

1. Put the EJB directory of theHelloWorldsample in iPlanet Application Server’s CLASSPATHvariable if the directory is not already present:

install_dir/ias/APPS/helloworld/helloworldEjb

(TheHelloWorldSOAP sample uses theHelloWorldsample.)

2. Restart iPlanet Application Server to activate theCLASSPATHchanges.

Now you are ready to run the sample.

4.

Running the Sample

TheHelloWorldClientsample is a simple Javamainprogram that accepts as arguments the URL for the Apache SOAPrpcrouterand a name, such as the name of the person greeted by iPlanet Application Server when you run the client. To start and run theHelloWorldsample:

1. Change directory tosoap-client:

% cdinstall_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 theGreeterEJB 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 thecall.invokerequest to the Apache SOAPrpcrouterservlet.

b. The Apache SOAPrpcrouterservlet class calls theServiceManagerclass to look upDeploymentDescriptor.

c. The Apache SOAPrpcrouterservlet passes the request to

StatelessEJBPluggableProvider.

d. TheStatelessEJBPluggableProviderlocates and invokes the EJB methods.

(9)

HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology • March 2002 7 e. The Apache SOAPrpcrouterconverts 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:

5.

Troubleshooting

Error messages posted to the log files and debugging tools can help identify problems you encounter when runningHelloWorld. 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:

Cause: The invalid GUID error most likely resulted from a failure to register the HelloWorldbean in iPlanet Application Server before the SOAP sample was run.

Got SOAP response from

http://hostname:port/NASApp/soap/servlet/rpcrouter Hello Rakesh! Good evening. Have a great evening.

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

(10)

Remedy: Follow theHelloWorldsample 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:

Cause: The SOAP service exception related to theGreeterHomeclass was most likely caused by the absence of the EJB deployment directory from iPlanet Application Server’sCLASSPATHenvironment variable.

Remedy: Set theCLASSPATHvariable of iPlanet Application Server; see Modifying the iPlanet Application ServerCLASSPATHEnvironment 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:

opens a listening port at9090of your local machine to port80of the tunnel host,

localhost.

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

(11)

HelloWorld SOAP Sample: Accessing Stateless Session Enterprise JavaBeans Technology • March 2002 9 With the preceding example, running the client program with the URL—

—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 theHelloWorldSOAP 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.

java samples.soap.helloworld.HelloWorldClient http://localhost:9090/NASApp/soap/rpcrouter Rakesh

(12)

3. In the form that is displayed, fill in information about the SOAP service:

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.

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

Java services, Provider class null

Java services, Use static class Select no

Key Value JNDIName ejb/TheGreeter FullHomeInterfaceName samples.soap.cart.ejb. GreeterHome ContextProviderURL FullContextFactoryName com.netscape.server.jndi. RootContextFactory

Figure

Updating...

References

Updating...

Related subjects :