Your first Cocoon application using Maven 2

In this tutorial, you will:

1. Create a Cocoon block (the application resources and logic)
2. Import the block as a project in Eclipse
3. Start the block as a web application and access it from your browser

First, make sure that you have Maven 2.0.8 or above installed. You can check this by calling mvn --version from the command line. If this doesn't work for you, read the Maven in 5 Minutes tutorial.

Creating a Cocoon block

Create a new directory which will be the root directory of your Cocoon application and change into it. For this tutorial, let's name it getting-started-app.

The next step is to create a Cocoon block to contain your custom application. The development of any Cocoon web application should be done within a block.  A Cocoon block is little different to any other kind of Maven block.  It simply has a particular directory and file structure.

We could manually create the block, but a simpler route is to use Maven's 'archetype' plugin.  This allows us to select from a list of block types and have Maven create them for us.  The default list of archetypes is quite large.  For convenience, a catalog of Cocoon archetypes is available on the Cocoon web site and we shall use that.

The current version of the Archetype plugin (2.0 alpha-3) has a bug which prevents it accessing the remote copy of the Cocoon archetype catalog.  The following instructions will be simpler when this is fixed.

First save the catalog somewhere convenient.  In Windows you could open a browser on http://cocoon.apache.org/archetype-catalog.xml and save it from there.

In Unix you could execute the command: -

wget http://cocoon.apache.org/archetype-catalog.xml

Now run the following Maven command and when requested type in the answers (shown in bold): -

> mvn archetype:generate -DarchetypeCatalog=file://archetype-catalog.xml
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
...
[INFO] [archetype:generate]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: local -> cocoon-22-archetype-block-plain (Creates an empty Cocoon block; useful if you want to add another block to a Cocoon application)
2: local -> cocoon-22-archetype-block (Creates a Cocoon block containing some small samples)
3: local -> cocoon-22-archetype-webapp (Creates a web application configured to host Cocoon blocks. Just add the block dependencies)
Choose a number:  (1/2/3): 2
Define value for groupId: : com.mycompany
Define value for artifactId: : myBlock1
Define value for version:  1.0-SNAPSHOT: : 1.0.0
Define value for package: : com.mycompany.myBlock1
...
 Y: : y
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------

If you are using a cocoon binary build from svn trunk then you probably want to change the archetypeVersion to the most recent one, matching the svn trunk. (see [cocoon-svn]/tools/archetypes/cocoon-22-archetype-block/pom.xml)

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

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

Import the block in Eclipse

Cocoon is not tied to Eclipse IDE by any means. This step only describes what can be done to avoid tedious work of setting up project in Eclipse manually.
If you don't use Eclipse, you can either skip this step or find a similar procedure to load the block in the IDE of your choice.

Change into the myBlock1 directory and call

mvn eclipse:eclipse

This will create the necessary project descriptors for Eclipse. In Eclipse you can import the project into your workspace: File - Import - General - Existing Projects.

If that's the first time you use Eclipse together with a project created by Maven 2, we recomment to read the Maven Guide using Eclipse with Maven 2.x.

Run the block as Java web application

After creating the block you probably want to run it. For this purpose there is a Maven plugin, that generates a minimal web application that loads your block. The pom.xml of your block already contains all necessary configurations.

You can then run

mvn jetty:run

and point your browser at http://localhost:8888/myBlock1/ and get a hello world page.

The mentioned minimal web application is automatically created, when mvn jetty:run is invoked. This happens because the rcl goal of the Cocoon plugin is bound to the Maven build lifecycle which is invoked too, when the jetty:run goal is executed. See the block's pom.xml for details.

This process can be manually triggered with mvn cocoon:prepare too.

Conclusion and further information

So far you have created a block. You have also been able to run the block in Jetty. Of course, that was only the first step in order to get a  "Hello world" as result. If you wonder how you can do some useful stuff like writing your own Cocoon pipeline or some Java code, there are more tutorials:

• Your first XML pipeline
  Cocoon has become 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
  While following this tutorial, you will create 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 (aka skinning).
• 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.
• Deploying a Cocoon application
  Although you have already been able to run this block, you most probably need a Java web application (war file) in order to deploy it to the servlet container (Tomcat, Jetty, etc.) of your choice.
  

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 (create Eclipse configuration files, release, produce documentation, etc.) that Maven offers. More information about Maven 2 can be found at the project website. Especially we recommend reading

• Maven in 5 minutes and the
• Getting started guide