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

Java Virtual Machine A Java 1.2 or later compatible virtual machine must be present for both command line and servlet type usage of Apache 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.2 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.

If you don't have a servlet engine installed, well, stop right here and go to the Apache Tomcat project http://jakarta.apache.org/tomcat/ then come back when you are done.

You have three choices for getting Cocoon: you can either download a stable release, or you can download development snapshot, or you can get the latest development version directly from the cvs repository.

You can simply download the latest official release from the Cocoon distribution directory.

You also can download one of the development snapshots from the CVS snapshots directory.

See the Cocoon document Contrib for starting tips.

1. Download WinCVS (v1.2) (homepage is http://www.wincvs.org/);
2. Install it;
3. Start it;
4. Click on admin->preferences;
5. In "Enter the CVSROOT:" enter ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" (without quotes);
6. In "Authentication:" choose ""passwd" file on the cvs server";
7. Click "Ok";
8. Click admin->login;
9. When asked for the password: answer "anoncvs" (without quotes);
10. Click "create->checkout module";
11. Module name and path on the server is "cocoon-2.0" (no quotes);
12. Choose a dir to put the source code in;
13. Go to the "Checkout-options" tab and select "By revision/tag/branch" and enter "HEAD";
14. Click "Ok";
15. If everything goes well, messages will start to appear in the log window;
16. Wait until you see "*****CVS exited normally with code 0*****" in the log window;
17. The Cocoon source is now on your harddrive.

1. Start the shell of your choice.
2. Enter "cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login".
3. When asked for the password: answer "anoncvs".
4. Enter "cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout -r HEAD cocoon-2.0". This will create a directory called "cocoon-2.0" where the Cocoon2 source will be stored.
5. Wait until cvs has finished.
6. The Cocoon source is now on your harddrive.

In case you want to update your Cocoon source tree to the current version, change to the "cocoon-2.0" directory and call "cvs -z3 update -d -P".

Set the JAVA_HOME environment variable to point to the root directory of the Java Development Kit installed on your machine. To do this simply type:

	[unix] JAVA_HOME=/path/to/java/ [win32] SET JAVA_HOME=c:\path\to\java

Your mileage may vary, but you know how to setup environments, right?

Cocoon requires more recent versions of the Xerces and Xalan libraries than those shipped with j2se 1.4. To override bundled libraries, follow these steps:

1. Create %JAVA_HOME%\jre\lib\endorsed directory.
2. Copy xerces-XXX.jar, xalan-XXX.jar, and the xml-apis.jar from the .\lib\core\ to the %JAVA_HOME%\jre\lib\endorsed\ directory.

Tomcat overrides the standard java endorsed directory. For tomcat, you'll need to use %TOMCAT_HOME%\common\endorsed for all these changes.

If you use the binary distribution, the above jars are bundled in the war file. You can get them by extracting the war with a zip utility and looking in WEB-INF\lib

Due to changes in JDBC between JDK 1.3 and JDK 1.4, it is not possible to use Cocoon built on JDK 1.2/1.3 with JDK 1.4 when it comes to databases. If you use the binary distribution, be sure to download the one appropriate for your JDK.

Cocoon requires a Java compiler for some components like XSP etc. The default configuration of Cocoon does not use the compiler provided with the JDK but it's own version.

However, if you want to use the JDK compiler, you have to change the configuration of Cocoon and make sure that the correct compiler is in the WEB-INF/lib directory. You can find the compiler in %JAVA_HOME%/lib/javac.jar.

If you use the source distribution of Cocoon, the build system takes care of this and copies the jar file to the appropriate directory. If you use the binary distribution or want to switch between different JDKs you have to copy %JAVA_HOME%/lib/javac.jar to WEB-INF/lib/javac.jar replacing the existing version.

Cocoon is bundled with the Batik (SVG rasterization toolkit) to deliver SVG imaging capabilities. Batik uses Java java.awt library, which (at least in Sun JDK before 1.4) requires graphics display. This means that X server must be running and Cocoon should have permission to connect to it.

Easiest way to avoid X server connection problem (and to have mentioned permission) is to install and run Cocoon and entire servlet engine of your choice under regular user account.

For security, and many other reasons, X server can be replaced by Xfvb or PJA (alternative awt implementation).

Sun JDK 1.4 does not require graphics display anymore, but Java has to be started with the argument -Djava.awt.headless=true, and X libraries still must be installed.

If you are using unix with the Sun JDK 1.4, it can run in the headless environment (but you still must have X libraries installed!) when following option is provided on Java startup:

	-Djava.awt.headless=true

If you use Tomcat, this can be done by setting environment variable CATALINA_OPTS (Tomcat 4.x), or TOMCAT_OPTS (Tomcat 3.x):

	export CATALINA_OPTS='-Djava.awt.headless=true'

If you are using unix with the Sun JDK 1.3.1 or earlier, it's awt implementation requires you to use X even if you aren't actually displaying anything. One simple solution is to use a different implementation of the awt.

1. From www.eteks.com you can get an awt replacement that doesn't need X: http://www.eteks.com/pja/en/.
2. Then add the following options to the Java command starting your container:

	-Xbootclasspath/a:/path/to/pja.jar -Dawt.toolkit=com.eteks.awt.PJAToolkit -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment -Djava.awt.fonts=/usr/local/jdk/jre/lib/fonts/

If you use Tomcat, this can be done by setting environment variable CATALINA_OPTS (Tomcat 4.x), or TOMCAT_OPTS (Tomcat 3.x):

	export CATALINA_OPTS='-Xbootclasspath/a:/path/to/pja.jar \ -Dawt.toolkit=com.eteks.awt.PJAToolkit \ -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment \ -Djava.awt.fonts=/usr/local/jdk/jre/lib/fonts/'

If you downloaded the binary distribution of Cocoon, you can skip this chapter and proceed to the "Installing Cocoon".

Some of the components delivered with Cocoon require additional libraries, e.g. the Php generator or the FOP serializer (for more information about these components, refer to their documentation).

Most of these libraries are already included in the distribution, but some have to be downloaded manually. The build task checks whether you have the required libraries or not and includes the optional components only if you have the libraries available when you build Cocoon. Refer to the Cocoon JARs page for a list of libraries and locations where you could get them.

A library/package is available to the build process when it is located in the ./lib/optional or the ./lib/local directory.

The following table contains a list of the optional components, their needed libraries and if they are already included or not.

If you want to add additional libraries, put them in the ./lib/local directory as this directory is not touched by CVS. Note: If you added a library/package, you need to rebuild Cocoon as described in 'Create the Cocoon WAR package'.

If you want to build a minimal Cocoon, simply remove all optional libraries from the ./lib/local and the ./lib/optional directory. Make a build clean and then a build with the target you want. However, if you want to build a web application make sure you leave the servlet.jar in the ./lib/optional directory.

Note:This feature is only available in the latest developer version of Cocoon which you can find in the CVS.

Cocoon uses Jakarta Ant for the build and installation, and comes with a build script ([unix]./build.sh, [win32] .\build.bat) that automates the process.

If you want to use build.xml directly with your copy of Ant, please run the build script at least once after every CVS checkout, to ensure that extra initializations like jar copying are done correctly.

The UNIX build script (build.sh) overrides the existing ANT_HOME variable.

There are basically two options that can be set as parameters to the script: targets and properties.

Targets are the execution units available in Ant build files.

Only one target can be specified per run, by appending it to the script invocation:

	[unix] ./build.sh target [win32] .\build.bat target

A target can use properties, that can, or must in some cases, be specified. Multiple properties can be set, by appending them like this to the script invocation:

	[unix] ./build.sh -Dpropertyname=propertyvalue [target] [win32] .\build.bat -Dpropertyname=propertyvalue [target]

The build.xml file comes with some basic important targets. If no target is specified, the default one is used (defined in build.xml).

Some targets are preliminary and their call method will change in the future. Preliminary targets are marked as [BETA].

Cocoon targets place work files and results in a build directory under the cocoon root. The only exception are the distribution targets that build in a directory called dist.

The target you will most use is propably the webapp target which builds a Cocoon web application. For more information see below.

Creates the Cocoon webapp in ./build/cocoon/webapp directory usable as servlet context for quicker turn around.

• target: webapp
• required properties: include.webapp.libs
• buildfile: build.xml

To do this you simply have to type:

	[unix] ./build.sh -Dinclude.webapp.libs=yes webapp [win32] .\build.bat -Dinclude.webapp.libs=yes webapp

If you want a "clean" web application, you can specify these optional properties:

• exclude.webapp.samples : to exclude the samples
• exclude.webapp.documentation : to exclude the documentation
• exclude.webapp.javadocs : to exclude the java docs

So, if you first remove all libraries from the ./lib/local and the ./lib/optional directory except the servlet.jar and then type:

	[unix] ./build.sh -Dinclude.webapp.libs=yes -Dexclude.webapp.samples=yes -Dexclude.webapp.documentation=yes -Dexclude.webapp.javadocs=yes webapp [win32] .\build.bat -Dinclude.webapp.libs=yes -Dexclude.webapp.samples=yes -Dexclude.webapp.documentation=yes -Dexclude.webapp.javadocs=yes webapp

you get a minimal Cocoon web application without any samples or documentation. But remember to make a build clean beforehand.

This is currently the default target.

Creates the Cocoon WAR package out of the ./build/cocoon/webapp directory. It's a non-interactive version of installwar.

• target: war
• required properties: include.webapp.libs
• buildfile: build.xml

It packages the complete webapp from the ./build/cocoon/webapp directory into one file called cocoon.war. The configuration and the options are so the same as for build webapp.

Builds and installs Cocoon war package in a specified directory.

• target: installwar
• required properties: asks the user for installation path
• buildfile: build.xml

This is the recommended target for an easy install in Tomcat.

Available in interactive build.

Cleans the build directory. It is recommended to clean Cocoon build directory every time you upgrade Cocoon, or add/remove libraries from the ./lib/optional/ directory, or change JDK version.

• target: clean
• required properties: none
• buildfile: build.xml

Available in interactive build.

Builds all main Cocoon targets to create the cocoon.jar package.

• target: package
• required properties: none
• buildfile: build.xml

Available in interactive build.

Compiles Cocoon source files.

• target: compile
• required properties: none
• buildfile: build.xml

Available in interactive build.

Shows common build targets and asks the user for eventual properties that may be needed.

• target: interactive
• required properties: none - asks if needed
• buildfile: tools/build-i.xml

To do this you simply have to type:

	[unix] ./build.sh -buildfile tools/build-i.xml [win32] .\build.bat -buildfile tools/build-i.xml

This is the recommended target for first-time users.

Builds the Cocoon documentation in html format.

• target: docs
• required properties: none
• buildfile: build.xml

Available in interactive build.

Builds the Cocoon javadocs in html format.

• target: javadocs
• required properties: none
• buildfile: build.xml

Available in interactive build.

Builds the Cocoon documentation in html printer-friendly format.

• target: printer-docs
• required properties: none
• buildfile: build.xml

Available in interactive build.

Runs Cocoon unit tests.

• target: test
• required properties: none
• buildfile: build.xml

Available in interactive build.

Creates source and binary distributions of Cocoon. This target is not intented for the usual Cocoon user; it's primary used by the Cocoon developers to create a new distribution.

• target: dist
• required properties: none
• buildfile: build.xml

The results are in the dist directory.

An interactive build to help alpha-testers in installing cutting-edge code.

• target: scratchpad
• required properties: none
• buildfile: tools/build-s.xml

To do this you simply have to type:

	[unix] ./build.sh -buildfile tools/build-s.xml [win32] .\build.bat -buildfile tools/build-s.xml

WARNING: Scratchpad builds are not guaranteed to work. You have been warned.

Makes it possible to try new build targets that have not yet made it into the core build. These targets are in tools/builds/try.xml.

• target: try
• required properties: try.target
• buildfiles: build.xml, tools/build-t.xml

To test target test-target for example, you simply have to type:

	[unix] ./build.sh try -Dtry.target=test-target [win32] .\build.bat try -Dtry.target=test-target

Targets are in tools/build-i.xml.

In most servlet engines, this is just a matter of copying the war file in a specific directory and the engine will take care of installing it when restarted.

The first time that you start Cocoon, it will take a few seconds, since Cocoon needs to compile parts of itself.

After that, point your browser to http://localhost:8080/cocoon/ which will generate the live Samples and also lead you to the live local Cocoon documentation.

With the 2.1 version, http://localhost:8080/cocoon/ goes directly to the documentation, while http://localhost:8080/cocoon/samples/ is the Samples.

This is a very easy installation.

1. Build the Cocoon webapp as described above.
2. Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps directory.
3. Start Tomcat: Go to the tomcat/bin directory, and run the startup script.
4. Open the Cocoon welcome page: http://localhost:8080/cocoon/
5. Congratulations! You should see the Cocoon welcome page.

Cocoon requires Tomcat version 3.2 or greater. It wouldn't work with Tomcat 3.1.X

Tomcat currently uses a different version of the XML parser than Cocoon. To get Cocoon to work, you need to perform the following steps:

1. Stop Tomcat Go to the tomcat/bin directory, and run the shutdown script.
2. Delete tomcat/lib/jaxp.jar Tomcat's jaxp.jar is 'sealed', and since xerces contains its own implementation of the JAXP standard extension, Java will fail to load xerces and report a 'Package Sealing Violation' if both are in the classpath.
3. Rename tomcat/lib/parser.jar to tomcat/lib/zparser.jar Tomcat's parser.jar contains older versions of some the same XML APIS that Xerces uses, and these will prevent Xerces from functioning properly if they appear before Xerces in the classpath. Since Tomcat's startup scripts automatically load all the jar files in tomcat/lib in name order, changing the name of the file causes it to be loaded last in the classpath.
4. Copy the cocoon/lib/core/xerces-XXX.jar and cocoon/lib/core/xml-apis.jar JAR files to tomcat/lib Cocoon will now be able to see and use the correct XML libraries.
5. Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps
6. Start Tomcat Go to the tomcat/bin directory, and run the startup script.
7. Start using Cocoon Access the URI http://localhost:8080/cocoon/ with your favorite browser and start to enjoy the world of Cocoon.

Tomcat 4 is a really straight-forward installation.

1. Build the Cocoon webapp as described above.
2. Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps directory.
3. Start Tomcat: Go to the tomcat/bin directory, and run the startup script.
4. Open the Cocoon welcome page: http://localhost:8080/cocoon/
5. Congratulations! You should see the Cocoon welcome page.

If you have to use Tomcat 4.0.3, you have to replace its XML parser with the one shipped with Cocoon.

1. Remove tomcat/common/lib/xerces.jar file.
2. Copy following libraries from the cocoon/lib/core directory to the tomcat/common/lib directory:

   • xalan-XXX.jar
   • xercesImpl-XXX.jar
   • xml-apis.jar

3. Copy cocoon/lib/optional/batik-all-XXX.jar to the tomcat/common/lib directory.
4. Edit extra-classpath parameter in the cocoon/src/webapp/WEB-INF/web.xml file:

For UNIX:

	<init-param> <param-name>extra-classpath</param-name> <param-value>/tomcat/common/lib/xalan-XXX.jar: /tomcat/common/lib/xercesImpl-XXX.jar: /tomcat/common/lib/xml-apis.jar: /tomcat/common/lib/batik-all-XXX.jar</param-value> </init-param>

For Windows:

	<init-param> <param-name>extra-classpath</param-name> <param-value>C:\tomcat\common\lib\xalan-XXX.jar; C:\tomcat\common\lib\xercesImpl-XXX.jar; C:\tomcat\common\lib\xml-apis.jar; C:\tomcat\common\lib\batik-all-XXX.jar</param-value> </init-param>

param-value should be in one line! Also, replace /tomcat/ (UNIX), C:\tomcat\ (Windows) with the path to your Tomcat installation home.

1. Clean Cocoon build directory: build clean
2. Build Cocoon webapp: build -Dinclude.webapp.libs=yes webapp
3. Remove xalan-XXX.jar, xercesImpl-XXX.jar, batik-all-XXX.jar, and xml-apis.jar from the cocoon.war archive.
4. Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps directory.
5. Start Tomcat: Go to the tomcat/bin directory, and run the startup script.
6. Open the Cocoon welcome page: http://localhost:8080/cocoon/
7. Congratulations! You should see the Cocoon welcome page.

This combination is also easy to install.

1. Build the Cocoon webapp as described above.
2. Copy cocoon-2.0/build/cocoon/cocoon.war into tomcat/webapps directory.
3. Set environment variable CATALINA_OPTS=-Djava.awt.headless=true
4. Start Tomcat: Go to the tomcat/bin directory, and run the startup script.
5. Open the Cocoon welcome page: http://localhost:8080/cocoon/
6. Congratulations! You should see the Cocoon welcome page.

Make sure that JAVA_HOME enviroment variable points to the JDK1.4.0. If you had JDK1.3.1 or earlier before, build clean before all these steps.

This installs Cocoon using the cocoon.war file. This was successfully installed under Windows 2000 and JDK 1.3.1. Unix users will need to adjust appropriately. If you haven't done so already, build a domain and a server. In this discussion, the name of the domain is 'mydomain', the name of the server is 'myserver', and WebLogic installation directory is c:\bea\wlserver6.0sp2\. These are the BEA defaults.

1. Build the Cocoon webapp as described above.
2. Copy cocoon\build\cocoon\webapp directory into the c:\bea\wlserver6.0sp2\config\mydomain\applications\ directory of your WebLogic server.
3. Copy the xerces-XXX.jar and xml-apis.jar JAR files from the cocoon\lib\core\ to the directory of your choice, say c:\bea\.
4. Add to the config.xml of the WebLogic server following snippet:

	<Application Deployed="true" Name="Cocoon" Path="./config/mydomain/applications"> <WebAppComponent Name="cocoon" Targets="myserver" URI="cocoon"/> </Application>

1. Edit c:\bea\wlserver6.0sp2\config\mydomain\startWebLogic.cmd file, add xerces and xml-apis JAR files to the classpath:

	set CLASSPATH=c:\bea\xerces-XXX.jar;c:\bea\xml-apis.jar set CLASSPATH=%CLASSPATH%;.;.\lib\weblogic_sp.jar set CLASSPATH=%CLASSPATH%;.\lib\weblogic.jar

1. Start WebLogic server using startWebLogic.cmd.
2. Using a browser, you might want to check WebLogic configuration using console: http://localhost:7001/console/.
3. Open the Cocoon welcome page: http://localhost:7001/cocoon/ (Don't forget the final '/' in the link.)
4. Congratulations! You should see the Cocoon welcome page.

Because of some issues with this version of WebLogic, you will see lots of exceptions in the WebLogic's console window.

This installs Cocoon in a "war" configuration. This was successfully installed under Windows NT 4.0 and IIS 4. I don't believe that SE is available for unix.

Please note that JDK 1.3 is required.

1. Install IIS as usual
2. Install ServletExec (default paths will be used throughout), but don't start it.
3. Build Cocoon's war file (include lib's)
4. Copy cocoon.war into C:\Program Files\New Atlanta\ServletExec ISAPI\webapps\default, creating the directory default if required.
5. Start IIS.
6. Open the Cocoon welcome page (http://localhost/cocoon/)
7. Congratulations! (hopefully) you should see the Cocoon welcome page.

This section describes the deployment of the Cocoon sample WAR with the JBoss-2.4.4_Tomcat-4.0.1 package. It assumes that you built Cocoon as described above or downloaded the binary Cocoon distribution. All steps have been tested with a fresh JBoss 2.4.4 installation on Linux and Windows 2000.

The JBoss/Tomcat bundle is available from the JBoss project page

The JBoss/Tomcat package has the following directory structure

	[path]/JBoss-2.4.4_Tomcat-4.0.1/jboss [path]/JBoss-2.4.4_Tomcat-4.0.1/catalina

Subsequently,

• jboss denotes the JBoss-2.4.4_Tomcat-4.0.1/jboss directory
• catalina is short for JBoss-2.4.4_Tomcat-4.0.1/catalina
• and cocoon is the base directory of your Cocoon distribution or CVS checkout.

In order to get Cocoon running you have to install Xerces as default XML parser for JBoss.

• Stop JBoss if it is running.
• Remove the following files from the jboss/lib directory

  • crimson.jar
  • jaxp.jar

• Copy xml-apis.jar from cocoon/lib/core/ to jboss/lib
• Change jboss/bin/run.sh

	[...] # Add the XML parser jar and set the JAXP factory names # Crimson parser JAXP setup(default) # Change it to Xerces for C2 JBOSS_CLASSPATH=$JBOSS_CLASSPATH:../lib/xml-apis.jar # Remove the following two lines JAXP=-Djavax.xml.parsers.DocumentBuilderFactory=\ org.apache.crimson.jaxp.DocumentBuilderFactoryImpl JAXP="$JAXP -Djavax.xml.parsers.SAXParserFactory=\ org.apache.crimson.jaxp.SAXParserFactoryImpl" [...]

Windows users have to change run.bat accordingly.

• Start JBoss with run_with_catalina.sh or run_with_catalina.bat
• Copy cocoon/build/cocoon/cocoon.war to jboss/deploy
• Check the server log to make sure that J2EE application: [...]/cocoon.war is deployed.
• Open the Cocoon welcome page (http://localhost:8080/cocoon/)
• You should see the Cocoon welcome page.

As both JBoss and Cocoon ship with a Hypersonic database installed, these two conflict and you won't be able to use Cocoon database (SQL) samples. Then again, you probably use JBoss for EJB persistence anyway, so this shouldn't bother you too much ;-)

This section describes the deployment of the Cocoon sample WAR with the JBoss 2.2.2/Tomcat-3.2.2 package. It assumes that you built Cocoon as described above. All steps have been tested with a fresh JBoss 2.2.2 installation on Linux and Windows ME(sic).

The JBoss/Tomcat bundle is available from the JBoss project page

The JBoss/Tomcat package has the following directory structure

	[path]/JBoss-2.2.2_Tomcat-3.2.2/jboss [path]/JBoss-2.2.2_Tomcat-3.2.2/tomcat

Subsequently,

• jboss denotes the JBoss-2.2.2_Tomcat-3.2.2/jboss directory
• Tomcat is short for JBoss-2.2.2_Tomcat-3.2.2/tomcat
• and cocoon is the base directory of your Cocoon distribution or CVS checkout.

In order to get Cocoon running you have to install Xerces as default XML parser for JBoss.

• Stop the server if it is running.
• Remove the following files from the jboss/lib directory

  • crimson.jar
  • jaxp.jar
  • xml.jar

• Remove the following files from the tomcat/lib directory

  • jaxp.jar
  • parser.jar

• Copy xerces-XXX.jar from cocoon/lib/core/ to jboss/lib
• Change jboss/bin/run.sh

	[...] # Add the XML parser jars and set the JAXP factory names # Crimson parser JAXP setup(default) # Change it to Xerces for C2 JBOSS_CLASSPATH=$JBOSS_CLASSPATH:../lib/xerces-XXX.jar # Remove the following two lines JAXP=-Djavax.xml.parsers.DocumentBuilderFactory=\ org.apache.crimson.jaxp.DocumentBuilderFactoryImpl JAXP="$JAXP -Djavax.xml.parsers.SAXParserFactory=\ org.apache.crimson.jaxp.SAXParserFactoryImpl" [...]

Windows users have to change run.bat accordingly.

• Start JBoss with run_with_tomcat.sh or run_with_tomcat.bat
• Copy cocoon/build/cocoon/cocoon.war to jboss/deploy
• Check the server log to make sure that J2EE application: [...]/cocoon.war is deployed.
• Open the Cocoon welcome page (http://localhost:8080/cocoon/)
• Congratulations! (hopefully) you should see the Cocoon welcome page.

As both JBoss and Cocoon ship with a Hypersonic database installed, these two conflict and you won't be able to use Cocoon database (SQL) samples. Then again, you probably use JBoss for EJB persistence anyway, so this shouldn't bother you too much ;-)

This section describes the deployment of the Cocoon sample WAR with Resin 2.x. It assumes that you built Cocoon as described above. All steps have been tested with a fresh Resin 2.0.0, 2.0.4, and 2.1.3 installations (the package is available from Resin's download page)

After unpacking the Resin package you get the following directory structure

	[path]... [path]/resin-2.x/conf [path]/resin-2.x/lib [path]/resin-2.x/webapps [path]...

To get Cocoon running do the following:

• Stop the server if it is running.
• For 2.0.3 version and older: If yours Resin is older then 2.0.4, you have to install Xerces as default XML parser for Resin

  • Remove the following files from the resin-2.0.x/lib directory:

    • jaxp.jar
    • dom.jar
    • sax.jar

  • Copy xerces-XXX.jar and xml-apis.jar JAR file from cocoon-2.0/lib/core/ to the resin-2.0.x/lib/ directory.

• For 2.0.4 version and newer: Edit resin-2.x/conf/resin.conf, change value of the servlet-classloader-hack element to true
• Copy the cocoon-2.0/build/cocoon/cocoon.war WAR file to resin-2.x/webapps directory
• Start Resin as usual
• Open the Cocoon welcome page (http://localhost:8080/cocoon/)
• Congratulations! (hopefully) you should see the Cocoon welcome page.

If you want to place Cocoon webapp in a directory different than resin-2.x/webapps, you need to edit resin-2.x/conf/resin.conf file and add a line somewhere in <host> tag: <web-app id='/cocoon' app-dir='/path/to/webapp/cocoon.war'/>

HP-AS is J2EE application server available from the Hewlett-Packard website. Download and install HP-AS 8.X

Cocoon cannot be deployed as a .war file in HP-AS. Use the following steps to deploy cocoon.war:

1. Extract the cocoon.war file to some directory, using WinZIP or a similar utility to extract the files.
2. To run HP-AS, go to( Start | Programs | HP Middleware | HP Application Server | System Console).
   The HP-AS Console appears with a Log browser. As the HP-AS kernel starts and initializes, messages will appear in the status bar of the console. Wait for the message 'Kernel started' to appear in the Log browser. The following message should display:
   
   [10/16/01 16:03:50][localhost_][S]:Kernel "kernel" started.
   
   
3. To verify that an instance of HP-AS is running, open a web browser and go to http://localhost:9090/helloservlet/hello
   An HTML page should appear containing the following message:
   
   Congratulations!
Congratulations from the HelloWorldServlet
It appears you have the server running
My servlet path is /hello

This test is valid only if you've performed a full install of HP-AS
   
   
4. In the HP-AS console, select View | Deployment Window. In the Available Files pane on the right, browse to the the directory you extracted the cocoon.war file to.
   Expand this directory, and then drag and drop the cocoon sub-directory node to the kernel.j2ee-partition icon in the left pane.
5. When prompted, answer Yes to the deployment question.
   This should create an appropriate entry in the HP-AS j2ee partition configuration file.
   In the current version of the console, there is no indication that the operation succeeded. If you see a parser error in the Log browser, ignore it.
6. To test the deployment, open a web browser and go to the following URL:
   
   http://localhost:9090/cocoon/welcome
   
   Congratulations! (hopefully) you should see the Cocoon welcome page. (this request may take some time).
   

This section describes the deployment of the Cocoon sample WAR with JRun 3.1, on its default server. It assumes that you built Cocoon as described above. All steps have been tested under Win2000.

To get Cocoon running do the following:

• Stop the default and admin servers if they are running.
• Remove jaxp.jar and parser.jar files (Crimson XML parser) from the jrun/lib/ext/ directory.
• Install Xerces as default XML parser for JRun by copying xerces-XXX.jar and xml-apis.jar JAR files from the cocoon-2.0/lib/core/ to jrun/lib/ext/ directory.
• Update Rhino shipped with JRun with newer version from the Cocoon by overwriting jrun/lib/rhino.jar JAR file with the cocoon-2.0/lib/optional/rhino-1.5r3.jar file.
• Start JRun admin server.
• Start JRun default server.
• Open JRun admin page: http://localhost:8000/
• Deploy cocoon.war webapp using console. Use same values for application name and URI prefix (e.g., application name "cocoon", URI "/cocoon").
• Open the Cocoon welcome page: http://localhost:8100/cocoon/
• Congratulations! (hopefully) you should see the Cocoon welcome page.

Instead of deploying WAR file using console, same could be done by copying cocoon-2.0/build/cocoon/webapp under jrun/servers/default/ directory and adding following lines to the jrun/servers/default/local.properties:

	cocoon.rootdir=/absolute/path/to/jrun/servers/default/cocoon cocoon.class={webapp.service-class} webapp.mapping./cocoon=cocoon

iPlanet Web Server 4.x provides the servlet 2.2 API (javax.servlet.* classes), but the servlet engine doesn't handle servlet contexts. This means there is no classloader built with the contents of WEB-INF/classes and WEB-INF/lib and that resolution of context resources (using ServletContext.getResource()) doesn't give the expected results.

To be able to run on such non-compliant engines, Cocoon provides a bootstrap servlet in org.apache.cocoon.BootstrapServletthat handles all the servlet context related behaviours needed for proper functioning.

To use this bootstrap servlet, configure your servlet engine as follows (how to do it depends on the actual engine - see below for iPlanet) :

• add cocoon.jar (and only this one) in the engine's classpath,
• declare the org.apache.cocoon.servlet.BootstrapServlet servlet,
• add a "context-directory" parameter, whose value is the absolute path to Cocoon's context (e.g. "/path/webapp/cocoon"),
• add any other cocoon parameters you want to this servlet (see web.xml for a description of available parameters),
• configure a path translation from "/" to the servlet.

For iPlanet Web Server 4.x, this translates to :

• connect to the administration server of your web server,
• in the "Servlet" tabs, select "Configure servlet attributes", and enter the following :

  • Servlet Name : cocoon
  • Servlet Code (class name) : org.apache.cocoon.servlet.BootstrapServlet
  • Servlet Classpath : /path/webapp/cocoon/WEB-INF/lib/cocoon.jar
  • Servlet Args : context-directory=/path/webapp/cocoon (and any other Cocoon parameters you want)

• select "Configure Servlet Virtual Path Translation" and enter the following :

  • Virtual Path : @/.*
  • Servlet Name : cocoon

• save and apply your changes, and enjoy the latest Cocoon on an old-fashioned servlet engine !

This section describes the deployment of the Cocoon sample WAR with WebSphere 4.0, on its default server. It assumes that you built Cocoon as described above. All steps have been tested under Win2000 and WebSphere AEs 4.0.1 a0136.02.

To get Cocoon running do the following:

• Start the server using startServer startup script.
• Open admin page: http://localhost:9090/admin/
• Deploy cocoon.war webapp using console.
• Save server configuration file.
• Restart the server using stopServer and startServer scripts.
• Open the Cocoon welcome page: http://localhost:9080/cocoon/
• Congratulations! (hopefully) you should see the Cocoon welcome page.

WebSphere power users might deploy Cocoon by exploding cocoon.war into installedApps directory and editing config/server-cfg.xml file.