Installing Apache SOAP on iPlanet
iPlanet^TM Application Server Samples

Updated June 18, 2001

If you already went through the process of installing Apache SOAP on iPlanet Application Server using this machine, you can access the SOAP administration page by clicking here.

This document describes how to install Apache SOAP 2.2 on iPlanet Application Server 6.0 and how to exercise the samples bundled with the Apache distribution. The document is organized into several sections:

Installing Apache SOAP
Configuring the Client Environment

Registering and Exercising the Apache SOAP Samples
Next Steps
Changing Location of the Deployed Services Configuration File (optional)

Installing Apache SOAP

Apache SOAP 2.2 is not bundled with iPlanet Application Server but must be downloaded from the Apache web site and installed. The following instructions provide a streamlined set of steps for installing Apache SOAP 2.2 on iPlanet Application Server. Each step is explained in the subsections below:

Download Apache SOAP 2.2 Binary Distribution
Deploy the Apache SOAP Web Application
Modify Application Server Classpath
Test the Apache SOAP Installation

For general Apache SOAP installation information, refer to http://xml.apache.org/soap/docs/index.html

1. Download Apache SOAP 2.2 Binary Distribution

Go to http://xml.apache.org/dist/soap/ and download the latest release of Apache-SOAP version 2.2.

For Windows, download soap-bin-2.2.zip

For UNIX, download soap-bin-2.2.tar.gz

Extract the SOAP distribution to a suitable location on your machine's file system. For example, to c:\soap-2_2\ or /opt/soap-2_2/.

2. Deploy the Apache SOAP Web Application

The SOAP web application archive, soap.war, must be modified before being deployed to the iPlanet Application Server. The Deployment Tool will be used to automatically add an iPlanet Application Server-specific deployment descriptor to the WAR file. Before doing this, you may want to create a backup of the original soap.war file.

Start the iPlanet Application Server Deployment Tool
Open the soap.war file from the expanded Apache SOAP distribution. This file is located under soapinstalldir/webapps/soap.war. If a dialog box warns that a number of class references cannot be resolved, ignore the warning as supporting libraries will be added to the server's classpath in the next section. When asked to add iPlanet deployment descriptor, click OK
Select the WAR file from the list of Web Applications. Right-click and select Edit Descriptor from the pop-up menu. In the iAS tab, click on the Local Data Synchronization radio button so that it is unselected. Since the Apache SOAP implementation stores non-serializable objects in user session, this step is required to disable session synchronization for the SOAP web application. Close the deployment descriptor window and be sure to save its contents
Save the modified soap.war file
Deploy the soap.war module to the application server

Upon deployment, the SOAP web application is installed in the install_dir/APPS/modules/soap/ directory of the application server. If you browse the WEB-INF/classes/ directory of the deployed web application, you'll note that the Java classes for Apache SOAP sample services are included in the web application.

3. Modify Application Server Classpath

To use Apache SOAP with iPlanet Application Server, you need to add several JAR files to the application server's classpath.

Library Requirements

Library Name	Description	Required?
JAXP Parser (e.g. xerces.jar)	XML Parser library. Download a copy of a JAXP-compatible, namespace-aware XML parser such as Xerces version 1.4 or later. The Xerces Java Parser has been shown to work properly with Apache SOAP 2.2. To avoid conflicts with an XML parser bundled with the application server, ensure the JAXP compatible parser appears at the start of the application server's classpath	Yes
SOAP Services	As SOAP services are developed, the service classes must be accessible to the Apache SOAP web application via the application server's classpath. This document will use the convention of deploying these classes to the following directory: install_dir/ias/APPS/soap-services/	Yes
mail.jar	JavaMail library. Note that this library is already in the application server's classpath and does not need to be added again	Included by default
activation.jar	JavaBeans Activation Framework library. By default, this library is also part of the application server's classpath and does not need to be added again	Included by default
bsf.jar	Bean Scripting Framework library. This library is used by some of the Apache SOAP samples that rely on server side scripting languages (such as the calculator sample application). Refer to the Apache SOAP installation instructions for pointers to the BSF libraries	No
js.jar	Rhino JavaScript library. This library is used in conjunction with BSF to provide support for JavaScript. It can be downloaded from the Mozilla.org site (look for the latest BSF-compatible library)	No

