The Apache-SOAP distribution can be installed for use as a client or as a server. This document provides installation instructions for both cases and also has a trouble shooting section to help sort out common installation related problems.
Important note for users upgrading from older versions of Apache SOAP: If you are upgrading from an older version of Apache SOAP then you must be sure to remove any cached class files, DeployedServices.ds files etc. or you will get a variety of strange errors. If you deployed Apache SOAP using a Web app, then any old expanded WARs must also be removed. Services deployed into the old version cannot be automatically transferred to the new version - you must manually re-deploy them to the new version. That is, the old DeployedServices.ds file cannot be read by this new version. We apologize in advanced for the pain this will cause some of our users. If you are in fact upgrading from an older version of Apache SOAP and get any funny, unusual looking exceptions or behavior, then most likely the problem is some unexpected interaction with code from the older version. Please clean up and try again or try installing in a virgin environment.
Note that if you are on a Win32 machine then you should replace "/" with "\" in file names and replace $VAR with %VAR% for environment variables as you follow these instructions.
Many installation problems are caused by conflicts between the newly installed software and software already installed as optional Java packages. Check the contents of $JAVA_HOME/jre/lib/ext. If there are any jars that are the same as those in the following instructions, or any jars that may conflict (e.g. crimson.jar, an XML parser like xerces), you should consider moving or deleting them.
You should never install any Apache SOAP jars as optional packages. On the server, you should not install any of the Apache SOAP dependency jars as optional packages unless you are sure of what you are doing.
We assume that you have downloaded the binary distribution of Apache-SOAP and have extracted the archive into the directory /foo. Thus the files from the distribution are in the directory /foo/soap-2_3/.
Your classpath must contain /foo/soap-2_3/lib/soap.jar and the following:
Additionally, to run the samples that came with the distribution, add /foo/soap-2_3 to your classpath.
To install the server-side of Apache-SOAP, you need a Web application server that supports servlets. If you want to run the GUI admin client, the application server must support Java Server Pages (JSP) as well.
The exact instructions for how to install vary from one application server to another. Links to specific instructions for some application servers appear later in this section.
In all cases, you need to ensure that the class loader for the application server's servlet container has access to the components listed above for the client installation, namely activation.jar, mail.jar, a namespace-aware XML parser, and the Apache SOAP classes. Many newer application servers, such as Tomcat 4.0, already have everything needed except for the Apache SOAP classes. In addition, to implement services in scripting languages (such as the calculator sample), make bsf.jar from BSF and js.jar from Rhino available to the class loader. Note that making classes and/or jars available to the application server's class loader may not mean simply adding them to your environment's classpath. Many application servers construct their own classpath during startup. In those cases, it may be necessary to edit a startup script or configuration file. Alternatively, some application servers reserve particular directories that class loaders will search. If you cannot follow instructions for a specific application server at one of the links below, you must understand your application server's class loading well enough to get it to load the proper classes.
For newer application servers, Apache SOAP is installed as a web application by copying or unpacking the soap.war file to a particular directory. This makes the Apache SOAP classes available to the class loader.
Here are specific instructions for some common application servers:
If your application server is not listed, see whether the instructions for another application server, such as Tomcat, give you enough hints. If not, check the FAQs at http://xml.apache.org/soap/faq or http://xml.apache.org/soap/faq/faq_chawke.html#Q3_1. If that fails, try asking on the Apache-SOAP user's list; more than likely someone else has done it already. You can subscribe to the list here: http://xml.apache.org/soap/mail.html. If you figure out how to install on an application server for which there are no instructions, please post the steps you following to the mailing list so that the next user can benefit from your work.
Point your browser to:
http://localhost:port/soap/servlet/rpcrouter
and
http://localhost:port/soap/servlet/messagerouter
where port is 8080, or 4040,
or whatever port your particular HTTP server is listening on. The
browser should display the following:
SOAP (RPC|Message) Router
Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.
If you don't see this message, your server is not configured correctly. If you do, you now know your router URLs: they are the URLs you pointed your browser to.
To test whether you have proper server and client-side stuff set up, follow the client-side instructions to put the right things on your classpath and type the following:
java org.apache.soap.server.ServiceManagerClientrpc-router-urllist
where the first argument above is the RPC router URL you determined earlier (the one with "rpcrouter" at the end). [NOTE: The above command line is one long line; your browser may show it on two lines but do NOT put it on two lines!]
If this succeeds you will see it return with no output or with a list of URIs. Either case is successful - it indicates what services are already deployed on your server. If you get anything else then its time to troubleshoot.
Getting SSL support up and running: The instructions for how to get SSL support running vary from server to server: Here are instructions for the following servers: