Deploying a Cocoon application

This tutorial is based on the Your first Cocoon application using Maven 2 which shows how to bootstrap a Cocoon project and Modularize Cocoon apps which shows how inter-block communication works. If you haven't followed the latter tutorial, you can go through this tutorial nonetheless but you have to skip everything that refers to myBlock2.

In this tutorial, you will:

1. Connect blocks to the webapp and run it
2. 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)
3. Change the block mount point so that it is mounted at the root level context (typical for a web application's "main block")

Creating a Cocoon web application

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-RC1
  -DgroupId=com.mycompany
  -DartifactId=myCocoonWebapp

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

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

Using a block within the web application

So far the web application myCocoonWebapp doesn't have any information about the existense of the block myBlock1 and myBlock2. 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>
      <dependency>
        <groupId>com.mycompany</groupId>
        <artifactId>myBlock2</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 three 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>
    <module>myBlock2</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 its child modules, you have to add the parent element to getting-started-app/myCocoonWebapp/pom.xml , getting-started-app/myBlock1/pom.xml and getting-started-app/myBlock2/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"/>

to

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

and then run mvn:install.