SOAP Shopping Cart Sample
iPlanet^TM Application Server Samples

Updated June 13, 2001

If you already went through the deployment process for the SOAP shopping cart  on this machine, you can run the application by clicking here.

The shopping cart sample is a simple application based on SOAP, EJBs, servlets and JSPs. Assembling this application and deploying it to iPlanet Application Server provides an introduction to the server's assembly, deployment and registration tools.

Application Overview

There are four components of the application.

• Cart EJB : A stateful session bean representing a simple shopping cart for books. It provides business methods to:
• Add a book to the cart.
• Remove a book from the cart.
• List all of the books in the shopping cart.


This EJB may have been originally created for another purpose (such as a J2EE-based on-line book store), but now we'd like to expose it's functionality as a web service that can be used by SOAP-enabled client applications.

 
• SOAP Shopping Cart Service : The CartService is one of the core parts of the application. It is a Java class that wraps calls to the Cart EJB business methods, and it is registered as a SOAP service. Any client that utilizes SOAP can call methods on this service and thereby leverage the business method of the Cart EJB component.

 public class CartService {
    private Cart cart = null;
    ...
    private Cart getCart() throws RemoteException {
        if (cart != null) {
            return cart;
        }
        // Otherwise, lookup the Cart EJB home interface and create a new stateful session bean
    }

    public void addBook(Book book) throws RemoteException {
        // simply delegate to ejb.
        getCart().addBook(book);
    }

    public Book[] getSelectedBooks() throws RemoteException {
        Collection items = getCart().getSelectedBooks();
        // convert the collection into array and send back to client
        ....
        return array;
    }

    .....
 }

As seen above, the CartService creates a new Cart Stateful Session Bean and holds it's reference.  For all subsequent calls by a given client, the same instance of CartService (and, therefore, the same Stateful Session Bean) is reused. The user's session is maintained within the EJB.

One interesting aspect of this sample is the return type of method getSelectedBooks(). It is an array as opposed to the Collection return type of the EJB business method. The reason fro this conversion is that Apache SOAP does not yet provide a serializer-deserializer for Java Collections. Before sending the response back to the client, the service converts the collection to array. At the client stub, a collection can be reconstructed from the received array if so desired.
 

• SOAP Client Proxy : The CartSoapProxy is the client-side portion of the application architecture. It is a simple class which defines the same set of methods as made visible by the Shopping Cart SOAP service. This class acts as a client-side proxy to the Cart EJB. The business application client makes method calls on this proxy and the proxy in turn is responsible for calling the appropriate service using SOAP as the transport mechanism

 
• Shopping Cart Client : There are two types of clients demonstrated in the sample application. The first is a web based client while the other is an Java Swing GUI client.  Both clients use the CartSoapProxy to talk to Cart EJB using SOAP. This multi-client approach demonstrates how an EJB can be used by both a "rich" Java application as well as a thin web client. Although these clients are implemented in Java/JSP, any kind of language can be used with the CartService as long as it can send and receive SOAP messages.

Here's a summary of the interactions which occur when the application is run:

• The client program creates a new CartSoapProxy that acts as a SOAP proxy to the shopping cart service and EJB
• This proxy calls the SOAP rpcrouter servlet and sends a SOAP request envelope
• If this is the first request received from a given client, the rpcrouter class creates a new instance of the CartService SOAP service and routes the calls to the requested service method
• While executing the method request, the new CartService creates a new Cart Stateful Session Bean and maintains a reference to the EJB.  The service will then execute the appropriate method on the newly created EJB
• Since "session" scope was specified when the SOAP service was deployed, the rpcrouter sends back a new session-id cookie back to the client along with the response from the service
• Subsequent SOAP requests from the same client will include not only the SOAP request envelope but the session-id cookie as well.  In this way, the same CartService instance is used for each method request from a given client

Setting Up the Environment

• Getting Started includes a checklist of prerequisites for deploying sample applications to the iPlanet Application Server
  

• Install Apache SOAP in the application server. The Apache SOAP distribution must be installed before this sample can be exercised

Assembling and Deploying the Application

Command-line Assembly and Deployment

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/cart/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

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

The default target, core, will be executed.  It will recompile all of the Java classes, build the EJB stubs and skeletons, assemble the soap-cart.war web archive, and assemble the soap-cartEjb.jar EJB JAR

Execute "build deploy" under the install_dir/ias/ias-samples/soap/cart/src/ directory

The target deploy will be executed.  It will deploy the soap-cart.war web archive as well as the soap-cartEjb.jar EJB JAR, copy the SOAP service class to install_dir/ias/APPS/soap-services/, and register the service in SOAP using the descriptor file  install_dir/ias/ias-samples/soap/cart/src/DeploymentDescriptor.xml

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

The target install_service will be executed.  It will copy the SOAP service class, CartService, to the SOAP service directory (we use install_dir/ias/APPS/soap-services/ for convenience).  The service is then registered in SOAP using the descriptor file  install_dir/ias/ias-samples/soap/cart/src/DeploymentDescriptor.xml  If you prefer to deploy and register the SOAP service manually without using Ant, please refer to the documentation found here

The application server must restarted only if you've modified a deployment descriptor, an EJB home/remote interface, or the SOAP service. For servlet and/or SOAP client modifications, no restart is is necessary.

Running the Sample Applications

Before running the sample applications, it's necessary to add the Cart EJB classes to the application server's classpath.  This is necessary because the SOAP service, CartService, is loaded by the system classloader and it will be unable to access the EJB classes if they are not also on the system classpath.  To do this, add the install_dir/ias/APPS/modules/soap-cartEjb/ to the application classpath.  For instructions on how to modify the iPlanet Application Server classpath, refer to the Apache SOAP installation instructions.

UNIX:

Add the following path to the server's classpath:

/usr/iplanet/ias6/ias/APPS/modules/soap-cartEjb

Windows:

Add the following path to the server's classpath:

d:\iplanet\ias6\ias\APPS\modules\soap-cartEjb

Now restart the application server to pickup the classpath changes.

To test the web-based SOAP client, view the following URL in a browser:  http://<server name>/NASApp/soap-cart

For example: http://localhost/NASApp/soap-cart

To test the Java Swing GUI client, change directories to the SOAP Cart sample application (cd install_dir/ias/ias-samples/soap/cart/src) and execute "build run_gui"

Known Issues

The prebuilt EAR file that ships with the server has the Apache SOAP router parametrized to http://localhost/NASApp/soap/rpcrouter. If your router is on another server and/or port, then you will need to edit the web.xml file (located at soap/cart/src) to change the SOAP_ROUTER parameter to match your environment. Once the change is made, the sample has to be reassembled and deployed to the server.

Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved.