http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Index
License
Install

Technologies
Infrastructure
User Guide
Dynamic Content

XSP Processor
DCP Processor
SQL Processor
LDAP Processor

XSP WD

Javadocs

Cocoon 2
Javadoc XML

FAQ
Changes
Todo

Mail Archive
Bug Database


System Requirements

Cocoon requires the following systems to be already installed in your system:

  • Java Virtual Machine A Java 1.1 or greater compatible virtual machine must be present for both command line and servlet type usage of Cocoon. Note that all servlet engines require a JVM to run so if you are already using servlets you already have one installed.
  • Servlet Engine A Servlet 2.x compliant servlet engine must be present in order to support servlet operation and dynamic request handling. Note that this requirement is optional for command line operation.

Required Components

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 for lack of synch between the projects and the complexity of the operation. For this reason, Cocoon now ships with all the required 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 /lib directory you'll find all the required packages. Now jump to the installation instructions for your servlet engine.

Note 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.


Installing Cocoon

Being Cocoon a 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.

Installing Cocoon on Apache JServ

First thing to do is to make sure that Cocoon and all the needed components (as explained in the previous section) are visible. This implies adding this 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/lib/cocoon.jar
wrapper.classpath=/usr/local/java/lib/xerces.jar
wrapper.classpath=/usr/local/java/lib/xalan.jar
wrapper.classpath=/usr/local/java/lib/fop.jar
...

Note from this version of Cocoon the cocoon.jar package should be added to the servlet engine classpath as any other required package (as shown above).

At this point, you must set the Cocoon configurations. 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

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 the file that contains breaf 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).

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, place the samples contained in the distribution (under ./samples) in your web server URI space and call index.xml to see Cocoon in action.

Note For any problem, please go to the FAQ list before submitting a bug report or a request for help on the mail lists. Thank you.


Installing Cocoon on Apache Tomcat

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 Class.forName().newInstance(). The second classpath is associated with a specific context, and is somewhat analagous to the servlet zones used in Apache JServ (see section above).

Because the Cocoon framework utilizes Class.forName() 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 <Tomcat-Root>/lib 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.

On Windows, this is <Tomcat-Root>/tomcat.bat and on Unix, this is <Tomcat-Root>/tomcat.sh. In this file you must add all the component jar files to Tomcat's classpath.

Note from this version of Cocoon the cocoon.jar package should be added to the servlet engine classpath as any other required package (as shown above).

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 web.xml file in your context's WEB-INF directory (look in src/WEB-INF/ to find a template web.xml). This file specifies servlet mappings and initial arguments to servlets and looks like this:

<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>

Make sure you replaced the path to the Cocoon.properties file with the actual location of that file on your system. 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.

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 both Apache and Tomcat and try accessing the samples contained in the distribution to see Cocoon in action or the /Cocoon.xml page for Cocoon internal status.

Note Tomcat 3.0 has a bug that prevents Cocoon operation. In order to make Cocoon work under Tomcat you need to download a newer version or, if none is yet avaiable, build it from the latest source code found in the jakarta-tomcat CVS module under jakarta.apache.org. We apologize for this, but it's not something we can control or work around.


Installing Cocoon on BEA WebLogic

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.


Installing Cocoon on other platforms

Yet to be written! Volunteers welcome!



Working Systems

Cocoon has been reported to be working on these systems:

Operating System  Web Server  Servlet Engine  JVM 
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 
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 
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 
SunOS Netria 5.6  Apache 1.3.9  Apache JServ 1.1b3  Sun JDK 1.1.7 
FreeBSD 3.4  Apache 1.3.9  Apache JServ 1.0  Blackdown JDK 1.1.8 
SCO OpenServer 5  WebLogic 4.5.1  SCO JDK 1.1.7A 
MacOS 8.5+  Resin 1.1b  MRJ 2.2 
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 
SuSE 6.3 Linux  Apache 1.3.9  Apache JServ 1.1  Sun JDK 1.2.2 

Note Due to a bug in Blackdown JDK 1.2pre2 for Linux, we suggest you to use green threads instead of the native ones which are much less stable, expecially highly concurrent operations like servlet engines and servlet execution.

Please, submit your feedback on the cocoon user mail 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.