Cocoon Documentation
Cocoon requires the following systems to be already installed in your system:
Cocoon is a publishing framework and was designed to be highly modular to allow users to choose their preferred implementation for the required component and to allow better and faster parallel development.
Previous releases of Cocoon forced you to download all the basic required packages for the installation, but this generated lots of problems due to lack of synch between the projects and the complexity of the operation. For this reason, Cocoon now ships with all the required packages, (but not the optional packages), a sort of a simple distribution to make things easier for you. We apologize for the increased size of the distribution, but we think this will be worthwhile even for users with low bandwidth.
In the /bin
directory you'll find the cocoon.jar
jar package that contains the Cocoon binary files, while the /lib
directory contains all the libraries required for Cocoon operation.
While these packages may not be the most up-to-date versions, they are
guaranteed and tested to work properly with Cocoon so, we suggest that you
use them. Note, however, that they were all redistributed untouched from
their original distributions.
If you use Java 1.2 or greater, you also have to treat the file
[jdk_home]/lib/tools.jar
as another Cocoon component and include
this into your classpath. This package contains the java compiler that
is required for Cocoon page compilation.
The Ant and Stylebook packages are only used in the build system and are not used by Cocoon at run-time. So you can safely ignore them in the installation.
As Cocoon is a servlet (albeit a large servlet!), you should be able to install it on every compliant servlet engine by associating the "org.apache.cocoon.Cocoon" servlet with the requests you want it to handle. In order to do this, there is no standard way, so we try to provide detailed information for the most used servlet systems.
If you have any problems, please look at the FAQ before submitting a bug report or a request for help on the mailing lists. Thank you.
The first thing to do is to make sure that Cocoon and all the needed
components
(as explained in the previous section) are visible to the JVM. This
means adding
the following to the servlet engine classpath by adding a bunch of
classpath lines
to your jserv.properties
file for each jar package.
wrapper.classpath=[path-to-jar]/[jar-name].jar
Here is an example:
wrapper.classpath=/usr/local/java/jdk/lib/tools.jar wrapper.classpath=/usr/local/java/cocoon/bin/cocoon.jar wrapper.classpath=/usr/local/java/cocoon/lib/xerces.jar wrapper.classpath=/usr/local/java/cocoon/lib/xalan.jar wrapper.classpath=/usr/local/java/cocoon/lib/fop.jar ...
The ./bin/cocoon.jar
package must be added to the
servlet engine classpath in order for the XSP subsystem to work correctly.
We understand that this could be a flexibility limitation.
On JServ it is not yet possible to run
multiple instances of Cocoon in the same virtual machine - if you
would like to do that, try using a different servlet engine.
JServ is a Servlet 2.0 compliant servlet engine and will not work if you place the Servlet_2.2.jar in its classpath. So ignore the servlet_2.2.jar package that is shipped with Cocoon if you use Jserv.
At this point, you must set the Cocoon configuration. To do this, you
must choose the servlet zone(s) where you want Cocoon to reside.
If you don't know what a servlet zone is, open the
zone.properties
file.
To configure Cocoon, you must pass the cocoon.properties
file location to the servlet by adding the following line to the servlet zone:
servlet.org.apache.cocoon.Cocoon.initArgs=properties=[path-to-cocoon]/bin/cocoon.properties
where [path-to-cocoon] is an absolute path.
Note that you should not need to change anything from the template
properties file found in the distribution (under /conf/
),
but you must edit it for more complex operation. Please refer directly to
that file, which contains brief indications and comments on the
different configurations (but you don't need to care about that at
this point).
Now your cocoon servlet is properly configured, but you should tell Apache
to direct any call to an XML file (or any other file you want Cocoon to
process) to the Cocoon servlet. To do this, you should add the following
line to your jserv.conf
file:
Action cocoon /servlet/org.apache.cocoon.Cocoon AddHandler cocoon xml
where xml is the file extention you want Cocoon to handle and /servlet/ is the mount point of your servlet zone (and the above is the standard name for servlet mapping for Apache JServ).
If you haven't already got the Actions module compiled in to Apache
(note - this is compiled in by default in standard installs),
you will need to have the following line uncommented in your
httpd.conf
or Apache will not be able to start:
LoadModule action_module /path/to/mod_actions.so
Restart both Apache and Apache JServ and try accessing the Cocoon status page:
http://localhost/Cocoon.xml
Cocoon will show you how it's configured.
If the page above is working, make the samples contained in the distribution
(under ./samples
) visible from your web server (by either
copying the files under yout htdocs
directory, or by making
at alias for the sample directory) and call ./samples/index.xml
to see Cocoon in action.
If you have any problems, please look at the FAQ before submitting a bug report or a request for help on the mailing lists. Thank you.
To make Cocoon work with Tomcat, you must add a context to Tomcat that describes to Tomcat how to load Cocoon files. 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.
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
$COCOON_HOME/lib
to $TOMCAT_HOME/lib
that are necessary for Cocoon to run.
In addition, you must copy $COCOON_HOME/bin/cocoon.jar
to $TOMCAT_HOME/lib
.
In recent versions of Tomcat under Unix, Tomcat will automatically
detect any .jar
files
in the $TOMCAT_HOME/lib
directory. But under Windows, you must explicitly add the new
.jar
files in the appropriate place in the file $TOMCAT_ROOT/bin/tomcat.bat
.
Next you must tell Tomcat about the new context which will run Cocoon requests. To do
this edit the file $TOMCAT_HOME/conf/server.xml
and add the following line:
<Context path="/cocoon" docBase="webapps/cocoon" debug="0" reloadable="true" > </Context>
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.
Next, if using Apache with Tomcat (which is recommended on a production server, since Tomcat standalone
is not yet as efficient or robust - Apache is far more mature!)
we need to tell Apache to forward the same partial pathnames to Tomcat. This is done
by editing the tomcat .conf
file (it's called tomcat-apache.conf
if you're using Tomcat 3.1 and
Apache 1.3.12) in your Apache setup. Add the following lines:
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>
This tells Apache to direct requests that come in under that partial path "/cocoon" to
the directory under Tomcat ($TOMCAT_HOME/webapps/cocoon
).
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 (.xml
files).
First make a directory and its subdirectory:
mkdir $TOMCAT_HOME/webapps/cocoon mkdir $TOMCAT_HOME/webapps/cocoon/WEB-INF
Next copy the template files from the Cocoon distribution:
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
Next you need to edit the $TOMCAT_HOME/webapps/WEB-INF/web.xml
file to point to the
Cocoon properties file in the same directory. Do this by changing the text
conf/cocoon.properties
to WEB-INF/cocoon-properties
. 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.
Next you need to populate the cocoon context with source .xml
files. For testing purposes
you can just use the samples that come along with Cocoon.
cp -R $COCOON_HOME/samples $TOMCAT_HOME/webapps/cocoon/servlets
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
Make sure that xerces.jar
is located before
xml.jar
otherwise XSP won't work. To do this, rename
xml.jar
as zxml.jar
to be placed later in
alphabetical order.
If you have any problems, please look at the FAQ before submitting a bug report or a request for help on the mailing lists. Thank you.
After you have obtained all the jar packages you need
(see the above section), you should add
them to your Classpath.pref
file.
Then, add this to the servlets.properties
file:
servlet.Cocoon.code=org.apache.cocoon.Cocoon servlet.Cocoon.initArgs=properties=/web/var/tmp/cocoon/cocoon.properties
and this to the rules.properties
file:
*.xml=Cocoon
to provide the initArgs and extension association for Cocoon. Once the web server is restarted to pick up the new configuration, everything should work ok - try accessing the samples contained in the distribution to see Cocoon in action or the /Cocoon.xml page for Cocoon internal status.
You could also make these three configuration changes via the servlet/admin GUI interface if you're not into editing files.
After you have obtained all the jar packages you need (see the above
section), you should add all of them (included the cocoon.jar
package to your weblogic.class.path
variable either
using the t3config utility or use the -Dweblogic.class.path
argument with the java runtime that invokes the system.
Once you've done that, you should register Cocoon by adding these lines to your configuration files:
weblogic.httpd.register.*.xml=\org.apache.cocoon.Cocoon weblogic.httpd.initArgs.*.xml=\properties=[path-to-cocoon]/bin/cocoon.properties
making sure that you replaced [path-to-cocoon] with the actual path in your system.
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.
Everything should be configured fine. Restart Weblogic
and try accessing the samples contained in the distribution to see
Cocoon in action or the /Cocoon.xml
page for Cocoon internal
status.
WLS 5.1 implements Servlet 2.2. so it plugs in easily. Here's a quick recipe:
weblogic.httpd.webApp.cocoon=cocoonwar
Start WLS, point your browser at http://localhost:7001/cocoon/samples/index.xml and away you go.
To support hot deployment of EJB's and Servlets, WebLogic Server uses its own class loader with its own classpath (the "WebLogic classpath"). Normally you'd put all the WebLogic Server container code, JDBC drivers, etc. in your Java CLASSPATH (so that WebLogic Server can start up) and add all your application code (stuff that needs to be able to be redeployable) to the WebLogic classpath.
Cocoon is effectively "container" code, and the XSP processor uses dynamic classloading which only understands the Java CLASSPATH, so you should put all of the Cocoon jars in CLASSPATH.
The big problem with this is that you can't use any code that loads from the WebLogic classpath within XSP's. This includes all of the WebLogic API, so is a PITA. To overcome this, either the way Cocoon loads classes needs to be modified, or the WebLogic Server class loader needs to be disabled (in which case you have to be willing to live without hot redeployment).
To disable the WebLogic class loader, put your application classes, the Cocoon jars and all of the WebLogic Server stuff into the Java CLASSPATH, and add
-Dweblogic.system.disableWeblogicClassPath=true
to the Java command at the end of you WebLogic start script.
The above will also work for installing Cocoon in the BEA WebLogic Enterprise 5.1 J-Engine.
To configure JRun, you must set up both JRun and the web server of your choice to work with Cocoon. We assume that you already have a generic JRun installation that works with your web server.
For the JRun portion, you must add all Cocoon jars to the java.classpath in [jrun-home]/jsm-default/properties with something like:
java.classpath=[previous jrun jars]:[cocoon-home]/lib/xerces.jar: [cocoon-home]/lib/stylebook.jar:[cocoon-home]/lib/fop.jar: [cocoon-home]/bin/cocoon.jar:[cocoon-home]/lib/xalan.jar: [cocoon-home]/lib/turbine-pool.jar
Note that all newlines are added for readability and should not actually be in the configuration file. All jars should be listed upon the same line.
Now, modify [jrun-home]/jsm-default/services/jse/properties/rules.properties and add the line:
*.xml=org.apache.cocoon.Cocoon
In [jrun-home]/jsm-default/services/jse/properties/servlets.properties, add the lines:
servlets.properties:servlet.org.apache.cocoon.Cocoon.code=org.apache.cocoon.Cocoon servlets.properties:servlet.org.apache.cocoon.Cocoon.args=properties=[cocoon-home]/conf/cocoon.properties servlets.properties:servlet.org.apache.cocoon.Cocoon.preload=false
And finally, change the defaultdocs line in [jrun-home]/jsm-default/services/jse/properties/files.properties and add "index.xml" so that the line looks something like:
defaultdocs=index.html,index.jsp,index.xml
Since JRun is web server independent, you must configure JRun and Cocoon to work with your webserver. Again, we assume that you already have JRun installed and working for your particular webserver. We give additional instructions only for making Cocoon work.
Add the following to [apache path]/conf/httpd.conf
Action cocoon /servlet/org.apache.cocoon.Cocoon AddHandler cocoon xml Alias /cocoon/ "[cocoon-home]"
The "Alias" line above is optional; but it will make testing the setup much easier. To verify that all is working, make sure to test out the XSP demos. If you get a java.lang.NoSuchMethodError: org.w3c.dom.Node error, try moving the xerces.jar to the front of JRun's java.classpath, restart JRun, and try the XSP again.
Add your sucessful installation method here. Volunteers welcome!
This has been tested on v4.1 under NT 4.
Edit your servlets.properties
file in the config folder
of your server (something like C:\Netscape\Server4\https-something.somewhere.com\config
),
add the following lines:
servlet.cocoon.code=org.apache.cocoon.Cocoon servlet.cocoon.initArgs=properties=<yourpath to cocoon>/cocoon/conf/cocoon.properties
In the jvm12.conf
, add all the needed ".jar" to the jvm.classpath
line
and uncomment it. This would make the following line, for example, if you
installed Netscape on D: drive. (Note: This should be all on one line, but
for legibility it is split accross lines.)
jvm.classpath=d:/Netscape/Server4/plugins/samples/servlets/beans.10/SDKBeans10.jar; d:/Netscape/Server4/plugins/samples/servlets/beans/SDKBeans.jar; d:/Netscape/Server4/bin/https/jar/Bugbase.jar; d:/Netscape/Server4/bin/https/jar/Calljsac.jar; D:/Netscape/Server4/docs/cocoon/bin/cocoon.jar; D:/Netscape/Server4/docs/cocoon/lib/fop_0_12_1.jar; D:/Netscape/Server4/docs/cocoon/lib/stylebook-1.0-b2.jar; D:/Netscape/Server4/docs/cocoon/lib/xalan_1_0_1.jar; D:/Netscape/Server4/docs/cocoon/lib/xerces_1_0_3.jar
In the rules.properties file, add the following line (this is made to turn around a regexp bug in iWS):
@.*[.]xml=cocoon
Everything is in the "Servlets" tab of your server setting:
Yet to be written! Volunteers welcome!
Cocoon 1.x has been reported to be working on these systems:
Operating System | Web Server | Servlet Engine | JVM |
---|---|---|---|
Debian Potato or Woody | Apache 1.3.12 | JServ 1.1.2 | IBM JDK 1.1.8 or 1.3 |
RedHat Linux 6.0 | Apache 1.3.9 | Apache JServ 1.0 | IBM JDK 1.1.8 |
RedHat Linux 6.0 | Apache 1.3.9 | Apache JServ 1.1b3 | IBM JDK 1.1.8 |
RedHat Linux 6.0 | Apache 1.3.9 | Apache JServ 1.0 | Blackdown JDK 1.2pre2 |
RedHat Linux 6.1 | Apache 1.3.9 | JRun 2.3.3 | IBM JRE 1.1.8 |
RedHat Linux 6.1 (i686) | Apache 1.3.11 | Apache JServ 1.1 | Sun JDK 1.2.2 |
RedHat Linux 6.1 (i686) | Apache 1.3.11 + mod_ssl 2.5.0 | Apache JServ 1.1 | IBM JDK 1.1.8 |
RedHat Linux 6.1 | Apache 1.3.12-2 | Jserv 1.1.2-2 | JDK 1.2.2_006 |
RedHat Linux 6.2 (i686) | Apache 1.3.12 + mod_ssl 2.6.5 | JRun 2.3.3 | Sun JDK 1.2.2 |
RedHat Linux 6.2 | Apache 1.3.12-2 | Tomcat 3.1 | JDK 1.2.2_006 |
RedHat Linux 6.2 (i686) | Apache 1.3.12 | Resin 1.2.b1 | Sun JDK 1.2.2 |
SuSE 6.3 Linux | Apache 1.3.9 | Apache JServ 1.1 | Sun JDK 1.2.2 |
SuSE 7.0 Linux (2.2.16) | Apache 1.3.12 | Apache JServ 1.1.2, Tomcat 3.1 | IBM JDK 1.3 |
Windows 98 | Apache 1.3.9 | Apache JServ 1.0 | Sun JDK 1.2.2 |
Windows 98 | Apache 1.3.9 | Apache JServ 1.0 | IBM JDK 1.1.7 |
Windows 98 | Apache 1.3.9 | Apache JServ 1.1b3 | Sun JDK 1.2.2 |
Windows 98 | Apache 1.3.9 | Apache JServ 1.1b3 | IBM JDK 1.1.7 |
Windows 98 | MS Personal Web Server | ServletExec 2.2 | Sun JDK 1.2.1 |
Windows NT 4.0 | IIS 4.0 | ServletExec 2.2 | Sun JDK 1.2.1 |
Windows NT 4.0 | IIS 4.0 | JRun 2.3.3 | Sun JDK 1.2.1 |
Windows NT 4.0 | Apache 1.3.9 | JRun 2.3.3 | Sun JDK 1.2.2 |
Windows NT 4.0 | Apache Jakarta Tomcat 3.1 Milestone 1 | Sun JDK 1.2.2 | |
Windows NT 4.0 SP4 | BEA WebLogic Server 5.1 SP3 | Sun JDK 1.2.2 | |
Windows NT 4.0 SP5 | IIS 4.0 | Websphere 3.5 Enterprise | IBM JDK 1.2.2 |
Windows NT 4.0 SP6a | Apache 1.3.11 | Apache JServ 1.1 | Sun JDK 1.2.2 |
Windows 2000 Professional | Apache 1.3.12 | Apache JServ 1.1 | Sun JDK 1.2.2 |
Windows 2000 Professional | Apache 1.3.12 | Tomcat 3.1 | Sun JDK 1.3 |
Windows 2000 Advanced Server | Tomcat 3.1 | JDK 1.3 | |
MacOS 8.5+ | Resin 1.1b | MRJ 2.2 | |
MacOS 8.6 | Tomcat 3.1 | MRJ 2.2.2 | |
MacOS 8.6 | WebSTAR 4.0 | JRun 2.3 | MrJ 2.1.4 |
MacOS 8.6 | WebSTAR 4.0 | ServletExec 2.1 | Mrj 2.1.4 |
MacOS 8.6 | Quid Pro Quo 2.1.3 | ServletExec 2.2 | Mrj 2.1.4 |
Solaris 2.5.1 | Netscape-Enterprise/3.6 SP3 | ServletExec 2.2 | Sun JDK 1.2.1 |
SunOS Netria 5.6 | Apache 1.3.9 | Apache JServ 1.1b3 | Sun JDK 1.1.7 |
Solaris 8 (SPARC) | Apache 1.3.12 | Tomcat 3.1 | Sun JDK 1.3 Beta Refresh |
Solaris 8 (x86) | Resin 1.2.b1 | JDK 1.3 beta | |
FreeBSD 3.4 | Apache 1.3.9 | Apache JServ 1.0 | Blackdown JDK 1.1.8 |
FreeBSD 3.4-STABLE with linux_base-6.1 for linux-emulation | Jetty Java HTTP Server v2.3.3 | Blackdown jdk-1.2.2-RC4-linux-i386-glibc | |
FreeBSD 4.1 (RELEASE) | Apache 1.3.12 | Jserv 1.1.2 | Linux JDK 1.2.2 |
SCO OpenServer 5 | WebLogic 4.5.1 | SCO JDK 1.1.7A | |
OS/2 Warp 4 FP 12 | Gefion Software LiteWebServer | IBM JDK 1.1.8 | |
SGI IRIX 6.5.7 | Apache 1.3.12 | Apache JServ 1.1 | Sun JDK 1.2.1 (SGI) |
Please, submit your feedback on the cocoon users mailing list (nowhere else!) if you were able to install Cocoon on a different combination not listed above. Thanks!
Copyright © 1999-2000 The Apache Software Foundation.
All rights reserved.