You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cocoon.apache.org by Chris Meyer <cm...@ultratask.com> on 2000/05/11 03:18:34 UTC
more docs for Cocoon 1.7 + Tomcat 3.1
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><Tomcat-Root>/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><Tomcat-Root>/tomcat.bat</em> and on
- Unix, this is <em><Tomcat-Root>/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">