Apache » Cocoon »

Cocoon 2.2 homepage

Cocoon 2.2

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
Note: First, make sure that you have Maven 2.0.9 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 one or more  blocks.  Cocoon blocks are little different to other Maven blocks except they have a particular expected directory and file structure.
Note: You could manually create your blocks, but a simpler and less error-prone process is to use Maven's 'archetype' plugin.  This allows you to select from a list of block types and have Maven create them for you.  By default, the list of Maven archetypes is quite large.  For convenience, a catalog of Cocoon specific archetypes is available on the Cocoon web site and you will make use of this in the following instructions.
Run the following Maven command:
mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org

Maven will generate some output and then interactively ask you for some information:

Choose archetype:
1: remote -> cocoon-22-archetype-block-plain (Creates an empty Cocoon block; useful
 if you want to add another block to a Cocoon application)
2: remote -> cocoon-22-archetype-block (Creates a Cocoon block containing some small
 samples)
3: remote -> 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

Maven first asks which archetype you want to create.  Item 2 in this list is the standard Cocoon block with some small sample files already in place.

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

Maven then asks a few more questions.  Just enter the details as shown above.  The groupId is a label that you can use to group all the blocks in your application.  The artifactId is the unique label that will identify this block from all others.  It is also the name of the directory that will be created to contain the block's files.  The package is the Java package that any Java files in the block will be assigned to.

Note: 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

Note: 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... > Existing Projects into Workspace

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

Run the block as Java web application

After creating the Cocoon 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 the necessary settings.

mvn jetty:run

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

Note: 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.
Note: This process can be manually triggered with mvn cocoon:prepare too.

Conclusion and further information

So far you have created a Cocoon block and been able to run it in Jetty.  This is only the first step to creating a full-blown Cocoon application.  If you would like to know  more read the following tutorials:

  • Your first XML pipeline
    Cocoon is well known for its XML pipelines.  In this tutorial you will learn how to setup your first pipeline and discover the power of Cocoon sitemaps.
  • Adding a second block
    This tutorial creates a web application that has a dependency on another 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 enables the reloading of Cocoon resources too if they change.
  • Deploying a Cocoon application
    Eventually, you will probably need to create a Java web application (war file) in order to deploy your application to a servlet container such as Tomcat or Jetty, etc.  This tutorial shows you how.
For the time being, we recommend you use Maven 2 as your 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, create releases, produce documentation, etc.). More information about Maven 2 can be found at the project website.  We especially recommend reading: