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

Index
License
Install

Technologies
User Guide
Dynamic Content

XSP Processor
DCP Processor
SQL Processor
LDAP Processor

XSP WD

Javadocs

Cocoon 2
Javadoc XML

FAQ
Changes
Todo


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.

Here is a list of supported components with their minimum version required to operate with this version of Cocoon:

XML Parsers
Name  Version  Location 
Apache Xerces  1.0.1 (java edition)  xml.apache.org 
Sun ProjectX  TR2  java.sun.com 
Cocoon comes preconfigured for Xerces 
XSLT Processor
Name  Minimum Version  Location 
Apache Xalan  0.19.0  xml.apache.org 
James Clark's XT  19991102  www.jclark.com 
Cocoon comes preconfigured for Xalan 
Other Packages
Name  Minimum Version  Location 
Apache FOP  0.12.0  xml.apache.org 
FESI EcmaScript Engine  1.2.1  home.worldcom.ch/jmlugrin/fesi 
GNU Regexp  1.0.8  www.cacas.org/java/gnu/regexp 
JNDI API  1.2.1  java.sun.com 

Note Cocoon is strictly dependent on some printing classes contained into Xerces so, even if you use another parser, you should still keep Xerces visible to Cocoon.

Being an Apache project, Cocoon focuses on Apache technologies but we are dedicated to support all compatible XML/XSL technologies and will welcome contributions to add support for other components not currently supported.

So this is your shopping list for components for complete operation:

  • Apache Xerces (required for the formatting classes org.apache.xml.serialize)
  • Your favorite XML parser
  • Your favorite XSLT processor
  • Apache FOP (optional, unless you want PDF rendering)
  • GNU Regexp (optional, unless you use ProducerFromMap)
  • FESI (optional, unless you use DCP)
  • JNDI (optional, unless you use the LDAP processor)

All right. Now that you have downloaded all the components you need, go on and jump to the installation instructions for your servlet engine.


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.

General considerations

There are some general considerations that apply to all systems.

Since there is no portable way, in a Java platform, to tell how much memory an object is using, the memory cache works in a rather cumbersome manner: you set up a lower limit that the cache must always leave free for the JVM operation. This means, that if the memory limit is 200Kb, Cocoon uses all your JVM heap size to store pages in memory and makes sure that 200Kb are available for other operations.

This does not impact the JVM operation, if enough memory is left for the normal operation. You must be aware of the fact that leaving Cocoon with too little memory for operation does impact peformance since the JVM garbage collector has to do more work to keep up with execution and memory cleanup. Sometimes, you may even end up having OutOfMemoryExceptions if your limit is lower than the memory required for the operation.

A good way to control your memory is to setup your JVM with a fixed heap limit and to give it enough memory to start. This is done by using command line parameters for your java interpreter such as:

  • Startup heap size:
    • java 1.1 - -ms[size]
    • java 1.2 - -Xms[size]
  • Maximum heap size:
    • java 1.1 - -mx[size]
    • java 1.2 - -Xmx[size]

A well balanced system should have something like 8Mb start heap, 2Mb Cocoon memory limit and 64Mb or greater max heap, but these depend heavily on your system load/configuration to be generally meaningful.

To change the cocoon object store memory limit open you should change the following property in the cocoon.properties file.

store.memory = 200000

Another important part of Cocoon is the page compiler used inside the XSP processor which store the generated/compiled pages on file system. The default directory is ./repository which is usually relative to the web server or servlet engine working directory.

If you experience troubles (such as not having reading/writing permissions) or you want to locate this directory somewhere else, you have to change the

processor.xsp.repository = ./repository

property in the cocoon configuration file.

Warning: Since this directory may contain security sensible information, make sure you deny access (even read-only) to untrusted users.


Installing Cocoon on Apache JServ

Apache JServ has one configuration file for the whole engine (normally called jserv.properties) and one for each servlet zone. Please, refer to the Apache JServ documentation for more information on this.

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 line like this in your jserv.properties file for each jar package you have to install (after substituting [path-to-jar] with the path to the jar file and [jar-name] with the package file name).

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
wrapper.classpath=/usr/local/java/lib/regexp.jar
wrapper.classpath=/usr/local/java/lib/jndi.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 (Note that Cocoon can safely reside on different servlet zones with different configuration files). If you don't know what a servlet zone is, you probably want to open the zone.properties file that represents the default servlet zone.

To configure Cocoon, you must pass the cocoon.properties file location to the servlet by adding the following to the zone.properties file (or each servlet zone file you want Cocoon to reside):

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 mod_jserv.conf or jserv.conf file:

Action cocoon /servlet/org.apache.cocoon.Cocoon
AddHandler cocoon xml

where xml is the file extention you want to map to the servlet and /servlet/ is the mount point of your servlet zone (and the above is the standard name for servlet mapping for Apache JServ).

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

Note: you may want Cocoon to handle two different extentions with different configurations. To do this, you must set the two different configurations in two different servlet zones, then associate the extentions like this:

Action cocoon1 /zone1/org.apache.cocoon.Cocoon
Action cocoon1 /zone2/org.apache.cocoon.Cocoon
AddHandler cocoon1 xml1
AddHandler cocoon2 xml2

where xml1 is handled by the Cocoon residing on zone1 and xml2 is handled by the Cocoon residing on zone2 which have different configurations and thus different behavior.


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

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