Monthly Archives: May 2009 | mojavelinux.com

A game-changing Maven 2 plugin you absolutely must use

May 04, 2009

Ever since I first started using Maven 2, I envisioned having a console in which I could execute life-cycle goals without having to incur Maven's startup cost between every run. It just seemed to me such a waste for Maven to build up the project object model (POM) from the pom.xml only to run a single sequence of goals and immediately shutdown. It also gives the impression that Maven is slow. In fact, it's extremely slow when it's used in this way, especially multi-module projects. But it doesn't have to be if you take advantage of...

The maven-cli-plugin

Today my vision has come true thanks to Mr. Don (and the ease of collaboration made possible by git). Having a similar vision to mine, he wrote the maven-cli-plugin, hosted at github.com. This plugin uses the jline library to create an execution console for Maven 2 (i.e., command shell), shown here:

maven2>

At the prompt you can issue Maven 2 life-cycle phases or plugin goals. The console even supports tab completion of commands! In this entry, I'll explain how you setup and use this console to put Maven into hyperdrive.

Technically, the plugin has two consoles. One is for executing Maven 2 life-cycle phases, including all prerequisite phases, and the other is used to only run plugin goals (the life cycle is not executed). Those are the same two ways you use Maven 2 from your normal shell. In this entry, I'll be focusing on the execute-phase console.

A fork in the road

I was thrilled when I first discovered the plugin, but after giving it a shot I was disappointed to discover that it wasn't honoring profiles, which are a critical piece of the build (see issue 2). I didn't give up hope though. Since Mr. Don had done most of the legwork in creating the plugin, I figured it wouldn't be that difficult for me to figure out why the profiles weren't working. Sure enough, in under an hour I discovered the source of the problem and was able to apply a fix. That left me with the dilemma of how to distribute my changes. I wanted to be able to use the plugin in the Seam 3 examples, so I couldn't just maintain a hacked version on my computer. Github.com (and git) saved the day.

Following the process for creating a fork on github.com (for which they practically spoon feed you the instructions), I forked the code and committed my changes to a publicly accessible repository. You can access both the master tree and my forked tree. You'll need the version from my tree to use all the features I cover in this entry. Hopefully Mr. Don will merge my changes into the master tree soon, but the fact that you can get my code today is a true testament to the influence git can have on open source collaboration.

Now let's "git" on with the presentation.

Getting started

To get started, add a plugin repository where the maven-cli-plugin is hosted as a top level element in your pom.xml. I recommend using the JBoss maven repository because it hosts my forked version.

<pluginRepositories>
    <pluginRepository>
        <id>repository.jboss.org</id>
        <name>JBoss Repository</name>
        <url>http://repository.jboss.org/maven2</url>
    </pluginRepository>
</pluginRepositories>

Alternatively, you can publish the plugin to your local or company repository. Grab the source from github.com or the binaries from the JBoss Maven repository. Remember, you need my forked version until my features get merged in. Follow the project at github.com to find out when that happens.

Next, define the maven-cli-plugin inside the build > plugins element in your POM. This just allows you to use the plugin prefix from the commandline, which is cli. You're also going to use this section to add some configuration options later.

<plugin>
   <groupId>org.twdata.maven</groupId>
   <artifactId>maven-cli-plugin</artifactId>
</plugin>

With the setup out of the way, I'm going to demonstrate three reasons why this plugin is game-changing. By the end, I guarantee you'll be jumping out of your chair.

#1 - Speed

Let's face it, Maven is dog-slow. That's because it has to parse that heap of XML the Maven developers call a POM. Then it has to figure out what it's supposed to execute. Then it pings the internet for updates. Then it enforces constraints. Then it runs through all the precursor phases (likely including tests). And finally it arrives at the phase you really want it to execute.

Of course, some of those steps can be trimmed using various flags, switches, and properties. But that means having to type, and remember, a ridiculously long command that is just something no human should be expected to do. More on that later. Let's deal with this startup cost once and for all.

We'll begin by firing up the maven-cli-plugin phase executor console. You run it just like you would any other Maven plugin:

mvn cli:execute-phase

After Maven goes through it's normal loading process, you are presented with a command prompt:

maven2>

From here you can type any of Maven's life-cycle phases, such as package, or a plugin goal (more on plugins later). Give it a try:

maven2> package

The first time the life cycle executes, you'll see a noticeable improvement in speed. By the second execution, it's blazing fast! You can just feel years being added back to your life. Power up!

Now it's time to extend the build with...

#2 - Profiles

One of the most powerful features of Maven is profiles. In fact, I think Maven is pretty useless without them. That's because in Maven, you really only have one "command" you can execute, the Maven 2 life cycle. There must be a way, then, to instruct that execution pass to perform different steps along the way. That's what profiles are for. With a profile, you can hook additional plugins to a phase as a way to weave that extra behavior into the build.

But we have a dilemma. Profiles are typically activated from the commandline either explicitly using the -Pprofile flag or through an activation, typically by assigning a property such as -Dproperty=value. How can we set the profile once we are in the command console? This is where my contribution to the maven-cli-plugin comes in.

