snichol 2002/10/10 07:16:35
Modified: java/docs/install index.html
Log:
Explain and clarify class loading issues better, especially potential
conflicts with optional packages (lib/ext) and the vagaries of
application server class loaders.
Revision Changes Path
1.31 +65 -23 xml-soap/java/docs/install/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/install/index.html,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- index.html 8 Oct 2002 14:49:53 -0000 1.30
+++ index.html 10 Oct 2002 14:16:35 -0000 1.31
@@ -35,16 +35,31 @@
version. Please clean up and try again or try installing in a
virgin environment.</p>
+<p>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.</p>
+
+<h3>Check optional Java packages</h3>
+
+<p>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.</p>
+
+<p>You should <strong>never</strong> 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.</p>
+
<h3>Unpack the Distribution</h3>
<p>We assume that you have downloaded the binary distribution of
Apache-SOAP and have extracted the archive into the directory <tt>/foo</tt>.
Thus the files from the distribution are in the directory
<tt>/foo/soap-2_3/</tt>.</p>
-<p>Note that if you are on a Win32 machine then you should
-replace "/" with "\" as you follow these
-instructions.</p>
-
<h3>Client-Side Instructions</h3>
<p>Your classpath must contain <strong>/foo/soap-2_3/lib/soap.jar</strong>
@@ -62,7 +77,9 @@
Xerces</a> (v1.1.2 or later). If you have other non-namespace
aware XML parsers on your classpath then the namespace-aware
parser must be at the front of your classpath. Apache
- SOAP will not work otherwise.</li>
+ SOAP will not work otherwise. Note that the names of the jars
+ required vary between XML parsers, and sometimes even between
+ different versions of the same parser.</li>
</ul>
<p>Additionally, to run the samples that came with the
@@ -71,21 +88,43 @@
<h3>Server-Side Instructions</h3>
-<p>You need to ensure that the server classpath contains all of
-the above components. In addition, to implement services in
-scripting languages (such as the calculator sample), add <strong>bsf.jar</strong>
+<p>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.</p>
+
+<p>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.</p>
+
+<p>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 and later, already have everything needed
+except for the Apache SOAP classes. In addition, to implement services in
+scripting languages (such as the calculator sample), make <strong>bsf.jar</strong>
from <a
href="http://oss.software.ibm.com/developerworks/projects/bsf";>BSF</a>
and <strong>js.jar</strong> from <a
-href="http://www.mozilla.org/rhino/";>Rhino</a> to your classpath.</p>
-
-<p>To install the server-side of Apache-SOAP, you need a Web
-application server that supports servlets and JSPs (if you want
-to run the admin client as well). </p>
+href="http://www.mozilla.org/rhino/";>Rhino</a> 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.</p>
+
+<p>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.</p>
-<p><strong>Installing the router servlets and admin client:</strong>
-The instructions for how to install varies from one app server to
-another. Here are instructions for the following servers:</p>
+<p>Here are specific instructions for some common application servers:</p>
<ul>
<li><a href="tomcat.html">Apache Tomcat v4.0</a></li>
@@ -104,17 +143,20 @@
<li><a href="resin211.html">Resin 2.1.1</a></li>
</ul>
-<p>Didn't find yours listed? See whether the instructions for
-Tomcat (for example) gives you enough hints on how to do it. If
-not, first check the FAQs
-(<a href="http://xml.apache.org/soap/faq"; target="_top">
+<p>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
+<a href="http://xml.apache.org/soap/faq"; target="_top">
http://xml.apache.org/soap/faq</a> or
<a href="http://xml.apache.org/soap/faq/faq_chawke.html#Q3_1"; target="_top">
-http://xml.apache.org/soap/faq/faq_chawke.html#Q3_1</a>)
-and if that fails try asking on the Apache-SOAP user's list; more
+http://xml.apache.org/soap/faq/faq_chawke.html#Q3_1</a>.
+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: <a href="http://xml.apache.org/soap/mail.html";
-target="_top">http://xml.apache.org/soap/mail.html</a>.</p>
+target="_top">http://xml.apache.org/soap/mail.html</a>. 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.</p>
<h3><a name="test-install">Testing Your Server-Side Installation</a></h3>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
