How to use the Hippo Cocoon Maven plugin

What is it?

The hippo-cocoon Maven plugin is used to deploy projects based on Hippo Cocoon. All sites using hippo-cocoon, as well as all hippo-cms instances can be deployed using this plugin. It is stored in SVN under "hippo-cocoon/plugin". The main script executed by Maven is src/plugin.jelly. The resources used by the plugin itself are under src/plugin-resources. These are mainly patchfiles.

The plugin has different 'goals' in the plugin.jelly script. A goal is like a job that has to be done, a subroutine that can be called from within other goals. The most important goals in the hippo-cocoon plugin are:

• cocoon:deploy
• cocoon:install
• cocoon:dist
• cocoon:repository-install
• cocoon:repository-deploy
  To run these goals, you need to install the latest hippo-cocoon plugin in your maven repository (see below). Maven matches the called goal globally to all installed plugins, that's why a namespace is used ("cocoon:").

Installing the plugin

maven plugin:download -Dversion=(versionnumber) -DartifactId=hippo-cocoon-plugin -DgroupId=hippo-cocoon

Replace '(versionnumber)' with the latest available version number. You can find this number by looking it up in the Hippo public repository: http://repository.hippocms.org/maven/hippo-cocoon/plugins/. The current version is 2.01.01 (updated 2007-08-21).

The above command will download the plugin from the Hippo repository and store it in your local repository. Maven uses the latest installed version of the plugin.

Also install Patch!

Sometimes maven refuses to download and install the new plugin. You'll need to delete the plugin on your computer in three places: C:\apache\maven\plugins (or where you installed maven) C:\Documents and Settings\bvdschans\.maven\cache (change username) C:\Documents and Settings\bvdschans\.maven\repository\hippo-cocoon\plugins (change username)

Project.xml

A plugin uses the project dependency information that is in the project.xml file (the "POM"). It looks for this file in the directory from where you called maven. The project.xml describes all dependencies, and maven will first download all of them in your local repository as long as they are not already available, and then copies them into the target folder in your project.

This is the place to set your project's name and versionnumber (under /project/name and /project/currentVersion). The plugin uses these variables to insert the versionnumber and projectname in some places. It makes finding, reporting and fixing bugs a lot easier, so don't forget to do it.

The Goals

Maven cocoon:deploy vs maven cocoon:install

Both goals do the same thing, except for the fact that "install" copies your site source files (/src/site) into the new hippo-cocoon directory structure under "sites". "Deploy" references to your site source files from within the hippo-cocoon deployment. It does so by patching the sitemap in the hippo-cocoon it installs in your target directory. This results in an absolute path that won't work when deployed on a live server - that's why we have the cocoon:install goal; to make sure it works on a different file structure by using only relative paths.
Also, cocoon:install searches for any occurance of @maven.cocoon.site.name@ and @maven.cocoon.site.version@ and replaces it with the project's name and version (as defined in the project.xml) into any file in your /src/site directory.

Use this to insert the projectname and versionnumber into the header of all pages so you can lookup the site's versionnumber by looking at the source code of one of the pages.

Clean or not so clean?

Any maven goal can be called with an extra "clean" prefix: "maven clean cocoon:install" or "maven clean cocoon:deploy" etc. This will delete the /target folder and recreate it. The plugin.jelly script in the plugin won't patch and copy all files over and over again when you don't add the 'clean' parameter. So, it deploys faster when you skip the 'clean'. But, when you want to put the site live, do use "clean"!

Maven cocoon:deploy

The main goal.

• First of all, it checks if you have a "src/site" directory in your project. It checks for Java sources in /src/java, and it checks to see if you have a dependancy for a hippo-cocoon distribution at all (if not, it will fail).
• It stores the location of your site/src files in a variable called 'maven.cocoon.site.directory' for later reference
• It extracts the Cocoon distribution
• It compiles any Java sources in your project
• It looks for any configuration files present in your project (sites.xconf, repositories.xconf, user.roles)
• Then, it copies all files in your /src/cocoon directory (if you have any) into the target Cocoon directory. You can use this if you have any special needs for the Cocoon installation.
• It walks through all dependency jars in the project.xml file and copies them into the target /WEB-INF/lib directory
• It copies any jar files that were previously compiled from your Java sources into the target /WEB-INF/lib directory
• It X-patches the repositories.xconf file with all the xpatch files under the plugin's /xpatch directory. These will:
  • Insert the correct credentials as defined in your build.properties
  • Set the repository configurations as defined in your build.properties
