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 &quot;/&quot; with &quot;\&quot; 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 &quot;/&quot; with &quot;\&quot; 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]>

Reply via email to