Installing Web Services Server

Introduction

Web Services is a method for transmitting information between a "client" and a "server" using typical web technologies. AppComposer currently has the ability for creating client-side components that can talk to web servers using SOAP,

For the web services example, MFwithServices, the server-side of this web service must be running somewhere accessible to a client built with AppComposer.

If you can't use the demo web services running on DigiSlice's site, or if you want to deploy it on your own workstation or server, follow the instructions located in this document.

Server Setup Instructions

1. Download Server Applications

This web service was tested with Tomcat and Apache Soap, but may be run on any server. The instructions included here are for Tomcat. Required downloads:

Tomcat 4.1: jakarta.apache.org/tomcat
Soap 2.3: xml.apache.org/dist/soap

You may also have to additional application or libraries in order to get the Tomcat servlet engine up and running.

2. Tomcat Installation

Install Tomcat on your local machine and verify that the installation works correctly by following its installation instructions.

Note: A common mistake during installation is that the JAVA_HOME environment variable is not set correctly. Make sure you set it to point to your JDK installation directory.

After you've verified that Tomcat is running correctly by issuing a start command. On Unix, the command would be something like the following where if the TOMCAT_HOME variable isn't set, it can be replaced with the destination of the Tomcat application directory.

$TOMCAT_HOME/bin/catalina.sh start

On Windows, the command would be something like:

%TOMCAT_HOME%\bin\catalina.bat start

And using your browser, attach to an example to page, http://yourserver:8080/examples/servlets/index.html Once you have verified that it runs, it shut it down via the following command in preparation for a later step.

$TOMCAT_HOME/bin/catalina.sh stop

3. SOAP Installation and Support Libraries

Before installing the SOAP libraries, add the following libraries to your Tomcat server. The easiest way to do that is to copy the following jars to your server system and store them somewhere they will be accessible to Tomcat, e.g. $TOMCAT_HOME/shared/lib

mail.jar from JavaMail
activation.jar from JavaBeans Activation Framework
Namespace aware XML parser, e.g. Xerces

You can use mail.jar and activation.jar from the jBoss tree included with AppComposer. Also, you can use xerces.jar from the libraries directory included with AppComposer for the XML parser. If you download the latest Xerces, version 2.x from the Apache Foundation, then the JAR files to include will be

Once these JARs have be copied to the server system, you need to tell Tomcat about them, by editing the setclasspath.bat (or setclasspath.sh) file in the %tomcat_home%/bin directory. While I'm not sure if this is recommended, you might add the following code section to setclasspath.sh ... assuming you copied the JARs into the "shared/lib" directory.

# Set standard CLASSPATH
CLASSPATH="$JAVA_HOME"/lib/tools.jar
 
for JAR in "$BASEDIR"/shared/lib/*.jar 
do 
  CLASSPATH="$CLASSPATH:$JAR" 
done

The Apache SOAP distribution includes a web archive at /soap-2_3/webapps/soap.war. Simply drop this web archive into Tomcat's webapps directory (i.e. %tomcat_home%/webapps). If you deploy Apache SOAP into Tomcat in this manner, you will not need to have anything from the /soap-2_3 directory on your server's classpath (the relevant items are included in the web archive). Note: If you copy the web archive into the webapps directory while Tomcat is running, Tomcat will need to be restarted before the Apache SOAP web application can be accessed.

4. Verify SOAP Installation

Start up Tomcat again and make sure that no errors appear in the startup information. Once this is done successfully, point a browser at (replacing the 8080 with the number you used during installation):

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

You should see the message:

Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

This means that you have set up SOAP correctly. Stop Tomcat again.

5. Setting up the Web Service

Included with the AppComposer installation is a directory called %appcomposer%/examples/MFwithServices/service. In this directory is a jar file named FundService.jar. Add this jar to Tomcat's classpath and restart Tomcat.

6. Command Line Verification of Client Side Service

The least problematic way to set up a client to deploy the web service (to verify that your web service is funcational) is via the following the command-line calls.

Include the JDK on your path. In Windows, this command looks like:
```
C:\>set path=c:\jdk1.3.1_06\bin;%PATH%
```
Set up your classpath to include mail.jar, activation.jar, and xerces.jar as well as %soap%/lib/soap.jar. In Windows, this command looks like the following (and keep in mind that this command must be on a single line, but is wrapped to be more readable:
```
C:\>set classpath=%appcomposer%\jBoss\server\all\lib\mail.jar;
    %appcomposer%\jBoss\server\all\lib\activation.jar;
    %appcomposer%\libraries\thirdparty\xerces.jar;
    %appcomposer%\libraries\thirdparty\soap.jar
```
Test your client side set up with the following command:
```
C:\>java org.apache.soap.server.ServiceManagerClient <rpc-router-url> list
```
Where rpc-router-url is the same URL you used in step 4. At this point, if everything is set up correctly, you should see a message that says "Deployed Services:" with an empty list - you haven't deployed anything yet!!
Deploy FundService with the following command (keeping in mind that this command must be entered on a single line ... it is broken into multiple lines to be more readable:
```
C:\>java org.apache.soap.server.ServiceManagerClient 
    <rpc-router-url> deploy 
    %appcomposer%\examples\MFwithServices\service\DeploymentDescriptor.xml
```
If you rerun the list command at this point from step c above, you should now see the following: Deployed Services: urn:DigiSliceFundService
To test the service, run the included TestClient located in the service directory:
```
java TestClient <rpc-router-url> fund01
```
The response should be: "fund_alpheus-customer.html" if everything is set up correctly. If you get a java.lang.NoClassDefFoundError, then you will have to add the "service" directory to your classpath, via:
```
set classpath=%appcomposer%\examples\MFwithServices\service;%classpath%
```