cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Meyer <cme...@ultratask.com>
Subject more docs for Cocoon 1.7 + Tomcat 3.1
Date Thu, 11 May 2000 01:18:34 GMT
I went through the difficult process of trying to decipher the 
documentation on how to install Cocoon with Tomcat today. I don't 
know if my explanation is much better than what is there already, but 
I think it is a little more complete and 'to the point'.

I am including a udiff (hopefully the line breaks don't blow it). 
Perhaps someone with a repository write access could review the 
changes and merge it if they like them. Here's the diff:

RCS file: /home/cvspublic/xml-cocoon/xdocs/installing.xml,v
retrieving revision 1.21
diff -u -r1.21 installing.xml
--- installing.xml	2000/08/23 22:52:45	1.21
+++ installing.xml	2000/08/24 01:19:02
@@ -192,128 +192,118 @@
     </note>
    </s2>

-  <s2 title="Installing Cocoon on Apache Tomcat">
+  <s2 title="Installing Cocoon 1.7.4 on Apache Tomcat 3.1">
      <p>
-     Tomcat has two basic methods of locating Java classes for the 
runtime environment.
-     The first is the overall classpath that Tomcat uses to run, and 
this is the
-     classpath provided to Java classes that use constructs such as
-     <code>Class.forName().newInstance()</code>.  The second classpath is
-     associated with a specific context, and is somewhat analagous to the
-     servlet zones used in Apache JServ (see section above).
+     To make Cocoon work with Tomcat, you must add a context to 
Tomcat that describes
+     to Tomcat how to load Cocoon files. Each context is run in a 
separate JVM for
+     Tomcat 3.1. Then you must tell Apache to send certain requests 
to Tomcat (and
+     consequently Cocoon). Finally you must provide the .xml files 
to be served by
+     Cocoon. These steps are outlined below.
      </p>

      <p>
-     Because the Cocoon framework utilizes 
<code>Class.forName()</code> and other
-     dynamic instance handling techniques, the Cocoon classes need to have its
-     classpath aware of the component classes used within the 
framework.  To do
-     this, take all the required components (see above) and put them in your
-     <em>&lt;Tomcat-Root&gt;/lib</em> directory.  This is the 
standard location
-     for Tomcat core libraries. To ensure that Tomcat will use these, you need
-     to edit the Tomcat startup file.
+     A context in Tomcat describes to Tomcat how and when to load a 
particular servlet
+     and Cocoon is one such servlet. First we need to make sure that 
Tomcat knows how to
+     load the Cocoon .jar files. To begin with, you must copy any 
.jar files from
+     <code>$COCOON_HOME/lib</code> to <code>$TOMCAT_HOME/lib</code>

that are necessary for Cocoon to run. For
+     Cocoon 1.7.4 these are <code>fop_0_12_1.jar</code>, 
<code>xalan_1_0_1.jar</code>, <code>xerces_1_0_3.jar</code>.
+     The names and versions are likely to change in future versions. 
In addition, you
+     must copy <code>$COCOON_HOME/bin/cocoon.jar</code> to 
<code>$TOMCAT_HOME/lib</code>.
      </p>
+
+    <p>
+     In recent version of Tomcat under Unix, Tomcat will 
automatically detect any <code>.jar</code> files
+     in the <code>$TOMCAT_HOME/lib</code> directory. But under 
Windows, you must explicitly add the new
+     <code>.jar</code> files in the appropriate place in the file 
<code>$TOMCAT_ROOT/bin/tomcat.bat</code>.
+    </p>
+
+    <p>
+     Next you must tell Tomcat about the new context which will run 
Cocoon requests. To do
+     this edit the file <code>$TOMCAT_HOME/conf/server.xml</code> 
and add the following line:
+    </p>

+<source><![CDATA[
+<Context path="/cocoon" docBase="webapps/cocoon" debug="0" reloadable="true" >
+</Context>
+]]></source>
+
      <p>
-     On Windows, this is <em>&lt;Tomcat-Root&gt;/tomcat.bat</em> and
on
-     Unix, this is <em>&lt;Tomcat-Root&gt;/tomcat.sh</em>.  In this
-     file you must add all the component jar files to Tomcat's classpath.
+     This tells Tomcat that requests that come in under that partial 
path "/cocoon" should
+     be mapped to the context defined in the directory 
"webapps/cocoon". We will set that up
+     shortly.
      </p>
+
+    <p>
+     Next we need to tell Apache to forward the same partial 
pathnames to Tomcat. This is done
+     by editing the tomcat <code>.conf</code> file (it's called 
<code>tomcat-apache.conf</code> if you're using Tomcat 3.1 and
+     Apache 1.3.12) in your Apache setup. Add the following lines:
+    </p>

-    <note>
-     the <code>cocoon.jar</code>
-     package should be added to the servlet engine classpath as any other
-     required package (as shown above).
-    </note>
+<source><![CDATA[
+Alias /cocoon $TOMCAT_HOME/webapps/cocoon
+<Directory "$TOMCAT_HOME/webapps/cocoon">
+    Options Indexes FollowSymLinks
+</Directory>
+ApJServMount /cocoon /cocoon
+<Location /cocoon/WEB-INF/ >
+    AllowOverride None
+    deny from all
+</Location>
+]]></source>

      <p>
-     Next you need to tell your context where Cocoon can find it's properties
-     file, as well as to map Cocoon to XML document requests.
-     Make sure you have a <em>web.xml</em> file in your context's
-     <em>WEB-INF</em> directory (look in <code>src/WEB-INF/</code>
to find a
-     template <em>web.xml</em>).  This file specifies servlet mappings
-     and initial arguments to servlets and looks like this:
+     This tells Apache to direct requests that come in under that 
partial path "/cocoon" to
+     the directory under Tomcat (<code>$TOMCAT_HOME/webapps/cocoon</code>).
      </p>
+
+    <p>
+     Finally, we need to set up the actual context that we have 
defined and pointed requests
+     to above. To do this, we need to create a new directory in 
webapps called cocoon. Then
+     we need to make a sub-directory that describes to Tomcat how to 
map particular files to
+     Cocoon, then we need to fill the sub-directory with our Cocoon 
source files (<code>.xml</code> files).
+    </p>
+
+    <p>
+     First make a directory and its subdirectory:
+    </p>
+
+<source><![CDATA[
+mkdir $TOMCAT_HOME/webapps/cocoon
+mkdir $TOMCAT_HOME/webapps/cocoon/WEB-INF
+]]></source>
+
+    <p>
+     Next copy the template files from the Cocoon distribution:
+    </p>
+
+<source><![CDATA[
+cp $COCOON_HOME/src/WEB-INF/web.xml $TOMCAT_HOME/webapps/cocoon/WEB-INF
+cp $COCOON_HOME/conf/cocoon.properties $TOMCAT_HOME/webapps/cocoon/WEB-INF
+]]></source>

+    <p>
+     Next you need to edit the 
<code>$TOMCAT_HOME/webapps/WEB-INF/web.xml</code> file to point to the
+     Cocoon properties file in the same directory. Do this by 
changing the text
+     <code>conf/cocoon.properties</code> to 
<code>WEB-INF/cocoon-properties</code>. Note that this path is a 
relative
+     path must be so. Don't try to use an absolute path here. It 
won't work. Also note that
+     the web.xml file describes how to map .xml requests to the 
Cocoon servlet.
+    </p>
+
+    <p>
+     Next you need to populate the cocoon context with source 
<code>.xml</code> files. For testing purposes
+     you can just use the samples that come along with Cocoon.
+    </p>
+
  <source><![CDATA[
-<servlet>
- <servlet-name>org.apache.cocoon.Cocoon</servlet-name>
- <servlet-class>org.apache.cocoon.Cocoon</servlet-class>
- <init-param>
-  <param-name>properties</param-name>
-  <param-value>
-    [path-to-cocoon.properties]/cocoon.properties
-  </param-value>
- </init-param>
-</servlet>
-
-<servlet-mapping>
- <servlet-name>org.apache.cocoon.Cocoon</servlet-name>
- <url-pattern>*.xml</url-pattern>
-</servlet-mapping>
+cp -R $COCOON_HOME/samples $TOMCAT_HOME/webapps/cocoon/servlets
  ]]></source>

      <p>
-     Make sure you replaced the path to the Cocoon.properties file with the
-     location of that file on your system,
-     <strong>relative to the context root</strong>. Even if you start the
-     filename with a <code>/</code> it will still be relative to the 
context root.
-    </p>
-
-    <note>
-      Because Cocoon now (since version 1.7.3) uses getResource() in the
-      Servlet API to read cocoon.properties, and has different instances for
-      each servlet context, you need to put a copy of cocoon.properties in all
-      of your servlet contexts that use Cocoon. (It is recommended to put it
-      in the context's WEB-INF directory, or a password-protected directory,
-      to prevent anyone from being able to read it over the web.)
-      However, you <strong>cannot</strong> use symbolic links on Unix to point
-      to a file outside of the current context, because Tomcat does not allow
-      it for security reasons.
-    </note>
-
-    <note>
-      the <code>cocoon.properties</code> file <strong>must</strong>

be referenced
-      with relative paths in <code>WEB-INF/web.xml</code>, otherwise, Cocoon
-      won't be able to locate it's properties and won't be able to start.
-    </note>
-
-    <p>
-     Note that you should not need to change anything from the template
-     properties file found in the distribution, but you must edit it for
-     more complex operation. Please refer directly to the file that contains
-     brief indications and comments on the different configurations, but you
-     don't need to care about that at this point.
-    </p>
-
-   <p>
-    At this point, you should check if your system matches the global
-    considerations about Cocoon properties. Usually, you might want to give
-    the installation a try as it is and then read again that section if
-    something goes wrong. Most installations don't need any changes to
-    be operational.
-   </p>
-
-   <p>
-    If you have upgraded Cocoon from an older version and Cocoon won't
-    initialize, either ensure that
-    you are using the latest cocoon.properties - or, if you are have some
-    non-standard properties in cocoon.properties which you need to keep,
-    refer to the latest cocoon.properties to find out what changes need to
-    be made, if any.
-   </p>
-
-   <p>
-    Everything should now be configured fine. Restart both Apache and Tomcat
-    and try accessing the samples contained in the distribution to see
-    Cocoon in action or the <code>/Cocoon.xml</code> page for Cocoon internal
-    status.
-   </p>
-
-   <note>
-    Make sure that <code>xerces.jar</code> is located <strong>before</strong>
-    <code>xml.jar</code> otherwise Cocoon won't run. To do this, rename
-    <code>xml.jar</code> as <code>zxml.jar</code> to be placed later
in
-    alphabetical order.
-   </note>
+     Finally, you need to stop Tomcat, stop Apache, then restart the 
two in order to make
+     all of the new settings load. You should be able to access pages like
+     http://localhost/cocoon/Cocoon.xml and 
http://localhost/cocoon/servlets/index.xml
+    </p>
+
    </s2>

  <s2 title="Installing Cocoon on New Atlanta's ServletExec 2.2">

Mime
View raw message