SOAP Shopping Cart Sample - Deployment without Ant
iPlanet^TM Application Server Samples

Updated June 13, 2001

This document describes the steps required to assemble and deploy the SOAPCart application using the iPlanet Application Server Deployment Tool and the SOAP registration tools. While this approach is more time consuming than using the command line tools, the Deployment Tool is often used when XML deployment descriptors need to be built from scratch, and it's an excellent way of building these descriptors while minimizing human error. Since the XML descriptors have been provided with the sample application, it's not necessary to use the Deployment Tool to test the SOAP Cart application and the command-line instructions may be used as an alternative.

This document is divided into three sub-sections:

Assembling Components using Deployment Tool
Deploying Components using Deployment Tool
Registering the SOAP Shopping Cart service

Assembling Components using Deployment Tool

This step is optional. Since the web application archive (soap-cart.war) and EJB JAR file (soap-cartEjb.jar) have already been assembled as part of the Shopping Cart sample application, you may proceed directly to the deployment instructions. If you wish to learn how these archives are constructed or if you wish to make changes to the sample application, this document will describe the steps required.

Assembling the SOAP Cart sample components requires three steps:

Compile Java Source Files
Create soap-cartEjb.jar Module
Create soap-cart.war Module

Compile Java Source Files

To facilitate recompiling and assembling the web application and EJB JAR, the Ant build facility will be used. For more information about this build facility and its use with the iPlanet Application Server samples, see the Sample Application Build Facility.

To recompile all source files, 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

2. Compile the Java source files

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

Create soap-cartEjb.jar Module

Now that the source files have been compiled into Java .class files, you are ready to begin assembling the application. Your first step is to create the EJB JAR file using the Deployment Tool.

Insert EJBs and Supporting Classes

1. Before using the Deployment Tool, create directory location where the assembled modules will be saved:

Create the new directory install_dir/ias/ias-samples/soap/cart/assemble/ outside the Deployment Tool. You will assemble the EJB into a JAR file and save it to this directory

2. Launch the Deployment Tool:

UNIX: Execute install_dir/ias/bin/deploytool&
Windows: Programs->iPlanet Application Server 6.0->iAS Deployment Tool

3. Create soap-cartEjb.jar:

In the startup dialog, select New EJB Application (.jar file)
Alternatively, if Deployment Tool is already started, select File -> New
Click on EJB JAR Module
Enter "soap-cartEjb.jar" as the archive file name.
Click on Browse to navigate to the directory install_dir/ias/ias-samples/soap/cart/assemble/
Click on OK to exit the dialog window
The EJB JAR module appears in the EJB pane of the Deployment Tool window
Click on Component View to see only the name of the EJB JAR module without the full directory path

4. Insert all class files needed in the soap-cartEjb.jar file:

Select the EJB JAR module and right click. Select Insert (alternatively, select the module and choose Edit->Insert from the menu)
Navigate to the directory in which the sample application's EJB and common classes reside (install_dir/ias/ias-samples/soap/cart/build/classes/) and add these classes:

samples/soap/cart/Book.class
samples/soap/cart/ejb/Cart.class
samples/soap/cart/ejb/CartHome.class
samples/soap/cart/ejb/CartEJB.class

Click on Resolve to determine if any of the included classes depend on classes that are not part of the EJB JAR module. Notice that the classes change from red to blue as they are resolved. Any files which remain red are dependent on classes not included in the EJB JAR module. If a warning appears regarding unresolved class dependencies, click on Resolve again to attempt the resolution again
When all of the classes have been resolved, click Insert to add these four classes to the EJB JAR
If you have selected Component View, you'll see the EJB listed in the EJB module window. Deployment Tool introspects the classes to identify any EJBs and lists them in the EJB module window

Modify Deployment Descriptor Settings for the Cart EJB

1. Modify the deployment descriptor for the Cart EJB

Click on Component View, if it's not already selected
Select the Cart EJB (it may be necessary to expand the soap-cartEjb folder first), right-click and select Edit Descriptor from the pop-up menu
Adjust the EJB descriptor window size to see all of the settings.
Note the unique GUID (Globally Unique IDentifier) assigned to the EJB. This ID is used by the application server to manage the EJB as a unique component throughout the application server.

2. Set general attributes for the CartEJB deployment descriptor

In the General tab, set Bean Name to ShoppingCart
In the General tab, set State Management Type to Stateful

3. Close and save the CartEjb deployment descriptor. Close the EJB descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes

Save the ShoppingCart EJB JAR

Select the soap-cartEjb.jar module and then choose Save from the File menu.

Now that we've assembled the EJB JAR module, we're ready to move on to assembling the web application archive (WAR).

Create soap-cart.war Module