Note that Apache SOAP infrastructure library, soap.jar, is not added to the application server's classpath. Since the Apache SOAP infrastructure classes are already present in the soap.war file, the application server automatically loads these infrastructure classes from the WAR file as the Apache SOAP router servlet is accessed. The same holds true for the Apache SOAP sample application classes. Since these classes are built into the soap.war file, you do not need to make them accessible via the application server's classpath.

Modify Classpath Settings on Windows

On Windows, the application server uses a classpath specified in the application server's registry. (Setting the Windows system environment variable classpath will not affect the setting used by the application server.) To modify the registry:

Execute kregedit, the application server's registry editor
Navigate to SOFTWARE\iPlanet\Application Server\6.0\Java
Select ClassPath and the select Edit->Modify to change the value.
Add the SOAP-related JAR files to front of the classpath. For example:

c:\xerces-1_4_0\xerces.jar;c:\iplanet\ias6\ias\APPS\soap-services;c:\bsf-2_2\lib\bsf.jar;c:\rhino\js.jar;...

Restart the application server to load the new classpath setting.

Modify Classpath Settings on UNIX

On UNIX, it is necessary to modify a shell script which sets the server classpath. While the modifications are nearly identical, the script which must be edited depends on which version of the application server is used.

For iPlanet Application Server 6.0 SP2 and earlier, modify the install_dir/ias/bin/kjs script.

...
SOAP_CLASSES=/opt/xerces-1_4_0/xerces.jar:$GX_ROOTDIR/APPS/soap-services:/opt/bsf-2_2/lib/bsf.jar:/opt/rhino/js.jar
CLASSPATH=$SOAP_CLASSES:$THIRD_PARTY_JDBC_CLASSPATH:$GX_ROOTDIR/classes/java/jdbc20.jar:
$GX_ROOTDIR/classes/java/javax.jar:...

For iPlanet Application Server 6.0 SP3 and later, modify the install_dir/ias/env/iasenv.ksh script.

...
# Union of all CLASSPATHS
SOAP_CLASSES=/opt/xerces-1_4_0/xerces.jar:${IAS_ROOT}/APPS/soap-services:/opt/bsf-2_2/lib/bsf.jar:/opt/rhino/js.jar
export CLASSPATH=$SOAP_CLASSES:${TOMCAT_DIR}/jasper.jar:...

Restart the application server to load the new classpath settings.

4. Test the Apache SOAP Installation

Access the following URL to start the administrative interface. (Note that because the Apache SOAP WAR does not define a default "welcome" page, you must include index.html in this URL -- if it is omitted, an error will occur.)

http://<web server host>/NASApp/soap/admin/index.html

For example http://localhost/NASApp/soap/admin/index.html

Access the RPC Router and Message Router Servlets by accessing the following URLs:

http://<web server host>/NASApp/soap/servlet/rpcrouter

For example http://localhost/NASApp/soap/servlet/rpcrouter

http://<web server host>/NASApp/soap/servlet/messagerouter
For example http://localhost/NASApp/soap/servlet/messagerouter

If your Apache SOAP installation is correct, the browser will display:

SOAP (RPC|Message) Router
Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

Now that you've performed a basic test of the environment, you're ready to configure your client environment and exercise the sample applications.

Configuring the Client Environment

To register SOAP services and to run Java-based client applications, you must add several JAR files to your client's classpath:

Library Name	Description	Location
mail.jar	JavaMail API	install_dir/ias/classes/java/mail.jar
activation.jar	JavaBeans Activation Framework	install_dir/ias/classes/java/activation.jar
soap.jar	Apache SOAP infrastructure	soapinstalldir/lib/soap.jar
xerces.jar (or equivalent)	A JAXP compatible, namespace-aware XML parser such as Xerces 1.4.0	xercesinstalldir/xerces.jar

