Setting up a Portlet Development Environment with Eclipse 3.5, Maven and Liferay 5.2

While normally I would prefer Netbeans or IDEA for developing Liferay based applications, I had to setup an Eclipse based environment due to client's needs. Basically this is a protocol incorporating known sources such as Developing portlets for Liferay in Eclipse or A portlet dev. environment using maven2.

If you haven't already, get a Eclipse copy from Eclipse Downloads. Install it and chose a workspace when starting. I prefer to setup a clean workspace for the Liferay setup, but this is of course no requirement.

Next, we need some plugins, most of which are served by external update sites which have to be added via the Help > Install New Software menu. Click Add... to register a new site, afterwards chose the site in the "Work with..." dropdown box to get a list of available modules. Check the modules of choice and let the wizard do the rest. The following plugins are needed:

1. Subclipse 1.6
   Homepage: subclipse.tigris.org
   Update Site URL: http://subclipse.tigris.org/update_1.6.x
   Full installation recommended
2. m2eclipse 0.99 dev
   Homepage / Documentation: Maven Integration for Eclipse - Codehaus
   Update Site URL: http://m2eclipse.sonatype.org/update-dev
   Full install recommended, except "Maven Integration for ADJT", since it seems to have unresolved dependencies (at least by the time of writing this)
3. BIRT 2.5
   Update Site URL: http://download.eclipse.org/birt/update-site/2.5/
   Note: Just add the update site, since it is needed for dependency resolving for JBoss Tools
4. JBoss Tools
   Homepage / Documentation: JBoss Tools
   Update Site URL: http://download.jboss.org/jbosstools/updates/development/
   Feel free to check what you like, but if a feature has something like "Portlet", "Richfaces" or "JSF" in it's name, it is highly recommended to include, while the SDKs should usually be less of interest.

Now it's time to get you a copy of Liferay from the Liferay Portal Download Page. The following steps assume that you get the Community Edition Tomcat 6.0 Bundle. Unzip / untar the bundle into a directory of choice - my recommendation is the Eclipse workspace directory we want to use for our Liferay development.

At first, a new server configuration for our Liferay installation has to be defined. Activate the Server tab at the bottom, right click in the free area and chose "New > Server". Fill the dialog as shown and click "Next". In the following dialog, chose the Tomcat directory within your Liferay installation folder and an appropriate JRE (1.6+ recommended). You are safe to click "Finish" now, since we have no resources to configure for the server yet. Double click the newly configured server in the server tab to open it's configuration options.

There are a couple of things we want to adjust:

• Set a longer start (300s) and stop (60s) timeout, since Liferay has to take it's time
• Make sure that the Tomcat installation folder will be used for deployment
• Select a suitable deploy path. Since we will configure Maven to do our deployment, we chose the Tomcat temp folder rather than webapps or the Liferay hot deployment folder.
• Adjust the VM start parameters to increase the heap and PermGen space limit. Therefore, click "Open launch configuration" and add something like -Xmx512m -XX:MaxPermSize=192m to "Arguments > VM arguments"

The following screenshot shows the values chosen in the server configuration tab.

Now is a good time to start the configured server for the first time and check that everything works. Especially if starting the very first time, some patience is needed since Liferay will need a lot of time to initialize. If everything went well, your browser should open a new window or tab with the portal content.

For the first portlet application, m2eclipse's feature to create new Maven projects based on Maven archetypes comes handy. Select "File > New > Other ... > Maven > Maven Project" and click "Next". The following dialog may remain unchanged, so click "Next" again. The next dialog gives you the actual archetype selection. Chose the "internal" catalog to find the standard portlet archetype. After clicking "Next", you will be able to provide a group and artifact id, an initial version and the main package to place your Java classes. Hitting the "Finish" button will make the new project show up in the Project Explorer. Check that it is marked as a web project. If not, you may have missed to in install the m2eclipse WTP support feature.

Check the project properties and make sure that the JRE System Library under "Java Build Path > Libraries" points to a "modern" Java execution environment such as 1.6. If not, hit the "Edit" button to fix this.

Next step is to fix the portlet-class entry in portlet.xml, which the current maven portlet archetype seems to mess up with a combination of group id with artifact id. Replace it with the fully qualified name of the MyPortlet class found under the package you provided when creating the project from the archetype:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xsi:schemalocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
                            http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">

    <portlet>
        <description>Write here a short description about your portlet.</description>
        <portlet-name>simple-portlet</portlet-name>
        <display-name>simple-portlet Portlet</display-name>

        <portlet-class>net.itneering.simpleportlet.MyPortlet</portlet-class>

        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>VIEW</portlet-mode>
        </supports>

        <supported-locale>en</supported-locale>

        <portlet-info>
            <title>Put the portlet title here</title>
            <short-title>Portlet Short Title</short-title>
            <keywords>put keywords here</keywords>
        </portlet-info>
    </portlet>
</portlet-app> 

Now everything is ready to configure our pom to let Maven do the deployment to Liferay. For the hot deployment, Liferay requires us to drop a war file in <Liferay Home Directory>/deploy. While you could configure this to be some other directory, the requirement for the war packaging remains. The usual way Eclipse handles the deployment, which is copying the web application resources to the configured Tomcat webapps folder, will not work, since Liferay has to get it's hand on the configured portlets before Tomcat.

For that reason Maven will be utilized to not only build the war artifact, but also copy it to the Liferay's hot deployment directory. While copying the artifact to an arbitrary filesystem location is not a core feature of Maven nor a Maven plugin I'm aware of, it is quite easy to accomplish since Maven's antrun plugin can do the job for us. All we have to do is bind it to a suitable phase, in this case the package phase which will be targeted by invoking package, install and deploy goals. To do so, add the following snippet to the pom.xml file:

<build>
    <finalname>simple-portlet</finalname>
    <plugins>
        <plugin>
            <artifactid>maven-antrun-plugin</artifactid>
            <executions>
                <execution>
                    <phase>package</phase>
                    <configuration>
                        <tasks>
                            <copy todir="../liferay-portal-5.2.3/deploy" file="target/simple-portlet.war">
                        </copy></tasks>
                    </configuration>
                    <goals>
                        <goal>run</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Please note that if you change the finalName, you will have to adjust the copy target as well. Unfortunately, the ${finalName} variable will not get substituted if you'd try this.

While we do not have to, as a final step the application should be added to the server profile we created. This will help Eclipse to find the code of our project and it's dependencies when it comes to debugging. To do so, right click the server in the Servers tab and chose "Add and remove ...", then add the portlet application to the "Configured" list.

Now start the server, if you like in debug mode. When Liferay is up and running, right click your pom.xml and chose "Run as > Maven package". The war file gets built and copied the deployment folder. A few seconds later you should notice Liferay registering the portlet application in the console. You are now ready to add the portlet to a portal page and set breakpoints or do hot code replacements in debug mode.