The commands typed in the console are processed by the jline ConsoleReader from the maven-cli-plugin, not by Maven. That means we can allow any command we want, including flags like -P and -D. Fortunately, Maven was designed in such a way that an execution is isolated internally from parsing the POM. So it's possible to execute a life-cycle phase with a different set of profiles and properties, or even put Maven into offline mode for a single execution, without having to start the console again.

I hacked up the maven-cli-plugin to support the following flags:

-P activates the profile specified immediately after the flag (no spaces); this flag can be used multiple times
-D assigns a property specified immediate after the flag (no spaces) in the form name=value; this flag can be used multiple times
-o puts Maven in offline mode for a single execution; if not specified, will inherit the setting used to start the console
-N instructs Maven not to recurse into projects in the reactor
-S skip tests, an alias for -Dmaven.test.skip=true

Here's an example of a command you can issue:

maven2> clean package -Prun-integration-tests -o

That would activate the run-integration-tests profile, run the clean plugin and the life cycle up to the package phase, all while executing Maven in offline mode (to avoid checks for missing pom files, snapshots, and plugin updates).

In addition, the maven-cli-plugin already supported specifying individual projects by artifactId. This allows you to execute a phase on a sub-project without having to descend into that project or use the -f flag.

Let's say you are working with an standard EAR project and you want to build the WAR. To package just the WAR, you would either have to change into the war directory and execute Maven or use the -f flag as follows:

mvn -f war/pom.xml package

With the maven-cli-plugin, you can accomplish the same thing using this command (note that "seam-booking-war" is the artifactId of the module):

maven2> seam-booking-war package

Ah, the simplicity! And now, for the grand finale!

#3 - Aliases

Aliases are the Holy Grail of Maven 2. When I switch people from Ant to Maven, the first thing they get annoyed about is the ridiculous commands they are required to type. To put it simply, if you want to run clean and package, there is no way to specify that with a single command. You have to type:

mvn clean package

Things get worse with plugins. All plugin goals must be namespaced. That's because Maven 2 technically supports any command in the world, as long as there is a plugin to execute it. To run Jetty on a WAR project, for instance, you have to type:

mvn run:jetty

If you want to run clean, package, and then start jetty, you have to type:

mvn clean package run:jetty

Let's say that you also need to expand the WAR in-place and you want to run offline. Then the command becomes:

mvn -o clean package war:inplace run:jetty

I think you can see where this is going. When I first setup the booking examples for Seam 3, the record for the longest commandline in the readme went to this command, which undeploys, packages, and redeploys an EAR to JBoss AS:

mvn -o -f ear/pom.xml jboss:undeploy && \
  mvn -o package && \
  mvn -o -f ear/pom.xml jboss:deploy

Uuuuugly! That's why the aliases feature of the maven-cli-plugin is absolutely game-changing (perhaps even life changing). In fact, combined with the other two features I have covered, they make Maven 2 better and faster than Ant, hands down. I'll go so far as to say that there has never been a faster, more convenient way to execute builds.

So what is an alias? Quite simply, a string of commands you would otherwise have to type in the console, aliased to a single word. You define them in the plugin configuration. Here's an alias I put together to deploy an exploded EAR archive to JBoss AS in the Seam booking example:

<plugin>
   <groupId>org.twdata.maven</groupId>
   <artifactId>maven-cli-plugin</artifactId>
   <configuration>
       <userAliases>
           <explode>package -o -Pexplode</explode>
       </userAliases>
   </configuration>
</plugin>

After starting up the console, the user only has to type one word:

maven2> explode

It's no longer even necessary to prefix commands with mvn (or ant in the old days). Just one command. One word.

The execute-phase console also supports direct execution of plugin goals. That means you can include them in the alias command. The only limitation is that when you include one in an alias, you have to specify the fully qualified name of the plugin (groupId:artifactId) before the goal rather than just it's prefix (e.g., org.codehaus.mojo:jboss-maven-plugin rather than jboss). This next alias invokes the harddeploy goal of the jboss-maven-plugin after packing the project.

<userAliases>
   <deploy>seam-booking-ear package -o org.codehaus.mojo:jboss-maven-plugin:harddeploy</deploy>
</userAliases>

You can even mix aliases with regular commands. Perhaps you want to clean first:

maven2> clean deploy

I find it nice to alias commonly used built-in Maven goals too, such as the one that lists the active profiles:

<userAliases>
   <profiles>org.apache.maven.plugins:maven-help-plugin:active-profiles -o</profiles>
</userAliases>

The maven-cli-plugin also provides a handful of built-in aliases.

If this plugin isn't game changing, I don't know what is. All I can say as hell yeah!

See the Seam 3 booking example to see this plugin in action and read additional commentary.

Update: There is also a cli client for IntelliJ IDEA that can invoke builds remotely. Of course, the plugin supports this from the commandline too.

Update: I should also mention that this is a great way to debug Maven since you get an opportunity to attach a debugger before executing a command. First, set the MAVEN_OPTS environment variable:

MAVEN_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"

Then run cli:execute-phase, attach a debugger (port 8787 in this case) and execute a command.

Posted at 02:18 PM in Java, Programming, Usability | Permalink | Comments (38)

mojavelinux.com: Open Source Advocacy