Table of Contents
Getting started with Apache SAP web services
If you have been following along in this series of articles you should be familiar with the following:
What is a Web Service?
As a SAP developer, why should I care about Web Services?
What are some technologies used to build Web Services?
What is SOAP?
Are there toolkits to help me?
As mentioned previously, we are going to be using the Apache SOAP toolkit to help us build Web Services. Although this toolkit can work with other J2EE Application Servers, its originally targeted platform is Tomcat. Therefore, we need to download and install Tomcat. Point your browser to http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.2.4/bin/ and right-click on the jakarta-tomcat-3.2.4.zip link. Select "Save Target As..." and save this file locally.
Unzip this file to a directory. I am going to use d:jakarta-tomcat-3.2.4. After unzipping the file, you should have the following subdirectories: bin, conf, doc, lib, logs, src, and webapps. You then need to set an environmental variable called TOMCAT_HOME to this directory (ex. set TOMCAT_HOME=d:jakarta-tomcat-3.2.4).
For Tomcat to run properly, you must have Java 1.2 or higher installed. If you have not already done this, point your browser to http://java.sun.com/j2se/1.4/download.html and download the SDK for Windows. You should then receive an EXE file. Execute this file and follow the installation instructions.
Installing Apache SOAP
Now its time to download Apache SOAP. Point your browser to http://xml.apache.org/dist/soap/version-2.3.1/ and right-click on the soap-bin-2.3.1.zip link. Select "Save Target As..." and save this file locally.
Unzip this file to a directory. I am going to use d:soap-2_3_1. After unzipping the file, you should have the following subdirectories: bin, conf, docs, lib, samples, and webapps. You then need to set an environmental variable called SOAP_HOME to this directory (ex. set SOAP_HOME=d: soap-2_3_1).
Configuring Tomcat to work with SOAP
You must now copy files from the SOAP_HOME directories to the TOMCAT_HOME directories. Copy SOAP_HOMElibsoap.jar to TOMCAT_HOMElib. Also, copy SOAP_HOMEwebappssoap.war to TOMCAT_HOMEwebapps.
Apache SOAP relies on several libraries that must be correctly installed before it will work properly. To see a list of these, view the file index.html in the SOAP_HOMEdocs directory and look for the Requirements & Limitations heading.
Point your browser at http://java.sun.com/products/javamail/ and download the JavaMail API Implementation Version 1.3. This will download a file called javamail-1_3.zip. Extract the mail.jar file from the zip file and copy it to the TOMCAT_HOMElib directory.
Point your browser at http://java.sun.com/products/javabeans/glasgow/jaf.html and download the JavaBeans Activation Framework 1.0.2 release. This will download a file called jaf-1_0_2.zip. Extract the activation.jar file from the zip file and copy it to the TOMCAT_HOMElib directory.
Point your browser at http://www.alphaworks.ibm.com/aw.nsf/download/xml4j, and download the file XML4J-bin.4.0.1.zip. Extract the files xercesImpl.jar and xmlParserAPIs.jar and copy them to the TOMCAT_HOMElib directory. Rename xercesImpl.jar to xerces.jar and xmlParserAPIs.jar to xml4j.jar.
Setting the CLASSPATH
To build clients that access our Web Services, we need to add the above files to the CLASSPATH environmental variable. Add the following files to this variable in this order: %SOAP_HOME%libsoap.jar;%TOMCAT_HOME%libxerces.jar;%TOMCAT_HOME%libxml4j.jar;%TOMCAT_HOME%libmail.jar;%TOMCAT_HOME%libactivation.jar
Testing our installation
At this point, we would like to see if everything is installed correctly. Start Tomcat by opening a command window, going to the TOMCAT_HOMEbin directory and execute "tomcat run". You may want to change the height of the screen buffer size of this window to be able to scroll through Tomcat messages.
Now point your browser to http://localhost:8080/soap/index.html and then click on the Visit link. The browser should then display the message: Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.
If you do not see this message, you probably have not installed all of the above files correctly. From the error message in the browser and in the command window, try to determine which jar file needs to be placed in the TOMCAT_HOMElib directory.
Now we want to make sure the CLASSPATH variable has been set correctly. In another command window, type all of the following and then press enter:
java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter list. This command tells Tomcat and Apache SOAP to list the currently deployed Web Services. Since we have not yet created or deployed any Web Services, this is a blank list and you should see the message: Deployed Services:, followed by a blank line.
Just like before, if you get an error message, try to determine which jar file needs to be placed in the CLASSPATH variable.
For more information on troubleshooting your installation, view the SOAP_HOMEdocstroubleindex.html file. A useful URL for troubleshooting is http://xml.apache.org/soap/faq/faq_chawke.html.
Running some samples
There are some sample Web Services included with Apache SOAP. One of them is a client that accesses a fortune cookie Web Service. To get your fortune cookie, open a command window, go to the SOAP_HOME directory and execute java samples.lemurlabs.Fortune. This will invoke the fortune cookie Web Service running at http://www.lemurlabs.com/.
Invoking the other Apache SOAP samples requires a little more setup. First, we need Tomcat to be able to access the SOAP sample files. One way to do this is to create a classes directory under the TOMCAT_HOME directory. Then copy the SOAP_HOMEsamples directory and everything below it to the TOMCAT_HOMEclasses directory you just created. Next, add the SOAP_HOME directory to your classpath. You should now be able to run the SOAP samples.
Open a command window, go to the SOAP_HOMEsamplesaddressbook directory and execute "testit". This will deploy a new Web Service called AddressFetcher, call it several times using a Web Service client, and then undeploy it.
In the next article we will create our own Web Service that will invoke an SAP BAPI using JCo. Until then, look at the Apache SOAP samples and read the Apache SOAP documentation. There is a lot of information here!
Author Jeff Marin is director of training and education for Gamma Enterprise Technologies Inc.