WARNING: you are not looking at the live version but at an older version.

Your first Cocoon application using Maven 2

In this tutorial, you will:

Create two Maven modules: a Cocoon web application (mounted in a servlet container), and a Cocoon block (the application resources and logic)
Connect the block to the webapp and run it
Create a parent Maven POM for the webapp and block (a convenience which allows you to trigger cascading builds of both maven modules from a single command)
Change the block mount point so that it is mounted at the root level context (typical for a web application "main block")

Creating a Cocoon web application

First, make sure that you have Maven 2.0.4 or above installed. You can check this by calling

mvn --version

from command line. If this doesn't work for you, read the Maven in 5 Minutes tutorial.

Next create a new directory which will be the root directory of your Cocoon application. For this tutorial, let's name it getting-started-app. Change into it and invoke the cocoon-22-archetype-webapp archetype:

mvn archetype:create
  -DarchetypeGroupId=org.apache.cocoon
  -DarchetypeArtifactId=cocoon-22-archetype-webapp
  -DarchetypeVersion=1.0.0-M2
  -DgroupId=com.mycompany
  -DartifactId=myCocoonWebapp

For copy and paste without line feeds:
mvn archetype:create -DarchetypeGroupId=org.apache.cocoon -DarchetypeArtifactId=cocoon-22-archetype-webapp -DarchetypeVersion=1.0.0-M2 -DgroupId=com.mycompany -DartifactId=myCocoonWebapp

Because of a Maven bug, it could be necessary to add the apache.snapshots Maven repository to getting-started-app/myCocoonWebapp/pom.xml:

<repositories>
  [...]
  <repository>
    <id>apache.snapshot</id>
    <name>Apache Snapshot Repository</name>
    <url>http://people.apache.org/repo/m2-snapshot-repository</url>
    <releases>
      <!-- excalibur poms are located here -->
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  [...]
</repositories>

The next release of the archetype will already have set the repository settings.

Creating a block

The next step is creating a Cocoon block which will contain your custom application. The development of any Cocoon web application should be done within a block. Again, for this purpose there is a Maven archetype:

mvn archetype:create
  -DarchetypeGroupId=org.apache.cocoon
  -DarchetypeArtifactId=cocoon-22-archetype-block
  -DarchetypeVersion=1.0.0-M5
  -DgroupId=com.mycompany
  -DartifactId=myBlock1

Once again for copy and paste without line feeds:
mvn archetype:create -DarchetypeGroupId=org.apache.cocoon -DarchetypeArtifactId=cocoon-22-archetype-block -DarchetypeVersion=1.0.0-M5 -DgroupId=com.mycompany -DartifactId=myBlock1

Because of a Maven bug, it could be necessary to add the apache.snapshots Maven repository to getting-started-app/myBlock1/pom.xml:

<repositories>
  [...]
  <repository>
    <id>apache.snapshot</id>
    <name>Apache Snapshot Repository</name>
    <url>http://people.apache.org/repo/m2-snapshot-repository</url>
    <releases>
      <!-- excalibur poms are located here -->
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  [...]
</repositories>

The next release of the archetype will already have set the repository settings.

Change into the myBlock1 directory and call

mvn install

from there. This installs the block into your local Maven repository in ~/.m2/repository.

Looking at the filesystem, you should find following directory structure:

getting-started-app
 +-myCocoonWebapp
 |  +-pom.xml
 |  +-src
 |     +-[...]
 +-myBlock1
    +-pom.xml
    +-src
       +-[...]

As you can see, the web application and the block are at the same level.

Using the block within the web application

So far the web application myCocoonWebapp doesn't have any information about the existense of the block myBlock1. Change this by opening getting-started-app/myCocoonWebapp/pom.xml and add the block as dependency:

<project>
  [...]
    <dependencies>
      <dependency>
        <groupId>com.mycompany</groupId>
        <artifactId>myBlock1</artifactId>
        <version>1.0-SNAPSHOT</version>
      </dependency>
    </dependencies>
  [...]
</project>

That's it. Now it's time to run the web application. Move into getting-started-app/myCocoonWebapp and call

mvn package jetty:run

from there.
Open your favorite web browser and call

http://localhost:8888/myBlock1/

That's it!

Creating a parent pom

For your convenience you can create a parent pom for the two Maven modules. Create a file getting-started-app/pom.xml with following content:

<project xmlns="http://maven.apache.org/POM/4.0.0" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <packaging>pom</packaging>
  
  <groupId>com.mycompany</groupId>
  <artifactId>getting-started-app</artifactId>
  <version>1-SNAPSHOT</version>
  
  <name>Cocoon Getting Stared application [parent]</name>
  
  <modules>
    <module>myCocoonWebapp</module>
    <module>myBlock1</module>
  </modules>
</project>

Having a parent pom file, you can trigger a reactor build from root, e.g. you can call mvn install from root which will compile, package and install the webapp and the block. Maven also takes care that the modules are build, according to the dependency graph, in the correct order.

If you want to inherit information (e.g. plugin configurations, properties, etc.) from the new parent pom to the two modules, you have to add the parent element to getting-started-app/myCocoonWebapp/pom.xml and getting-started-app/myBlock1/pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  [...]
  <parent>
    <groupId>com.mycompany</groupId>
    <artifactId>getting-started-app</artifactId>
    <version>1-SNAPSHOT</version>
  </parent>
  [...]

</project>

Mounting your block at the root level

You can mount your block at the root level in the application URI space, so that instead of using (for example) the URI http://localhost:8888/myBlock/foo/bar to request a page, you would request it at http://localhost:8888/foo/bar.

To do this, edit myBlock/src/main/resources/META-INF/cocoon/spring/block.xml , and change the element

    <property name="mountPath" value="/myBlock1"/>

    <property name="mountPath" value=""/>

and then do mvn:install.

Conclusion and further information

So far you have created a Cocoon application that consists of a web application and a block. You have also been able to run the application in Jetty.
Probably you wonder how you can do some useful stuff like writing your own Cocoon pipeline or some Java code. For this purpose there are two more getting-started documents:

Usage of the reloading classloader plugin
The reloading classloader plugin enables rapid development of Cocoon applications since you don't have to restart the servlet container whenever one of your Java classes changes. Additionally it provides all settings to enable the reload of Cocoon resources too.
Your first XML pipeline
Cocoon is famous for XML pipelines. At this tutorial you will learn how to setup your first pipeline and will learn the most important things about Cocoon sitemaps.
Adding a second block
This tutorial created a web application that has a dependency on one block. There are use cases that require more than one block, e.g. you want to have all style specific resources within a single block that can be easily exchanged at deployment time (-> skinning).

For the time being, we recommend the usage of Maven 2 as build system (though there is no hard dependency on it). This has the advantage that the build system is standardized and Cocoon web applications can reuse the toolset (creating Eclipse configuration files, releasing, create documentation, etc.) that Maven offers. More inforamtion about maven can be found at the project website. Especially we recommend

Maven in 5 minutes and the
Getting started guide

Comments (4)