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

mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org

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): 3

Define value for groupId: : com.mycompany
Define value for artifactId: : myCocoonWebApp
Define value for version:  1.0-SNAPSHOT: : 1.0.0
Define value for package: : com.mycompany.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

In order to use blocks as dependencies you need to install them into Maven's local repository. First go to myBlock1/ directory and execute following command:

mvn install

Then go to myBlock2/ and execute the same command. This way both blocks will get installed into local repository where Maven stores all artifacts that can be used as dependencies.

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/myBlock1/foo/bar to request a page, you would request it at http://localhost:8888/foo/bar.

To do this, edit myBlock1/src/main/resources/META-INF/cocoon/spring/blockServlet.xml , and change the element

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

to

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

and then run:

 mvn install