Quinn Dombrowski: Cocoon on Ubuntu

Installing Cocoon 2.2 on Ubuntu 8.10

This guide was prepared with help from a guide written on the GSLIS wiki by Wendell Piez. If you try it and something doesn't work, please e-mail me (quinnd -at- uchicago +dot+ edu). This document is licensed Creative Commons Attribution.

No knowledge of Ubuntu or Unix is assumed; the intended audience is someone who's managed to install Ubuntu and isn't too intimidated by the Terminal.

Step 1: Installing Java SDK

Open the Terminal (Applications > Accessories > Terminal)
Type:
```
sudo apt-get install sun-java6-jdk
```
(Hint: You can copy and paste, but in Terminal, pasting is Ctrl + Shift +C)
There'll be some downloading, you'll have to scroll through a long TOS and agree to it, but then it will install on its own.
Close Terminal.

Step 2: Installing Maven

Derived from Maven in Five Minutes.

Download Maven (choose tar.bz2)
Open the tar.bz file; by default, it probably saved to the Desktop
Extract it to the Desktop
Open the Terminal again and type:
```
cd /usr/local

sudo mkdir apache-maven
```
At this point, the Terminal will ask you for your sudo password. It's the same as the password you use to log in to Ubuntu. Then:
```
cd /home/YOUR_USER_NAME/Desktop
```
(be sure to replace YOUR_USER_NAME with your user name)
```
sudo mv apache-maven-2.0.9 /usr/local/apache-maven

export M2_HOME=/usr/local/apache-maven/apache-maven-2.0.9

export PATH=$M2:$PATH
```
Cross you fingers and type:
```
mvn --version
```
If everything worked right, it should display information about the version of Maven you have installed.
Close Terminal.

Step 3: Installing Cocoon

Derived from Your first Cocoon application.

Make a directory for your Cocoon install.
- Using the GUI: go to Places > Home Folder, then in that new window, File > Create Folder.
- Or, open the Terminal:
```
mkdir cocoon
```
- In the following text, I'm assuming you make a folder called cocoon in your Home Folder; if you give it a different name or put it somewhere else, you'll have to change the commands accordingly.

Open the Terminal and change directory to your cocoon folder:

cd cocoon

mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org

This begins the install process.
- For archetype, choose 2
- Define value for groupId: - This should be a unique value. A classic value to use is, if you own the namespace myurl.com, you could type com.myurl
- Define value for artifactId: cocoon
- Define value for version: 1.0-SNAPSHOT: 1.0.0
- Define value for package: - groupID.cocoon (i.e. com.myurl.cocoon)
After everything's done installing, you should see [INFO] BUILD SUCCESSFUL
Make sure you're in your cocoon directory in Terminal (does it say ~/cocoon$ right before the cursor?), and type
```
mvn jetty:run
```
There'll be a lot more installing, but it should conclude with [INFO] Started Jetty Server
Open a browser and go to http://localhost:8888/cocoonTest - you should see a message saying Apache Cocoon: Welcome

Step 4: Cocoon Add-ons

There are a couple add-ons for Cocoon that are essentials-- like generators for HTML. If you want to use XSLT 2.0, Saoxn 9 is also critical. Posibly less important are the FOP processor (to generate PDFs from XSL-FO), Batik (for SVG) and Forms (to genrate forms). If you don't need to use XSLT 2.0, you can skip the first part of this section.

Installing Saxon 9 - a good idea

Open your cocoon directory and navigate to src/main/resources/META-INF/cocoon
Create directory avalon

Create the following files in Text Editor (Applications > Accessories > Text Editor), and place them in the avalon directory:

File named cocoon-core-xslt-saxon.xconf

<?xml version="1.0" encoding="UTF-8"?>
<components>
<component role="org.apache.excalibur.xml.xslt.XSLTProcessor/saxon" 
class="org.apache.cocoon.components.xslt.TraxProcessor">
<parameter name="use-store" value="true"/>
<parameter name="transformer-factory" value="net.sf.saxon.TransformerFactoryImpl"/>  
</component> 
</components>

File named sitemap-transformers-saxon-transformer.xconf