Insert Java Classes, JSPs and HTML Files

1. Create soap-cart.war:

Choose New from the File menu
Click on Web Application
Enter "soap-cart.war" as the archive file name
Click on Browse to navigate to the directory install_dir/ias/ias-samples/soap/cart/assemble/
Click on OK to exit the dialog window
The WAR module appears in the Web Applications pane of the Deployment Tool window
Click on Component View to see only the name of the WAR module without the full directory path

2. Insert all Java class files needed in the soap-cart.war file:

Select the soap-cart.war file from the Web Applications pane
Right-click on the soap-cart.war file and select Insert from the pop-up menu (this may also be done by selecting Edit -> Insert from the menu bar)
Navigate to the directory in which the sample application's servlet class and common classes reside (install_dir/ias/ias-samples/soap/cart/build/classes/) and add these files:

samples/soap/cart/Book.class
samples/soap/cart/servlet/CartClientServlet.class,
samples/soap/cart/soap/CartSoapProxy.class

Click the Resolve button. This ensures that all dependent classes can be resolved before the classes are added to the WAR file. Notice that each Java class in the right-hand pane changes from red to blue--indicating that all of it's dependent classes can be resolved
When all of the classes have been resolved, click the Insert button to add the Java classes to the WAR file

3. Add JSPs and HTML files to the soap-cart.war file

Select the WAR module and right click. Select Insert from the pop-up menu
Navigate to path install_dir/ias/ias-samples/soap/cart/src/docroot/ directory and add these files:

index.html
viewBooks.jsp
viewCart.jsp

Click on Resolve to modify the location of these files relative to the root of the WAR file
Select all files using the Shift key
Delete the contents of the Update Destination Path text field (since the application requires that these files be located at the root of the WAR module). Click on Update to modify the relative location of these files within the archive. Click on OK to close the resolve dialog box
Click on Insert to close the insert dialog box and add the files to the WAR

Modify the Web Application Deployment Descriptor

1. Modify the deployment descriptor for the SOAP Cart Web Application

Click on Component View, if it's not already selected
Select the soap-cart web application, right-click and select Edit Descriptor from the pop-up menu

2. Set attributes for the soap-cart web applications deployment descriptor

