Your first Cocoon application using Maven 2

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-M1
  -DgroupId=com.mycompany
  -DartifactId=myWebapp

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

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-M4
  -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-M4 -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>myWebapp</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>

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