<?xml version="1.0" encoding="UTF-8"?>
<map:components xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:transformers>
<map:transformer name="xslt2" src="org.apache.cocoon.transformation.TraxTransformer"> 
<xslt-processor-role>saxon</xslt-processor-role>
</map:transformer>  
</map:transformers>
</map:components>

Download http://prdownloads.sourceforge.net/saxon/saxonb9-1-0-5j.zip
Extract the zip file to you Home folder; you can delete everything but saxon9.jar

Open a new Terminal

cd cocoon
    
mvn install:install-file -DgroupId=net.sf.saxon -DartifactId=saxon -Dversion=9.1.0.5 -Dpackaging=jar -Dfile=../saxon9.jar

Go to cocoon and open pom.xml

At the bottom of <dependencies>, add:

<dependency>  
<groupId>net.sf.saxon</groupId>    
<artifactId>saxon</artifactId>    
<version>9.1.0.5</version>  
</dependency>

If for some reason you only want Saxon 9 and not the ability to generate HTML, skip to the bottom of this section

Installing HTML support

Still in pom.xml, at the bottom of <dependencies>, add:

<dependency>
<groupId>org.apache.cocoon</groupId>
<artifactId>cocoon-html-impl</artifactId>
<version>1.0.0</version>
</dependency>

Installing FOP (for PDFs)

Still in pom.xml, at the bottom of <dependencies>, add:

<dependency>
<groupId>org.apache.cocoon</groupId>
<artifactId>cocoon-fop-impl</artifactId>
<version>1.0.0</version>
</dependency>

Installing Batik (SVG)

Still in pom.xml, at the bottom of <dependencies>, add:

<dependency>
<groupId>org.apache.cocoon</groupId>
<artifactId>cocoon-batik-impl</artifactId>
<version>1.0.0</version>
</dependency>

Installing Forms

Still in pom.xml, at the bottom of <dependencies>, add:

<dependency>
<groupId>org.apache.cocoon</groupId>
<artifactId>cocoon-forms-impl</artifactId>
<version>1.0.0-RC1</version>
</dependency>

There's a list of all blocks, and the syntax for the dependency code is in there someplace.
Once you're done adding dependencies:
1. If you have a Terminal open with [INFO] Started Jetty Server, close it.
2. Open a new Terminal
```
cd cocoon
            
mvn compile
```
  After it's done...
```
mvn jetty:run
```

Redirecting the Sitemap

You can add your pipelines to the sitemap.xmap in cocoon/src/main/resources/COB-INF, or (more conveniently) you can tell that base sitemap to look elsewhere for your files.

I'm assuming here that you have a folder called myproject in your Home folder where you have all your files and your sitemap. Please change that, and your user name, accordingly.

Included here is also the code to generate more useful error messages than a blank pages.

In sitemap.xmap in cocoon/src/main/resources/COB-INF, at the bottom of the <pipelines< section, add:

<map:pipeline>
<map:handle-errors>
<map:generate type="exception"/> 
<map:serialize type="xml"/>
</map:handle-errors>   
<map:match pattern="myproject/**">
<map:mount uri-prefix="myproject/" check-reload="yes"
src="/home/YOUR_USER_NAME/myproject/sitemap.xmap" reload-method="synchron"/>
</map:match>
</map:pipeline>

In this case, your project will be found at http://localhost:8888/cocoonTest/myproject/[things that match your pipelines]. But it doesn't have to match the folder name with your files. You can change the URL by chanigng <map:match pattern="myproject/**"> to <map:match pattern="whatever_you_want/**">

Hints and Tips

Every time you restart Ubuntu, you have to restart Cocoon:

cd cocoon

mvn jetty:run

Be sure to keep that Terminal window open while you're working with Cocoon. You can always check if Cocoon is working by going to: http://localhost:8888/cocoonTest.

Wendell Piez and Quinn Dombrowski, 2009

Quinn Dombrowski

Coordinator, Emerging Technology Development NSIT Academic Technologies, University of Chicago

Installing Cocoon 2.2 on Ubuntu 8.10

Step 1: Installing Java SDK

Step 2: Installing Maven

Step 3: Installing Cocoon

Step 4: Cocoon Add-ons

Redirecting the Sitemap

Hints and Tips

Coordinator, Emerging Technology Development
NSIT Academic Technologies, University of Chicago