• When defined in your build.properties, it will also configure any live repository and sites
• It patches the cocoon.xconf with your memory settings
• It set your site domains in the sites.xconf
• It runs all xpatches defined in your /src/config directory according to their postfix:
  • "*.xconf" on cocoon.xconf
  • "*.xroles" on roles.xconf
  • "*.xlog" on logkit.xconf
  • "*.xlog4j" on log4j.xconf
  • "*.xweb" on web.xml
  • "*.xmap" on sitemap.xmap
  • "*.xsite" on sites.xconf
• And finally, it patches the wrapper.conf file (if you have set maven.wrapper.executepatchfile to "true") with ('maven.wrapper.'..)
  • initmemory
  • maxmemory
  • servicename
  • servicedisplayname
  • servicedescription
  • servicedependency.1
  • servicedependency.2
  • port
• That's it. You are now ready to start the hippo-cocoon by running
  • target/hippo-cocoon-{version}/bin/wrapper.exe -c wrapper.conf
    *(Windows) or
  • sh target/hippo-cocoon-{version}/bin/fortress.sh -c wrapper.conf
    *(for Linux)

Maven cocoon:install

cocoon:install does the same as cocoon:deploy but also copies your site source files (/src/site) into the new hippo-cocoon directory structure under "sites", as described in "Maven cocoon:deploy vs maven cocoon:install" above.

Maven cocoon:dist

This is the same as "maven clean cocoon:install", but as an extra it zips the target folder into a nice zipfile.

Maven cocoon:repository-install

This will call cocoon:dist and copy the zipfile into your local Maven repository.

Maven cocoon:repository-deploy

This will call cocoon:dist and copy the zipfile into the final Hippo public repository. Do this only when releasing a new version of the project and make sure you TAG SVN, raise the version number in project.xml and commit this new version.

Jira

The project's name in Jira is "HIPCOPLUGIN": http://issues.hippo.nl/secure/BrowseProject.jspa?id=10165.
If you need any functionality that patches something somewhere in a hippo-cocoon deployment, please assign it in Jira.

Changes

2.0.8 CHANGES

-------------

Added properties:

maven.extensions.dir=../extensions

Sets the maven.cocoon.extensions.path property with the right relative (for cocoon:deploy) or absolute (for cocoon:install) path to an "extensions" directory.

This can be used when wrapping the CMS into a wrapper project with the following directory structure:

+ wrapperproject
    |
    +-- editor (svn:external to hippo-cms/editor)
    |    |
    |    +-- (editor code....)
    |    |
    |    ....
    |
    +-- extensions
    |    |
    |    +-- sitemap.xmap
    |    |
    |    +-- mountedfolder
    |         |
    |         +- code....
    |
    +- project.properties

Inside the main project.properties (the one in the root folder), add

maven.extensions.dir=../extensions

Then, build the CMS by doing

$ cd editor
$ maven clean cocoon:deploy

The difference is that now you "wrap" the editor folder inside a custom project, with the extensions property. The hippo-cocoon plugin will pass the corresponding path as the maven.cocoon.extensions.path property to the Cocoon sitemap, which can use it in an inputmodule (for example, the globalconstants).

2.0.4 CHANGES

-------------

Added properties:

maven.wrapper.servicedependency.1
maven.wrapper.servicedependency.2

Use these to set service dependencies in Windows.
Example:

maven.wrapper.servicedependency.1=hippo-repository

This will make sure that the hippo-repository service has been started before starting up the current service.

Troubleshooting

I get a 'Cocoon home is not set' error message

If your 'maven cocoon:deploy' or 'maven cocoon:install' build fails with a "Cocoon home is not set" message, you are probably trying to build from the wrong directory (e.g. the target/hippo-cocoon/bin directory because you started the wrapper from here). Maven should be executed in directory where your project.xml file lives.

I get a 'Provider org.apache.xalan.processor.TransformerFactoryImpl not found' error message

This error message comes from the Hippo Cocoon plugin trying to generate the XPath grammar files with an XSLT transformation when using Java 5. Due to a Maven limitation (see MAVEN-156) the class name of the XSLT transformer factory has been hardcoded in the plugin. This solution works well with JDK 1.4, but fails with Java 5 that uses a different XSLT transformer.

To work around this problem, Java 5 users need to place xalan-2.6.0.jar in the $MAVEN_HOME/lib/endorsed directory. Maven 1.1 users need to place the file in $JAVA_HOME/jre/lib/endorsed as Maven 1.1 does not have a private endorsed library directory.