Building a Site and using Properties

When building a site in Maven you are likely to want to use custom properties, such as the version #, artifact/group ids and so forth. This isn't as easy as it should be. First you'll need to attach an extra '.vm' to the end of any apt, fml file that you want to be filtered. Without this the ${property} references in these files will not be replaced with values.

A word on the properties you'll use in these site template files. They may not have '.'s in them. That's right you can't have a property such as 'pom.version' in your templates. So instead you'll need to add properties that do not use this character.

<properties>
    <currentVersion>${pom.version}</currentVersion>
<properties>

Then in your apt file you can now put in ${currentVersion} and it will resolve to the pom's version element value in the generated html file.

Authenticating When Using the SCM Plugin

If you are using the SCM plugin with Mercurial then you will likely need to pass the username and password to it. This can be done with the following arguments to the mvn command:

"-Dusername=<username> -Dpassword=<password>"

You also can create a server element in your 'settings.xml' file (in ~/.m2) which has an id that matches the host part of the SCM url, then set the username/password in the respective elements. This'll keep you from having to put in the values on the command line again and again.

<server>
    <id>www.blueleftistconstructor.com</id>
    <username>rob</username>
    <password>pass</password>
</server>

When using the release plugin I've always had to use this technique to 'push' the changeset from my local mercurial repo to the remote one.

Note that one unfortunate side effect here is that the HG Maven plugin WILL OUTPUT YOUR CREDENTIALS IN CLEAR TEXT!!!

This doesn't bother me all that much since I run a pretty tight ship, but if this violates your comfort level you may be out of luck as far as the release plugin goes.

Mercurial (HG) Source Control with Maven

I've been using Mercurial for quite some time now. I've also been back up to my old tricks. On switching jobs a while back I came back into using Maven. I've also been hacking up some projects with pals and we host them on my site blueleftistconstructor. We found it would be easier to work on, distributed as we are, if we used Maven and created a Maven repository.

Well these projects are under Mercurial source control. I won't go to much into why I use Mercurial, especially why I use it over git, darcs and so forth. Lets just say I suits me and my partners.

So how easy is it to use Maven with Mercurial? Very easy it turns out. There was a little snag which I will get to later. First though you need to go get Mercurial. If you have a Mac you probably can just use easy_install, which is likely already installed. Try this:

easy_install mercurial

Using easy_install is my perferred method of installation. Otherwise download from the site.

Once you have verified Mercurial installed you just need to go into your projects root folder and type 'hg init' and you'll see Mercurial taking care of adding needed files. Now you will want to use the 'hg add' command to add files into source control. Read the docs for more information on how you can 'ignore' files.

Ok now we are ready to tell Maven that we are using HG to control. You will need to configure the scm section of your projects pom. It should look something like this:

<scm>
  <connection>scm:hg:https://www.blueleftistconstructor.com/hg/netflix-client</connection>
  <developerConnection>scm:hg:https://www.blueleftistconstructor.com/hg/netflix-client</developerConnection>
  <url>https://www.blueleftistconstructor.com/hg/netflix-client</url>
</scm>

Note that you will have to replace the URLs above with your own. The 'connection' URL is a public accessible URL, while 'developerConnection' is not going to be read only. The 'url' is a source control browser such as ViewVC or Fisheye.

Thats it. You now can use all sorts of Maven commands to manage source control actions. I myself don't often use these. The real benefit here is in releasing versions of your software. With the source control repo configured Maven takes care of committing, tagging, and rolling the version number up.

For more on releasing a Maven project that is configured for source control read this, and this.

Go west young man

This is (likely) my last post to this blog. I've spent the past 2 and a 1/2 years using Maven primarily in my Java projects and my companies. Part of this I think is just growing up. When I first started using Maven I had just started work at a company who's development team consisted of some novice Java users. It of course did not help then that a lot of the software they had was written in Java. Queue some of the ugliest Ant build files I have ever seen. These people obviously had never been exposed to C/C++ and make in an academic environment... as they would have been heckled for such lack of simplicity. These Ant build scripts just wouldn't fly for me. So I found Maven. I used it to simplify the build environment, for my co-workers and myself. I encountered problems while using Maven which I solved. I watched the community slowly build up. I started a blog and shared my knowledge. It was fun.

I've progressed A LOT in the past two years. I am no longer a guy who is fresh out of college, smart but unprepared for nastiness which the enterprises of the world contain. I've honed my technique, worked on numerous projects (many more than the majority of people out of college for only a few years), and I have made honest appraisals of the things I have done. I'm at a point now where the expressivity of a tool such as Ant makes it much more viable than something like Maven. If Maven was Java, then Ant would be Python. I can do the same two things in both, but one is much easier to use (Python, duh).

Other things that have pulled me away from Maven, and more specifically Maven's ideology, are tools such as Gant (Groovy language + Ant) and scripts in Pylons (Python web framework). Being able to use the full power of a language right there in a build file, is a beautiful and powerful thing. I also would argue this is daunting for the novice. I have come full circle from Ant to Maven and back to Ant. I'm now ready to work on projects where the full responsibility is mine in making sure the build files are clean, coherent and useful. I recognize now that this is not a lot of responsibility, that the fact my previous co-workers could not handle it speaks volumes for the type of organization they were running.

Please drop a line if you have any questions about articles I've written here. You can reach me at mentalstasis. at. hotmail. com. I'm always interested in some convo with other computer professionals out there so don't hesitate. Thanks to all you readers out there, and best of luck.

