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.

Git-a-bit - How Git can be useful when being tied to Subversion

There's been a lot of talk lately about the new distributed version control systems like Mercurial, Bazaar or Git. It feels like just yesterday we started the fight to convince the world to switch from CVS to Subversion, and hopefully most of us won. But now more and more projects and even companies are switching to one of the new SCM systems, which might make one both consider why they do so and if one would have to undergo all that pain of convincing and migrating again if the concept looks appealing.

Distributed version control systems offer many advantages. They support offline working without the need of large feature cumulating commits when going back online again, which might be the first usecase people see and understand easily. But scratching the surface a bit, it reveals that there is a lot more, like ultra powerful (of course distributed) branching and merging facilities enabling new development team workflows such as continuous integration per developer/pair, enhanced environments for subteam or featureset driven branches, and a lot more.

Let's say you got intrigued by the features and the advanced workflows those new systems offer and you might have decided to give Git a try because you heard that your IDEA IDE now supports full Git integration, and you are convinced that Linus is a cool guy - what next? Move your or your companies' repositories to Git? Even more complicated, if you are a freelancer or consultant like I am, convince all your customers that this is the next cool thing and they have to switch immediately?

A scenario I recently experimented with came up when I was thinking about a feasible process to enable a local CI infrastructure for experimental changes on the Struts 2 codebase. While we have our central CI builds set up, they mostly make sense for features which are targeted for soon to integrate improvements, unless you are working on a fresh early branch like upcoming version 2.2. You would not want to push highly experimental code that might break builds for a longer time or even might never make it into a release to the upstream repository. Nevertheless, when your experiments turn out to be both stable and useful, you would want to push them as a whole to the main repository.

The solution I came up with was to use git-svn locally, which is not only able to make a git repository mirror out of a svn repo, but also to push changes back to the original svn repository. It helped me to introduce a very useful workflow, allowing me to commit small changes to my local git repository, triggering a local Hudson build, while I go over to the next change. I'm also able to pull incoming svn changes easily, improving the quality of the local integration test and solve merge issues upfront. After implementing and testing all changes, the commit to the svn repository then goes as a whole.

I started to build the Git mirror infrastructure from scratch, without knowing the concise Apache documentation on that topic which Don Brown pointed me to later. The only downside for my boilerplate solution was that since our svn tree is part of the huge Apache svn repository containing all revisions of all projects, the initial creation of the git-svn repo took about one (!!) day - it scanned about 7.3 million revisions only to get our "small" tree synced. But once done, things ran very fast, and getting the local infrastructure with Hudson and IDEA Git up and running was just peanuts.

After all, I found this workflow also very useful for my clients' projects, both for having a CI infrastructure set up even when the client refuses to and to have a good offline working infrastructure in place.

Moved - You're now watching my shiny new official blog

After some weeks of evaluation, I've decided to move my blog over here. The interface is compelling and the tool support, líke e.g. offline authoring, rocks. I still love the fantastic JRoller service and I have to thank for enjoying a free and high quality service there. But now let's start over here, combined with the hope that the easier authoring will push me to write more frequntly (to be proven ...)
I have to admit that I've not posted too many articles yet, but some of them might still be of interest - so here is a short link list of my previous posts on Ray's Blog:

• Struts2 voted as cool by Devoxx2008 visitors
• HTTP Proxy Servlet for Ajax Calls with Authentication Support
• Enhancing configurability by logging Hibernate SQL statements using Log4j
• Managing log4j Logging Levels for WebApps at Runtime using JMX

There are already a couple of new topics I want to write about, let's see if I find the passion to do so :)

Howto connect Mini-USB plug to HTC phone

I ordered a power adapter for my amazing little Android developer phone aka HTC Dream last week. When I unpacked it, I was a little disappointed because it looked like it was the wrong plug to be delivered, namely a conventional Mini-USB plug rather than a HTC ExtUSB one. I contacted the seller and complained, but he was desperately trying to convince me that it would work. Lucky enough, before making a total fool of me, I gave it a second try - and voila, it works! To document this, I recorded a demonstration video (of rather poor quality, better turn of sound) - to help my seller argue, and to convince other people that it works after all.

So empty ...

After starting this blogger site (and, well, saving this name I really like), I was heading back to my old blog site at JRoller, although it isn't that slick to work with as blogger is. Coming back here after some time now, I realized a couple of things:

• this blog is desperately empty
• the UI and publishing / linking options are really great here
• if you're already googlenized (using GMail, Reader , GTalk, Docs and what not), it is so easy for Google to track my hole life to connect things nicely
• sooner or later my brandnew adp1 phone will have a blogger client, I bet
• I should spend more time blogging....

I'm seriously considering to move my useless thoughts here, but I'm not convinced yet.