Installing Cocoon

System Requirements

The bold packages are the ones distributed with Cocoon due to licensing issues.

Installing Cocoon

Cocoon is a 100% pure Java servlet based on the JavaSoft Servlet API platform, for this reason it should work on any servlet engine that is compliant at least with the 2.0 version of the specification.

First thing to do is to install the servlet in your servlet engine. Since the Servlet API specification does not (yet) define a standard way to install a servlet, you should refer to your servlet engine instructions on how to do this. If your servlet engine supports jar files, we suggest you to install the cocoon.jar file that you find in the /bin/ directory of the distribution. Please, note that you must also make visible all the other jar archives that are needed to the servlet (and found in the /bin/ directory of the distribution).

Once the servlet is installed, you should tell Cocoon where its configuration file resides setting the properties initialization argument for the Cocoon servlet (a template configuration file is found both in the /bin/ directory of the distribution and packaged inside the cocoon.jar file in the directory org/apache/cocoon/). Again, there is no standard way (yet!) on how to do this, but all compliant servlet engine must be able to pass initialization arguments to servlets. So, if you don't find a way to do this, look again or contact your servlet engine provider.

At this point, you should map the ".xml" extension (note that Cocoon may not work correctly if another extension is used) to the org.apache.cocoon.Cocoon servlet. For the last time, you should follow your servlet engine instructions on how to do this.

At this point, any ".xml" file will be processed by Cocoon and the resulting output will be delivered to the client. Please note that XML files should contain a reference to their XSL stylesheet in order to be correctly processed. Otherwise, the XML will be processed but will be delivered without any particular style. This can be used in XSL aware clients. See the user guide for more information on this.

Installing on Apache JServ

NOTE: a bug in Apache JServ 1.1b1 and 1.1b2 prevents Cocoon from operating correctly. The problem is fixed from version 1.1b3 on.

Installation on Apache JServ is simple and straightforward. For out-of-the-box usage, you have to add the all the jar packages found in the /bin/ directory of the distribution in Apache JServ classpath adding the following lines to your jserv.properties file or making them available in the system classpath (if you're running Java2, it's enough if you move them in your extension directory):

wrapper.classpath=<cocoon>/bin/xxx.jar

where <cocoon> is the directory where you installed cocoon and for every package found in that /bin/ directory (all but the cocoon.jar file that could behave incorrectly if put there). Then you should add the Cocoon servlet to your favorite servlet zone, adding the following line to your <zone>.properties file, where <zone> is the name of the servlet zone as you should normally do with Apache JServ:

repositories=<cocoon>/bin/cocoon.jar

At this point, the servlet engine knows where to locate the Cocoon servlet (org.apache.cocoon.Cocoon) but Cocoon must need to know its configurations to be able to start. To configure Cocoon, you must pass the cocoon.properties file location to the servlet by adding the following to the <zone>.properties file:

servlet.org.apache.cocoon.Cocoon.initArgs=properties=<cocoon>/bin/cocoon.properties

Note that you find a template cocoon.properties file in the /bin/ directory or packaged inside the cocoon.jar file. To run the examples found in the /example/ directory of the distribution you should don't need to change anything of this file.

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 Apache conf files where you placed the other mod_jserv directives (usually httpd.conf or mod_jserv.conf) where /servlet/ is the URI mapped to the servlet zone where Cocoon resides.

ApJServAction .xml /servlet/org.apache.cocoon.Cocoon

At this point everything should be configured fine. Browse the /example/index.html file from your web server to see Cocoon in action.

Installing on Allaire JRun 2.3.3

Download JRun 2.3.3 and then get the build 155 patch so you have the latest and greatest version. Install it and run the connector wizard to install a connector for your native web server.

Special notes for Linux users:

Download Cocoon to unjar it in your favorite location.

Copy or move the docs/example/ directories and index.html file to your web server's document root or create an alias for them to be visible from your favorite location.

Edit JRun's properties files to use the Cocoon servlet and its provided jar files. You can do these steps using the GUI Admin.
Application, but I think it's easier to just edit the files "by hand."

Go to http://127.0.0.1/example/index.html and enjoy!

Working Systems

Cocoon has been reported to be working on these systems:

Please, submit your feedback if you were able to install Cocoon on a different combination not listed above.

Copyright (c) 1999 The Java Apache Project.
$Id: installing.html,v 1.9 1999/10/28 13:22:25 stefano Exp $
All rights reserved.