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 by calling

mvn --version

from command line.
If that works for you, create a new directory which will be the root directory of your Cocoon application. For this tutorial, let's name it getting-started-app. Move 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

Creating a block

The next step is creating a Cocoon block which will contain your custom application. The development of any Cocoon web application is 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

Move into the myBlock1 directory and call

mvn install

from there. This installs the block into your local Maven 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.xmland 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>
  <name>Cocoon Getting Stared application [parent]application</name>
  TBD
  <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.

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