In the General tab, type index.html in the Welcome Files text field and click Add. When a client tries to access the URL /NASApp/soap-cart, they will be automatically redirected to the index.html page (which will, in turn, redirect them to the controller servlet)
In the Servlet tab, click Add at the top of the window to create a new servlet mapping. In the Servlet Name field, select CartClientServlet. In the URL Pattern field, enter /controller/*. Whenever a client tries to access a URL that starts with /NASApp/soap-cart/controller, the request will be sent to the CartClientServlet
In the iAS tab, click on the Local Data Synchronization radio button. This will enable objects which are not serializable to be stored in the user session. In the SOAP Cart application, the SoapCartProxy is not serializable and it's stored in session

3. Close and save the soap-cart web application deployment descriptor. Close the descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes

Modify CartClientServlet Deployment Descriptor

1. Modify the deployment descriptor for the CartClientServlet

Click on Component View, if it's not already selected
Select the CartClientServlet class in the web application (you might have to expand the web application folder to see it), right-click and select Edit Descriptor from the pop-up menu

2. Set an initialization attribute for the CartClientServlet deployment descriptor

In the Init Params tab, click New Parameter. In the Name field, enter SOAP_ROUTER. In the Value field, enter http://localhost/NASApp/soap/rpcrouter (or a valid URL to a SOAP RPC Router). A description may be added as well. The CartClientServlet uses this parameter to determine where to find the SOAP RPC Router. Using this parameter, it's possible to change to a different SOAP server without recompiling the code

3. Close and save the CartClientServlet deployment descriptor. Close the descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes

Save SOAP Cart Web Application Archive

Select the soap-cart.war module and then select Save from the File menu.

Now that the EJB JAR and Web Application components have been assembled, they can each be deployed to the iPlanet Application Server.

Deploying Components using Deployment Tool

Open the Components in the Deployment Tool

If you've followed the instructions for assembling the soap-cart.war and soap-cartEjb.jar, they should already be open in the Deployment Tool and you can skip to the next sub-section and proceed to deploying the modules. If you want to deploy the pre-built components that are included with the sample application, the following steps are required:

1. Launch the Deployment Tool:

UNIX: Execute install_dir/ias/bin/deploytool&
Windows: Programs->iPlanet Application Server 6.0->iAS Deployment Tool

2. Open the pre-built soap-cartEjb.jar file. This can be done either by selecting Browse for more applications from the initial dialog box or by selecting Open from the File menu. The EJB JAR file can be found in the following location: install_dir/ias/ias-samples/soap/cart/soap-cartEjb.jar

3. Open the pre-built soap-cart.war file. To do this, select Open from the File menu. The web application archive can be found in the following location: install_dir/ias/ias-samples/soap/cart/soap-cart.war

Deploy the Application Components

1. Select the soap-cartEjb file in the EJB Modules window

2. Select File -> Deploy from the menu bar

3. If you have not already registered a target application server, do so now by clicking on the Register button. Enter the host name, administrative port number (typically 10817) and username/password for the target application server. Otherwise, select a pre-registered target server

4. Click Deploy to start the deployment process. The file transfer and application registration process will begin. See the Deploy tab for the status of the deployment. The deployment may take several minutes to complete

6. Repeat the deployment process for the soap-cart web application module

Now that all of the components have been registered with the iPlanet Application Server, the only remaining step is to register the SOAP Shopping Cart Service.

Registering the SOAP Shopping Cart service

A soap service can be registered either via a command line tool or via the Apache SOAP web administration tool (to use Ant to automate this registration process, see the Command-Line Assembly and Deployment documentation, step four). Both the SOAP command-line and web-based registration utilities are described in the sub-sections below.

Before registering the SOAP service, however, the Java class file should be moved so it is in the application server's classpath. To do this:

1. Compile the Java source files. If this has not already been done, refer to the previous section on source file compilation

2. Copy the service class file to the application server's classpath. By convention, we'll use the install_dir/ias/APPS/soap-services/ directory, which should have been added to the application server classpath when SOAP was installed and configured

Copy the file: install_dir/ias/ias-samples/soap/cart/build/classes/samples/soap/cart/soap/CartService.class
To: install_dir/ias/APPS/soap-services/samples/soap/cart/soap/CartService.class

Command Line Based SOAP Service Registration

Since a deployment descriptor for the Shopping Cart service is already provided, the fastest means of registering the service is to use the command line utilities described in this section. The registration tool is a Java program that comes with the Apache SOAP distribution. To use it, following these steps:

1. Set the classpath appropriately in the current shell. The soap.jar and xerces.jar libraries must be on the classpath when the registration utility is executed. If it hasn't already been set correctly, shell scripts have been provided to correctly set the environment. These scripts are titled soap_env.bat and soap_env.sh, and they're located in the install_dir/ias/ias-samples/soap/docs/ directory. Before executing the scripts, verify that the environment variables (IAS_HOME, SOAP_HOME, XERCES_HOME, and SERVICES_HOME) at the top of each script are set correctly

2. Change directories to the SOAP Shopping Cart sample application directory (cd install_dir/ias/ias-samples/soap/cart/src)

3. Execute the Apache SOAP registration utility using the XML deployment descriptor file provided (DeploymentDescriptor.xml). The utility uses the following format:

java org.apache.soap.server.ServiceManagerClient [url] [operation] [arguments]

To deploy the shopping cart SOAP service, use the following command line:

java org.apache.soap.server.ServiceManagerClient http://localhost/NASApp/soap/rpcrouter deploy DeploymentDescriptor.xml

Web-Based SOAP Service Registration

With the Apache SOAP Administration Tool, it is possible to use a Web browser to deploy and un-deploy services. It is also possible to review the list and the definitions of the services deployed to a SOAP server. To deploy the shopping cart service, following these steps :

Point your browser to http://<web server host>/NASApp/soap/admin/index.html (for example, http://localhost/NASApp/soap/admin/index.html) to access the Apache SOAP Administration application
Click on Deploy button in the left pane
A web form will appear where you can fill the information about your soap service

For ID enter urn:ShoppingCart
For Scope of the service enter session
For Method List enter 'getSelectedBooks addBook removeBook removeCart' without any quotes
For Provider type enter java
For Java services, Provider class enter samples.soap.cart.soap.CartService (which is the fully qualified name of the service class)
For Java services, Use static class select no.
You need to define one type mapping. In type mapping section

In the first row, enter SOAP for Encoding Style, urn:xml-soap-shoppingcart-demo for Namespace uri, book for Local Part, samples.soap.cart.Book for Java Type, org.apache.soap.encoding.soapenc.BeanSerializer for Java to XML Serializer, org.apache.soap.encoding.soapenc.BeanSerializer for XML to Java Deserializer.

All other fields in the forms are not required for deploy this service. If you want to get more information about these fields. Please refer to the Apache SOAP documentation

Submit the form. The service will be deployed and ready to be used by a SOAP client

Running the Sample Applications

Now that components are registered in the iPlanet Application Server and the service has been deployed to the SOAP server, the sample applications may be run. For instructions on running the sample applications, click here.

SOAP Shopping Cart Sample - Deployment without Ant iPlanetTM Application Server Samples