SOAP Client Environment Scripts

To help include the necessary libraries in the client's environment, shell scripts have been provided to correctly set the client's classpath. These scripts are named soap_env.bat and soap_env.sh for Windows and UNIX environments respectively, and they're located in the install_dir/ias-samples/soap/docs/ directory. Before executing the scripts, ensure that the environment variables (IAS_HOME, SOAP_HOME, and XERCES_HOME) at the top of each script are set correctly.

Registering and Exercising the Apache SOAP Samples

Each sample bundled with Apache SOAP 2.2 includes a script to register and exercise the service. The following steps are required to run the samples:

Set Client Environment
Edit testit Scripts to Reflect RPC Router URL
Run testit Scripts
Troubleshooting

1. Set Client Environment

It is recommended that you use the SOAP Client Environment Scripts to set your client environment prior to running the Apache SOAP samples. You'll note that the sample environment scripts include the Apache SOAP installation directory in the client's classpath. This setting ensures that the client side sample application classes are available to the testit scripts.

2. Edit testit Scripts to Reflect RPC Router URL

Go to the soapinstalldir/samples/addressbook/ directory and edit either the testit.cmd or testit.sh script depending on your OS platform. You will need to perform a replace all on the URL of the rpcrouter servlet to match your application server deployment. For example, throughout the testit script, the string:

http://localhost:8080/soap/servlet/rpcrouter

will need to be changed to:

http://<hostname>:<port>/NASApp/soap/servlet/rpcrouter

3. Run the testit Script

Double-check to ensure that your client's classpath is set appropriately. Then execute the testit script. For example, when running the addressbook sample, you should see the following output in the client window:

D:\soap-2_2\samples\addressbook>testit

This test assumes a server URL of http://127.0.0.1/NASApp/soap/servlet/rpcrouter

Deploying the addressbook service...

     .

     Verify that it's there

     Deployed Services:

     urn:AddressFetcher

     .

     Getting info for "Mr Good"

123 Main Street

     Anytown, NY 12345

     (123) 456-7890

     .

     Adding "John Doe"

     John Doe has been added.

     .

     Query "Mr Doe" to make sure it was added

123 Main Street

     AnyTown, SS 12345

     (800) 555-1212

...

  <Listing>

    <Name>Mary Smith</Name>

    <Address>

      <StreetNum>888</StreetNum>

      <StreetName>Broadway</StreetName>

      <City>Somewhere</City>

      <State>FL</State>

      <Zip>87654</Zip>

      <PhoneNumber>

        <AreaCode>222</AreaCode>

        <Exchange>333</Exchange>

        <Number>4444</Number>

      </PhoneNumber>

    </Address>

  </Listing>

</AddressBook>

.

Undeploy it now

.

Verify that it's gone

Deployed Services:

If you successfully ran the address sample, then proceed to the Next Steps.

4. Troubleshooting

If you encounter the following messages when running a sample, the most likely cause is not having the JAXP compatible parser library at the front of the server's classpath:

D:\soap-2_2\samples\addressbook>testit

This test assumes a server URL of http://127.0.0.1/NASApp/soap/servlet/rpcrouter



Deploying the addressbook service...

Ouch, the call failed:

  Fault Code   = SOAP-ENV:Server.Exception:

  Fault String = java.lang.NoSuchMethodError

...

This error occurs because the XML parser bundled with the application server does not contain a class required by Apache SOAP. Ensure that a JAXP-compatible parser is correctly specified at the start of the applicat server's classpath.

If you encounter errors when running the Calculator sample, ensure that you've added both the bsf.jar and js.jar libraries to the start of the application server's classpath.

Next Steps

Try the remaining samples. Review the readme file for each sample to understand the intent of the sample.

Experiment by modifying the testit scripts to leave services registered. Restart the application server to observe that registration of services is persistent across server restarts.

Access the Apache SOAP administrative interface to list the registered services:

http://<web server host>/NASApp/soap/admin/index.html

For example http://localhost/NASApp/soap/admin/index.html

