This document describes how to install Apache SOAP 2.3 on iPlanet Application Server 6.0 and how to exercise the Apache SOAP samples.
Registering and Exercising the Apache SOAP Samples
Changing Location of the Deployed Services Configuration File
Upon deployment, the SOAP web application is installed in the installdir/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.
Download a copy of a JAXP compatible, namespace-aware XML parser such as Xerces. Version 1.4 or later of the Xerces Java Parser has been shown to work properly with Apache SOAP 2.3.
To avoid conflicts with the XML parser bundled with the application server, you must ensure that the JAXP compatible parser library appears at the start of the application server's classpath.
If you plan on exercising the Apache SOAP samples that rely on server side scripting languages such as JavaScript, then download the Bean Scripting Framework and Rhino JavaScript libraries and add the bsf.jar and js.jar files to the front of the application server's classpath. Refer to the Apache SOAP installation instructions for pointers to these supporting JAR files.
Since mail.jar and activation.jar are already present in the server classpath, you do not need to perform any special setup to enable Apache SOAP to access these libraries.
On Windows the application server uses the CLASSPATH setting defined 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:
d:\rhino\js.jar;d:\bsf-2_2\lib\bsf.jar;d:\xerces-1_4_0\xerces.jar;...
Modify the installdir/ias/bin/kjs script to include the supporting JAR files. The kjs script starts the JVM that houses the application server's web and EJB containers.
installdir/ias/bin/kjs:
...
SOAP_CLASSES=/opt/rhino/js.jar:/opt/bsf-2_2/lib/bsf.jar:/opt/xerces-1_4_0/xerces.jar
CLASSPATH=$SOAP_CLASSES:$THIRD_PARTY_JDBC_CLASSPATH:$GX_ROOTDIR/classes/java/jdbc20.jar:
$GX_ROOTDIR/classes/java/javax.jar:...
Restart the application server to pick up the classpath changes.
In iPlanet Application Server 6.0 SP3 the classpath setting used by the kjs shell script is housed in a common environment setting shell script. Make changes to the kjs CLASSPATH variable in the
installdir/ias/iasenv.ksh:
...
# Union of all CLASSPATHS
SOAP_CLASSES=/opt/rhino/js.jar:/opt/bsf-2_2/lib/bsf.jar:/opt/xerces-1_4_0/xerces.jar
export CLASSPATH=$SOAP_CLASSES:${TOMCAT_DIR}/jasper.jar:...
Restart the application server to pick up the classpath changes.
Access the following URL to start the administrative interface:
Access the RPC Router and Message Router Servlets by accessing the following URLs:
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 are ready to configure your client environment and exercise sample applications.
Since the application server's web container does not by default load index.html files, you must include the index.html file names in the URLs. Otherwise, you will encounter a GX Error in the browser when attempting to access a URL such as NASApp/soap/admin/.
To register SOAP services and to run Java-based client applications, you must add several JAR files to your client's classpath:
| JAR | Description | Location |
| mail.jar | JavaMail API | installdir/ias/classes/java/ |
| activation.jar | JavaBeans Activation Framework | installdir/ias/classes/java/ |
| soap.jar | Apache SOAP infrastructure | soapinstalldir/lib/soap.jar |
| xerces.jar (or equivalent) | A JAXP compatible, namespace-aware XML parser such as Xerces. | xercesinstalldir/xerces.jar |
To register and run the Apache SOAP 2.3 samples, you also need to add the location of the samples directory to your client classpath.
On Windows, the client classpath setting might resemble the following:
set IAS_HOME=d:\iplanet\ias6\ias
set CLASSPATH=%IAS_HOME%\classes\java\mail.jar;%IAS_HOME%\classes\java\activation.jar;
c:\xerces-1_4_0\xerces.jar;c:\soap-2_3\lib\soap.jar;c:\soap-2_3;%CLASSPATH%
On UNIX, the client classpath setting might resemble the following:
export IAS_HOME=/usr/iplanet/ias6/ias
export CLASSPATH=$IAS_HOME/classes/java/mail.jar:$IAS_HOME/classes/java/activation.jar:
/opt/xerces-1_4_0/xerces.jar:/opt/soap-2_3/lib/soap.jar:/opt/soap-2_3:$CLASSPATH
Each sample bundled with Apache SOAP 2.3 includes a script to register and exercise the samples. Since the supporting Java classes for the Apache SOAP sample services have already been deployed as part of the SOAP web application, you do not need to move these classes to the application server. The sample scripts will only register the already deployed SOAP services with the Apache SOAP runtime.
1. Edit testit Scripts to Reflect RPC Router URL
2. Run testit
Scripts
3. Troubleshooting
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
Doublecheck 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_3\samples\addressbook>testit
This test assumes a server URL of http://127.0.0.1/NASApp/soap/servlet/rpcrouterDeploying 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 added123 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.
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_3\samples\addressbook>testit This test assumes a server URL of http://127.0.0.1/NASApp/soap/servlet/rpcr 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. Once you place a JAXP compatible parser at the front of the server's classpath, you will solve this problem.
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.
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:
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.
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:
installdir/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. (You may change the name of the file as desired).
To change the default location of the services configuration file, you must follow these steps:
1. Create a soap.xml file containing a pointer to the new location of the
services configuration file.
2. Open soap.war in Deployment Tool
3. Add initialization
parameters to the rpcrouter and messagrouter servlets. These parameters point to
the location of a new soap.xml file.
4. Copy old DeployedServices.ds file to new location. (optional)
5. Redploy
the soap.war
module.
6. Restart the application server.
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 the next section, you will modify the web application to point to the location of the soap.xml file).
For the purposes of specifying the location of a service configuration file, the soap.xml file takes the following form:
<soapServer>
<configManager value="org.apache.soap.server.DefaultConfigManager" >
<option name="filename" value="d:\soap-2_3\DeployedServices.ds" />
</configManager>
</soapServer>
In the web.xml file, the initialization parameters in the web application deployment descriptor takes the following form:
<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_3\soap.xml</param-value>
</init-param>
</servlet>
The new <init-param> must be added to the <servlet> section for both the messagerouter and rpcrouter servlets.
To make this change via the Deployment Tool, follow these steps:
Now comment out the undeploy steps in several of the sample testit scripts for the sample applications. Then rerun these scripts. Restart the application server and use the Apache SOAP administrative interface to ensure that the service configuration was persisted to the new configuration file. Open the services configuration file in an editor to double check that the services are being registered in the new file.
Apache SOAP includes providers for exposing EJBs as SOAP services. The provider and parameters for the EJB are specified in the deployment descriptor for the service. An example is:
<?xml version="1.0"?>
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:ejbhello">
<isd:provider type="org.apache.soap.providers.StatelessEJBProvider"
scope="Application"
methods="create">
<isd:option key="JNDIName" value="ejb/TheGreeter" />
<isd:option key="FullHomeInterfaceName"
value="samples.helloworld.ejb.GreeterHome" />
<isd:option key="ContextProviderURL" value="" />
<isd:option key="FullContextFactoryName"
value="com.netscape.server.jndi.RootContextFactory"/>
</isd:provider>
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>
Apache SOAP must be able to load the classes referenced in this file, namely the home interface for EJB and the context factory, as well as classes on which those depend. The context factory is already loadable from Web applications. The EJB classes or jars should be copied to the WEB-INF/classes or WEB-INF/lib, respectively, directory of the SOAP web application.