Introduction to Cocoon, XML XSL - Installing Cocoon (Page 4 of 9 )
Cocoon is Apache's XML publishing engine. Cocoon will read your xml file and format it according to the layout defined in your XSL files. The Cocoon distribution includes the cocoon.jar file and a set of jar files that help cocoon read and format xml files. Installing Cocoon is not much more complicated than installing Tomcat. You need to copy all of the jar files to a place where Tomcat knows to find them and update Tomcat's configuration.
First unpack Cocoon and change to the Cocoon directory:
$ tar -xzf Cocoon-1.8.2.tar.gz
$ cd cocoon-1.8.2
Next copy all of the jar files in lib/ to $TOMCAT_HOME/lib
$ cp lib/*.jar $TOMCAT_HOME/lib
$ cp bin/cocoon.jar $TOMCAT_HOME/lib
Tomcat 3.2.1 will automatically load all of the jar files found in $TOMCAT_HOME/lib so you do not have to add these to your CLASSPATH. However, if you are using java 1.2 or higher you will also need to add $JAVA_HOME/lib/tools.jar to your CLASSPATH. Cocoon uses tools.jar for page compilation. If you do not want to add tools.jar to your profile add this line to $TOMCAT_HOME/bin/tomcat.sh:
export CLASSPATH=$CLASSPATH:$JAVA_HOME/lib/tools.jar
The next step is to add a Context for Cocoon to Tomcat's server.xml file. This tells Tomcat to create a context for Cocoon. It also tells Tomcat where to find the cocoon files and what url path cocoon should be launched from. Change to $TOMCAT_HOME/conf and use an editor to open server.xml
At the bottom of the file you will see this tag </ContextManager>. Above that tag add these two lines:
<Context path="/cocoon" docBase="webapps/cocoon" debug="0" reloadable="true">
</Context>
This tells Tomcat to create a context for cocoon with the path /cocoon. Whenever /cocoon is called Tomcat will look for the files in $TOMCAT_HOME/webapps/cocoon. Of course at this point there is no webapps/cocoon directory so let's create that next.
$ mkdir $TOMCAT_HOME/webapps/cocoon
$ mkdir $TOMCAT_HOME/webapps/cocoon/WEB-INF
The WEB-INF directory is part of the servlet 2.2 specification. According to the specification the WEB-INF directory should contain a file called web.xml which defines your servlets and any parameters the serlvets need. Most servlet engines will not strictly enforce these standards but trying to work around it will usually give you more headaches than solutions.
The next step is to copy the cocoon web.xml file and cocoon.properties files to your WEB-INF directory and copy the sample files to the webapps directory.
$ cd /path/to/cocoon-1.8
$ cp src/WEB-INF/web.xml $TOMCAT_HOME/webapps/cocoon/WEB-INF/
$ cp conf/cocoon.properties $TOMCAT_HOME/webapps/cocoon/WEB-INF/
$ cp -R samples/ $TOMCAT_HOME/webapps/cocoon/samples
The last thing you need to do is edit the web.xml file you just copied. Open $TOMCAT_HOME/webapps/cocoon/WEB-INF/web.xml in an editor. You will see the line:
<param-value>[path-to-cocoon]/conf/cocoon.properties</param-value>
Change it to:
<param-value>WEB-INF/cocoon.properties</param-value>
Now stop and start Tomcat.
$ $TOMCAT_HOME/bin/shutdown.sh
$ $TOMCAT_HOME/bin/startup.sh
While Tomcat is loading you will see:
2001-01-26 01:35:04 - ContextManager: Adding context Ctx( /cocoon )
If you see this then everything is good. Open a browser and go to http://localhost:8080/cocoon and try some of the samples. Not all of the samples are meant to be viewed in a browser so don't worry if you get errors with some of them. If you can see hello-page.xml then everything is working.
Next: Defining your document >>
More XML Articles
More By Olivier Eymere
