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]>