Installing Apache Cocoon
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
Installation
Download
Installing
Jars
Testing
Overview

System Requirements

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.


Getting Apache Cocoon

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

Download a distribution

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


Download a development snapshot

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


Step-by-step cvs instructions for Windows

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 "xml-cocoon2" (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.

Step-by-step cvs instructions for Unix
  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 xml-cocoon2". This will create a directory called "xml-cocoon2" 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 "xml-cocoon2" directory and call "cvs -z3 update -d -P".



Building Cocoon
Set JAVA_HOME environment variable

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?


Adding additional components

Some of the components delivered with Cocoon required 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.

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

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

Component  Required Library  Library Included 
HTML Generator  JTidy  Yes 
Php Generator  Php Servlet  No 
XT Transformer  XT Processor  Yes 
LDAP Transformer  JNDI  No 
PDF Serializer  FOP  Yes 

Note: If you added a library/package, you need to rebuild Cocoon as described in 'Create the Cocoon WAR package'.


Create the Cocoon WAR package

To do this you simply have to type:

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

this will create the "cocoon.war" file in the './build/cocoon' directory.



Installing Cocoon

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.

Installing on Tomcat 3.X

NoteCocoon 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/xerces-XXX.jar and cocoon/lib/xml-apis.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. Note that the first time you access Cocoon, it will take a few seconds to start, since Cocoon needs to compile parts of itself.

Installing on Tomcat 4.X

Tomcat 4 is a really straight-forward installation.

  1. Build the Cocoon webapp Build the webapp as described above.
  2. Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps
  3. Start Tomcat Go to the tomcat/bin directory, and run the startup script.
  4. Start using Cocoon Access the URI http://localhost:8080/cocoon/ with your favorite browser and start to enjoy the world of Cocoon. Note that the first time you access Cocoon, it will take a few seconds to start, since Cocoon needs to compile parts of itself.
Linux/Headless/Batik

If you are using unix with the sun jdk, 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. Unpack the jars into a place where your jdk will be able to use them-- $JAVAHOME/jre/classes works for j2sdk1.3
  3. Then add the following to your Tomcat startup script (using CATALINA_OPTS if it is 4.x, TOMCAT_OPTS if it is 3.x)
export CATALINA_OPTS='-Dawt.toolkit=com.eteks.awt.PJAToolkit \
  -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment \
  -Djava.awt.fonts=/usr/local/jdk/jre/lib/fonts/'
        

(Re)start Tomcat and enjoy!



Installing on BEA Weblogic 6.0

This installs Cocoon using the cocoon.war file. This was successfully installed under Windows 2000. 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' and the name of the server is 'myserver'. These are the BEA default names.

  1. Copy cocoon.war into c:\bea\wlserver6.0sp1\config\mydomain\applications
  2. Create a new directory named ext under c:\bea\jdk130\jre\lib
  3. Copy the xerces-XXX.jar JAR file from xml-cocoon2/lib to c:\bea\jdk130\jre\lib directory
  4. Run weblogic using startWebLogic.cmd file in c:\bea\wlserver6.0sp1\config\mydomain directory
  5. Using a browser, link to your web site's cocoon page:
    http://<your machine name>:<port number>/cocoon/
    (Don't forget the final / in the link.)
  6. Congratulations! (hopefully) you should see the Cocoon welcome page.

NoteIf you have problems with starting up Cocoon, you can modify the CLASSPATH in the .cmd files and ensure that xerces-XXX.jar is picked up before any other jars.
set CLASSPATH=.;c:\bea\jdk130\jre\lib\xerces-XXX.jar;.\lib\weblogic_sp.jar;.\lib\weblogic.jar


Installing on BEA WLS6.1sp1, WLS6.1sp2

This section describes installing Cocoon in a "directory configuration". This was successfully installed under Windows 2000. 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' and the name of the server is 'myserver'. These are the BEA default names; you may want to download WLS6.1.

  1. Compile and build Cocoon. Launch build compile, build -Dinclude.webapp.libs webapp webapp-local.
  2. You should have a webapplication directory in {cocoon-dir}/build/cocoon/webapp.
  3. Modify {cocoon-dir}/build/cocoon/webapp/cocoon.xconf. Replace xslt-processor definition using TRAX XSLT transformer factory by xslt-processor definition using Xalan transformer factory explicitly. Your xslt-processor definition should look like the code snippet below.
  4. Configure your WebLogic server, launch your WebLogic console. Use Configure a new Web Application..., and enter in field "Path URI" full path name of Cocoon webapplication directory, like d:\xml-cocoon2\build\cocoon\webapp, enter in field "Name" the servlet name eg. cocoon. Check the "Deployed" checkbox, and click "Apply". At last be sure that you assign the servlet to a target server.
  5. You might try to avoid the configuration step by copying the whole Cocoon webapp directory into the applications directory of your WLS6.1 server. In this case you might have to restart your WLS6.1 server in order to activate Cococoon servlet in WLS 6.1.
  6. Using a browser, you might want to check WLS6.1 configuration link to your WLS6.1 console http://<your machine name>:<port number>/console.
  7. Using a browser, link to your web site's cocoon page: http://<your machine name>:<port number>/cocoon/ (Don't forget the final / in the link.)
  8. Congratulations! (hopefully) you should see the Cocoon welcome page.

Snippet of modified cocoon.xconf. The effect of this change is that Cocoon will not try to use a TRAX XSLT transformer factory. Using the TRAX XSLT transformer factory under WLS6.1sp1 lead to empty sitemap_xmap.java files, indicating that the XSLT processor used did not work properly. WLS6.1 has a built-in TRAX XSLT which seems not to work properly for Cocoon.

The code snippet below configures the xslt processor to use the XALAN transformer factory explictly. Forcing Cocoon using Xalan XSLT lead to correct sitemap_xmap.java files.

<xslt-processor class="org.apache.cocoon.components.xslt.XSLTProcessorImpl" 
  logger="root.xslt">
  <parameter name="use-store" value="true"/>
  <parameter name="transformer-factory" 
    value="org.apache.xalan.processor.TransformerFactoryImpl"/>
</xslt-processor>

Note The above description does not change any WLS6.1 startup script. Moreover other applications will still use the WLS6.1 shipped XSLT processor. All changes described above are locally to the Cocoon webapplication.


Installing on ServletExec 3.1 (In Process with IIS)

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.

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

Installing on JBoss 2.2.2 with Tomcat 3.2.2

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

NoteThe 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 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"
[...]
     

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

NoteAs 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 ;-)


Installing on Resin 2.0.x

This section describes the deployment of the Cocoon sample WAR with Resin 2.0.x. It assumes that you built Cocoon as described above. All steps have been tested with a fresh Resin 2.0.0, 2.0.1 and 2.0.4 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.0.x/lib
[path]/resin-2.0.x/webapps
[path]...

To get Cocoon running do the following:

  • Stop the server if it is running.
  • If yours Resin is older then 2.0.4, you have to install Xerces as default XML parser for Resin (Skip this step if you are using Resin 2.0.4 or newer)
    • Remove the following files from the resin-2.0.x/lib directory:
      • jaxp.jar
      • dom.jar
      • sax.jar
    • Copy the xerces-XXX.jar JAR file from xml-cocoon2/lib to resin-2.0.x/lib directory
  • Copy the xml-cocoon2/build/cocoon/cocoon.war WAR file to resin-2.0.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.

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


Installing on HP-AS 8.X

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

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


Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.