-Rob O.

Utilizing Maven Plugins: Jetty plugin

The problem: You would like to use a non-standard Maven plugin, such as the Jetty plugin.

The solution: First things first you will probably need to register the plugins group, so that Maven will know where to look. To do this you should put an entry in your settings.xml file. For our example here we will use the Jetty plugin. It has a group id of 'org.mortbay.jetty'. In your settings.xml file put an entry such as:

<pluginGroups>
  <pluginGroup>org.mortbay.jetty</pluginGroup>
</pluginGroups>

What this little piece of configuration does is tell Maven to search for plugins registered under the given group id. You can have as many 'pluginGroup' elements in your xml file as you want/need. In all my work with Maven I have only actually registered two plugin groups, one of which is Jetty... but if you create your own you will need to register your plugin group.

Lets start by creating a web application using a Maven archetype:

mvn archetype:create -DgroupId=com.mycompany.app -DartifactId=my-webapp -DarchetypeArtifactId=maven-archetype-webapp

This will create a folder called 'my-webapp'. Change over to this directory. Now we are going to use the long way of specifying the plugin. This is ugly and you certainly will not want to use this form often (likely ever).

mvn org.mortbay.jetty:maven-jetty-plugin:run

You should now be able to hit your web app on http://localhost:8080. The above command could be broken down as 'mvn groupId:artifactId:goal'. More on this in a bit. Now lets run the same 'run' goal using a short command syntax. Here is a simpler way to do the same thing:

mvn jetty:run

Much easier. Now I'll explain a bit. Since we put the plugin group entry in our settings.xml file we do not need to specify it like we did in the long command above. In the long command, after the group id, we have 'maven-jetty-plugin'. Maven expects the artifact id to be in a form 'maven--plugin'. For the Jetty plugin the artifact id is 'maven-jetty-plugin'. In the part after the colon in the long command we specify this artifact id. Now in the simple version we just have 'jetty'. Maven will take the 'jetty' value and automatically know to look for 'maven-jetty-plugin'. This saves you from typing out the whole shebang.

If your are interested in creating your own plugin I suggest you check this link out. It is not nearly as hard as you may imagine.

Exercise: Continuum

Today's article is going to be a step by step on getting a pretty hefty Maven based project up and running on your machine. I will finish by having the project set up in Eclipse of better development. The project is Continuum. It is a continuous integration server created by the Maven community.

We will start by checking out Continuum. Use this command to get the project from Subversion:

svn checkout http://svn.apache.org/repos/asf/maven/continuum/trunk/ continuum

Once you have the project downloaded 'cd' on over into it. Do a ls or dir command. You will now find you are looking at a multi-module Maven project! Egads thats a different sight in comparison to a non-multi-module project. Well lets kick things off by running:

mvn install -Dmaven.test.skip

We don't want to test, for now. You will need to run install so that each module's artifact (jar) gets put into your local repo. This is important because a module can rely on artifacts created by other modules, and so the artifacts must be available via repo. This will take a bit, Continuum is fairly big. Once things are done you will want to prep Continuum for Eclipse. Run the command:

mvn eclipse:eclipse

This will go into each module and create the Eclipse meta files, so that you can import them into Eclipse no problems.

We now are at the last step. Open up Eclipse, right click in the 'package manager' view (window). Select 'import'. This pops up a window, select 'general > existing projects into workspace'. Point to the folder containing all the modules and click ok. You will notice Eclipse finds a project for each module. Click ok. After a bit of grunting Eclipse will present you will a view full of projects, one for each module.

At this point you may need one last thing. If you do not have the M2_REPO Eclipse you will need to set it. Check the 'problems' view, if you see a bunch of messages about this not being set... bingo. Go into preferences then "java > build path > classpath" and add the var, giving it a value of the location of your local repo. Mine is "/home/ottaway/.m2/repository".

Going Offline

The problem: You want Maven to stop making all those network calls when you issue it commands like clean, build, test, package etc. You might want to work on a project while you have no network connection.

The solution: You can use the off line mode for Maven to keep it from making any network calls. You can do so by issuing the -o flag to the mvn command. When using this mode Maven will need to have all the jars it needs in your local repository (~/.m2/repository by default). To make this easier you can use a trick provided by the dependency plugin. Imagine we just checked out a project. Now we want to work on this project off line. To get all the dependencies needed by the project you can issue the command "mvn dependency:go-offline". This will download the dependencies you need. Now note it will not make sure you have all the plugins you need. Say you want to run "mvn -o site:run", creating a site for your project and making it available via Jetty. You will need to have used this plugin before so that it is in your local repo. The same goes for compile, package, test and the like.

The million dollar question is why use off line mode? Well it could be that it makes quicker the process you are doing with Maven, since Maven will not try to call out to any network repos. I've timed the difference between using it and not using it for some fairly large projects and found it doesn't make a huge difference. For really big projects (I cannot really name one) it might shed enough seconds to make it worth using often, maybe even creating an alias. This 'huge' project mind you would probably have upwards of 200 jar (dependencies) or more being managed. Another reason one might use off line is as follows: you have a local network repository used by the developers at work. One day the person you administers this repository is going to move it somewhere new. This going to take a few hours. Using off line mode you could weather this time if prepared without noticing too much that the repository is down. This could also be helpful in situations where you are going to not be able to reach the repository, like working at home with no network connection, or the server hosting the repo crashed.