Select the List option to list the deployed services. Drill down into each service to see the detailed configuration of the service. Since the Calculator service is based on JavaScript, you will see the script code for this service as you list it in the administrative interface.

To exercise more complex examples that involve SOAP services interacting with EJBs, proceed to the Registering and Exercising the iPlanet SOAP Samples section of the documentation.

Changing the Location of the Deployed Services Configuration File (optional)

The Apache SOAP infrastructure relies on a file named DeployedServices.ds to retain the configuration of deployed SOAP services. This file enables the Apache SOAP infrastructure to reload service configuration data as the application server is restarted. When Apache SOAP is deployed to iPlanet Application Server, the default location for this file is:

install_dir/ias/DeployedServices.ds

You can override this default location by creating a soap.xml file containing the path and file name of a services configuration file. The Apache SOAP web application's deployment descriptor also needs to be modified to refer to the location of the soap.xml configuration file.

If you've already deployed SOAP services using the default services configuration file, copy the content of the DeployedServices.ds file to the new location of the services configuration file (the name of the file may be changed as desired).

To change the default location of the services configuration file, follow these steps:

Create a soap.xml file containing a pointer to the new location of the services configuration file. By default, the soap.xml file does not exist in a simple installation of Apache SOAP. If you want to change the location of the services configuration file, you must create a soap.xml file that refers to the new services configuration file. In subsequent steps, you'll modify the web application to point to the location of this soap.xml file.

soap.xml

<soapServer>

  <configManager value="org.apache.soap.server.DefaultConfigManager" >

      <option name="filename" value="d:\soap-2_2\DeployedServices.ds" />

  </configManager>

</soapServer>

Open soap.war in Deployment Tool.
In ComponentView, select the messagerouter servlet that is part of the SOAP Web Application. Right-click on the servlet and select Edit Descriptor

Under the Init Param tab, click on the New Parameter... button and enter the following information:

Name:

Value:

soap.xml

C:\soap-2_2\soap.xml

Description (optional):

Close and save the deployment descriptor. This will add the following element to the web.xml deployment descriptor:

<servlet>

  <servlet-name>messagerouter</servlet-name>

  <display-name>Apache-SOAP Message Router</display-name>

  <servlet-class>org.apache.soap.server.http.MessageRouterServlet</servlet-class>

  <init-param>

    <param-name>faultListener</param-name>

    <param-value>org.apache.soap.server.DOMFaultListener</param-value>

  </init-param>

  <init-param>

    <param-name>ConfigFile</param-name>

    <param-value>d:\soap-2_2\soap.xml</param-value>

    <description>Location of the SOAP configuration file</description>

  </init-param>

</servlet>

Repeat the previous step for the rpcrouter servlet
Save the WAR file and redeploy it to the application server
Because this change require deployment descriptors to be modified, the application server must be restarted for the changes to take effect

To verify that services are now saved to the new file, comment out the undeploy steps in one of the sample testit scripts and rerun the script. Open the services configuration file in an editor to double check that the services are being registered in the new file. Use the Apache SOAP administrative interface to ensure that the service configuration was persisted to the new configuration file.

For more information on other Apache SOAP configuration file settings, refer to the documentation on the Apache SOAP website.

Installing Apache SOAP on iPlanet iPlanetTM Application Server Samples

Installing Apache SOAP

1. Download Apache SOAP 2.2 Binary Distribution

2. Deploy the Apache SOAP Web Application

3. Modify Application Server Classpath

Library Requirements

Modify Classpath Settings on Windows

Modify Classpath Settings on UNIX

4. Test the Apache SOAP Installation

Configuring the Client Environment

SOAP Client Environment Scripts

Registering and Exercising the Apache SOAP Samples

1. Set Client Environment

2. Edit testit Scripts to Reflect RPC Router URL

3. Run the testit Script

4. Troubleshooting

Next Steps

Changing the Location of the Deployed Services Configuration File (optional)

Installing Apache SOAP on iPlanet
iPlanet^TM Application Server Samples