Tutorial: setup Eclipse workspace for Hippo CMS

As a senior Java developer I’ve gained quite some experience in the last couple of years. Not only I know how to identify great software architecture or horror code, but also how my local development tool should look like. For example, the ideal IDE can check out a project from a repository, helps me to write code, automatically compiles and is able to deploy this code directly to a server which is manageable within that IDE. That’s why we call it an Integrated Development Environment, right?

I was a little bit surprised that the current Hippo documentation doesn’t give any directions on how to setup your (Eclipse) IDE correctly, meeting the ‘ideal’ requirements from above. The documentation describes the different Maven commands outside Eclipse and how to deploy your software using Cargo. That’s not really ‘integrated’, is it?

This tutorial explains how to configure your Eclipse (Indigo) environment using the Maven integration and the Eclipse server runtime environment.

Prerequisite

• Some basic knowledge about Eclipse and Maven (you known how to execute a ‘clean install’ from the command line right?)
• Make sure you have a standard Eclipse installation using the M2Eclipse plugin, running JDK6. From Eclipse 3.7 (Indigo) M2Eclipse is already integrated, but make sure you add the WTP connector (Preferences > Maven > Discovery > Open Catalog).
• Download Tomcat 6 (in this tutorial, we copy the zip to c:developmenttomcat6)

Create your project using the Archetype

Create a new Maven Project

Next, select the Hippo Archetype hippo-archetype-website (currently v1.07.00). Notice that the first time you see this page you have to add a new Remote Catalog (Catalog File: http://maven.onehippo.com/maven2).

Note: I was able to reproduce this issue a couple of times, but I’m not sure if this is a local issue. The first time you try to generate your new project you will see (or not) the following error. Fix: simply restart creating a new maven project and you will notice that Archetype Properties are prefilled the second time…

Configure as Maven project

Downloading all the Hippo artifacts takes a couple of minutes. But after that you see 6 projects in the Package Explorer, all set up properly as Maven Java projects.

Two projects show an error for the pom file. A fix is described in here.

Configure your Server

Now, as soon as all errors are solved you have to configure your server configuration. The Hippo demo includes a preconfigured Tomcat installation so it’s probably a good idea to start with Tomcat as well. Basically, what we do is run the Maven Cargo command once and copy the configuration to our local server setup.

First, create a new server runtime environment in Eclipse. Select the Tomcat v6.0 Server and point it to your Tomcat 6 download.

Second, build all projects from the root directory:
mvn install

Third, run the Cargo command from the root directory:
mvn -P cargo.run

After Cargo successfully deployed the webapp you can shut it down. Notice that Cargo created some tomcat configuration files in the /target/tomcat6x directory (e.g. catalina.properties, context.xml, jar files, etc). We will use these files to create our own standalone tomcat instance.

• Copy all JAR files from the /target/tomcat6x/common/lib/ and /target/tomcat6x/shared/lib/ directory into your local Tomcat6 install directory (in this tutorial c:developmenttomcat6). Simply create the same folder structure and copy the files.
• Open de /target/tomcat6x/conf/catalina.properties and copy the defined paths for the /common/lib/ and /shared/lib/ to your own catalina.properties which is located in the Eclipse workspace.

 

It should look like this:
common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,${catalina.base}/common/lib/*.jar
shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar

• Open de /target/tomcat6x/conf/context.xml and copy the <Parameter …/> and <Resource …/> elements to your own context.xml, in the Servers project.
• Add the following system properties to your Tomcat 6 runtime environment (change to appropriate paths). Double click on the Tomcat item you created. Click Open launch configuration and go to the Arguments tab.

-Dderby.stream.error.file="C:developmenttomcat6logsderby.log" -Dlog4j.configuration=file:C:/development/workspace/hippo_speeltuin/hippodemo/conf/log4j-dev.xml -Dproject.basedir=C:/development/workspace/hippo_speeltuin/hippodemo/ -Xms256m -Xmx1024m -XX:MaxPermSize=256m

• Change the Server Location setting to Use Tomcat installation, to make sure your catalina.properties configuration won’t be ignored (not sure if this is an Eclipse bug).

Finished!
And you’re done. Start your Tomcat server and enjoy the full power of your integrated development environment. Debugging works out of the box and all your JSP templates will automatically be redeployed (without running Cargo from the command line). Also, if you need extended class reloading like adding methods, change static fields, etc, you can enable JRebel in your IDE (license required).

Extras
Every time the Tomcat server restarts all your changes are lost because the Hippo repository is restored. Setting up a remote repository location will prevent this. Add the following system property:
-Drepo.path=file:C:/development/hippo_repo