Friday, August 15, 2014

Make your portlet development use maven in no-time

Background

I started using maven some time back and I have found many advantages. One in particular was the ease to run unit tests. This made me want to be able to unit test portlets. The portlets I create nowadays are all based on the JSR286 standard. I did not find any examples of that, but with some help from what I found I was able to do unit testing. First things first though. Before we can use unit testing for portlets, we need to have a portlet where we also use maven. This blog entry will show you have you as simple as possible get your portlet sources mavenized. 

I will not cover the topic of why you should use portlets or maven. There are so many good resources out there already and a simple search should be easy enough to find them.

Basic portlet

First of all I have a really minimalistic portlet. There is only what I need to have inb order for the portlet to work. The point was to give a basic example of what you need to do to start using maven to build your portlet. In this I had the portlet class, a jsp file, the portlet.xml, the web.xml and some resource bundle property files.

Preparations

In order to use maven you need to have some software installed. You need to have a jdk (I used the latest available from Oracle) and maven. Make sure you have your maven binaries set in your path and your JAVA_HOME environment variable set to the directory where you installed the JDK. Note! It must be the jdk, a jre will not be sufficient in the long run.

If you just want to use the central maven repository and have direct access to Internet you don't need to do any other configuration, but if your network setup is different you may need to look at additional steps to configure maven, such as using a proxy with maven.

Moving files

Maven use a standard layout for its directories. You are in no way obliged to follow this standard and I am not going to even get into a discussion about what is best, I will simply leave that up to you. In this example though, I am using the standard directory layout as it makes the maven configuration easier. 

A portlet is packed in a web application archive, a war file. While maven has no direct portlet packaging available, it is not really required either as we use the war packaging, which effectively does the job. With this in mind there in particular three directories which we will use from the maven standard.
At this step you should move all of your portlet files into these three directories.
src/main/java should contain all your java sources. It is the root directory of your java sources so if you have your classes in packages, that structure must still be intact. The compiled classes will end up in your WEB-INF/classes directory. src/main/resources contains non-java files which should end up together with your compiled classes. In this case the portlet ResourceBundle property files will be here. Again, if you are using a package structure for your resources, that structure must be intact. The resources files will be copied as is (depending on your maven configuration) to your WEB-INF/classes directory. Finally the src/main/webapp directory contains all the files which should end up in the root directory of your web application. This includes any jsps you may have as well as your META-INF and WEB-INF directories (and all the files there in such as WEB-INF/portlet.xml and WEB-INF/web.xml). 

After all of this is completed I ended up with the following file structure:

Maven configuration

The heart of maven configuration is the pom. It is in xml format and its name is pom.xml. This file was created in the root directory. First there was the basic stuff. I won't go into details of any of this. Some of it is fairly self explanatory, but for the rest I suggest you look at the pom reference.
Finally the portlet apis need to be added in order for the portlet class to be compiled. For this we add a dependency. A dependency is really what the name implies. In order to compile and build our portlet we have a dependency on another library (apart from standard java) in this case the portlet api. For this portlet to work only the portlet api is needed, but there may be many dependencies. Note the scope in this dependency. With the scope of provided we are telling maven that this dependency will be provided later on, we only need to use it now at compile time. This is true because the portlet libraries are provided by the portlet container when we run the portlet. The libraries should not be included in our war file.

Building

Now we are done and we are ready to build. The command to build, package and verify as much as possible without adding our built war to the local or remote repository is mvn verify. If all has been done right you should get a BUILD SUCCESSFUL message in the end.

References

No comments:

Post a Comment