One of the key things driving the adoption of Maven, is the rich set of plugins available. Whenever you want to add some functionality to the build process, or possibly even just want to do a one-time job, chances are that there is already a plugin for that.

When you want to use Maven plugins, you need to get more information about them to know how to use them. Most often, there is online documentation that describes the goals and parameters. However, sometimes no such documentation exists or you just cannot find it. Also, the online documentation very often describes the latest version of the plugin – but what if you have to use an older version?

This blog post will explain the different options you have to retrieve information about a plugin, just by using Maven itself.

As mentioned above, the simplest way of viewing a plugin’s documentation is to use the one provided online. Not only does this documentation describe the available goals and the plugin’s parameters, but it most often also provides examples and other useful information. If available, this should normally be your first choice. However, there are at least two other ways of retrieving information from a plugin about it’s goals and parameters. These come in handy when there is no other documentation, and also when you want to be sure to find the goals and parameters of a specific version of the plugin.

The first option, and most likely the easiest one to remember, is to use the help goal of the plugin itself. Here’s an example:

mvn compiler:help

This would give you an overview of the goals of the Maven Compiler Plugin. If you want more information, add the detail parameter:

mvn compiler:help -Ddetail

If you want to focus on a specific goal, you do that through the goal parameter:

mvn compiler:help -Ddetail -Dgoal=compile

Please note that this will describe the version of the plugin according to normal Maven plugin management. To override that, there is always the option of specify the plugin version through the standard Maven syntax.

mvn org.apache.maven.plugins:maven-compiler-plugin:2.3:help -Ddetail -Dgoal=compile

Another great thing about the help goal is that it is created by Maven Plugin Plugin. So you could very easy add this feature to your own plugin as well, only by adding a simple POM configuration. However, this dependency is also the drawback. The functionality in Maven Plugin Plugin was added in version 2.4, so plugins (or older versions of plugins) written before that would not have the help goal. Fortunately, there is another option for those cases.

A fallback option is to use the Maven Help Plugin and its describe goal. It will work with any version of a plugin you want to describe. As an example, here is the equivalent to the one above:

mvn help:describe -Dplugin=org.apache.maven.plugins:maven-compiler-plugin:2.3 -Ddetail -Dmojo=compile

As this feature is described in detail in chapter 6.3.1 of Maven: The Complete Reference and also in the online documentation of Maven Help Plugin, I will not go into more details about it.

Try the different options and see which one you prefer. Please note that even if they provide much of the same information there are some slight differences. In some areas, like information about default phase binding, I find the help:describe option more informative.

Nexus OSS Core has more than 120 REST Resources published. And that number is just increasing with new Nexus Plugins. Not to mention Nexus Pro that comes with even more plugins and more REST resources.    Everything you do in Nexus, whether you use the Maven Nexus plugin or the Nexus UI, is interacting with a REST service that is available to you if you want to write your own customizations and scripts.   It has been this way since we started the project in 2007.  In this post, I’m going to discuss how this came to be, how Nexus was developed with REST in mind from the beginning.

Nexus: A Core of REST Services

When we started the Nexus project, I called it a “blind” application.  A “blind” webapp is one with no UI technology whatsoever built-in.   All it publishes is a few static files, and a REST API.   All of the UI that you see in Nexus is Javascript.   Your browser executes Javascript which, in turn, interacts with a set of services.   The only presentation technology on the server side is a trivial Velocity template used to render the initial “shell” of the page.

The server-side application you call Nexus, doesn’t generate the UI, that is all Javascript.   It is a completely separate and standalone application, that runs in your browser! A self contained JavaScript application (powered by ExtJS), that communicates with Nexus server, using REST calls only.  This has one very important consequence: whatever Nexus functionality you are able to reach using the Nexus User Interface (and I do mean all), you can do with a plain REST client.     If you want to automate a task, you can use a tool like curl, or some Ruby script, or any HTTP capable client.   You can even start to implement your own custom interface if you would like a completely customized UI.

As I said, it was like this since day one. But, we always had one major issue that prevented wider acceptance of Nexus’ REST API: we had no up-to-date documentation for it.    It wasn’t a priority, we spent much of our time trying to integrate the only existing REST framework (restlet.org) with Plexus, and since we were moving so quickly to implement new features, we didn’t think it made sense to stop and document an ever-changing interface.  We did maintain a wiki page which described the REST services from the beginning of the project, it always provided stale information given our aggressive development pace.

REST Documentation: Using Enunciate

I’ve been looking at the Enunciate project for some time, and it appears to be the solution to our REST document issues.  Enunciate is a cool project hosted on Codehaus, with a bold promise:

Enunciate is designed to make your life easier. Enunciate deals with your deployment difficulties, documentation, and client-side code. By using Enunciate to publish your service interfaces, not only will you have all three Web service interfaces (SOAP, REST, and AMF), but you’ll also have full up-to-date documentation generated, strongly typed ActionScript code that you can use to invoke your remote services from your Flex code, and rich client-side libraries that can be used to access your Web services from a variety of platforms (including Mac/iPhone).

Our initial plans are to use Enunciate in a “lite” mode to generate documentation (and potentially client side code) for our current REST API. Later, we plan to integrate it more closely into new Nexus “Remoting API” implementation, and it will be the backbone of our REST services when we will implement version 2.0 of our API.

Here is just a taste of what is to come.  We’ve used Enunciate to generate documentation for our REST services, and the work is proceeding very quickly.   Here is a snapshot of the documentation we will be releasing soon.

Remaining Problems to Solve

When our REST API was concieved in Q4 of 2007 we didn’t have the rich array of options that we have today.   One major REST library was available, and that was Restlet.  JSR311 wasn’t around back then, so we were forced to code directly to the Restlet API.  Back in 2007, it was very cool to create Plexus components that were then automatically published as REST Resources in Nexus. But today, the same thing looks very cumbersome and is not what one would call a “state of the art”. Back then, we had these goals in mind:

• have complete REST API published on Nexus
• have a decoupled UI application
• provide XML/JSON serialized transport to REST Resource without any effort, with proper content negotiation (XML was kept as “Plan B”)
• make our REST Resources as Plexus components (to enjoy all the benefits of IoC, and later pluggability)

While we fulfilled much of these goals above, we did that at a high cost.  For a Nexus core developer (or Nexus plugin developer), it is very cumbersome to create a new REST Resource using our classes, compared to what REST libraries are available today. Current state-of-the-art REST libraries make our initial implementation seem somewhat naive (hence the need to move toward new libraries like Enunciate). Our 1st and biggest mistake was a very deep class hierarchy in our current API.  While all the “defaults” are properly configured, it is often difficult to create a non-trivial Resource in the current API if you are not intimately familiar with the system.

Also, in the initial design, we use XStream with a custom driver to produce JSON. Back then, it was a real pain to produce proper JSON out of Java.   Today, we have libraries like Jackson.   In the next interation of refactoring, you’ll see update the infrastructure used to produce our REST services to bring it up to speed with what is available today.

The Benefits of “enunciating” a REST API

At first, we will use Enunciate with Nexus during build time only, to generate HTML documentation of our REST API. This documentation will be available publicly, but will also be bundled with every Nexus instance!   Our work to modify our own REST infrastructure is going to require some “invasive” work, but I have to emphasize that Enunciate is not invasive if you use it on a modern JSR311 based REST applications. Enunciate is invasive for us only, since we are about to use it on a home grown, non-JSR311 REST application.

Enunciate gathers and builds your services model using your sources and all the metadata it finds (Java5 annotations, Javadoc).  To “enunciate” the Nexus REST API, we had to add JSR311 annotations to our existing REST Resources.  There was one more problem to solve: our method signatures are more “servlet like”, and they didn’t fit the model of a JSR311 REST Application. While a JSR311 application method signature completely describes the method expectations about payload, parameters, and response type, our methods – whether GET, PUT, POST or DELETE – have almost same signature: RestRequest, RestResponse, Variant. Hence, we had to add more metainformation describing what a method does: what it expects as input, if any, and what it sends out as response.

Luckily, it turned out that this was the only piece missing, and Enunciate was happy to generate documentation for us. Ryan added the new annotation that describes the “alternate REST Signature” of the method, and Enunciate got all the information it needed to generate documentation for us.

Another painful step yet to be completed is “freeing” our REST DTOs from Modello. Initially, we knew we wanted to version the DTOs used in REST. Hence, we used Modello to generate the DTOs. Later, problems with Modello and Restlet forced us to always use version 1.0 of our REST DTOs. Since Enunciate requires that DTOs have JAXB2 annotations, we decided to store our DTOs as code and ditch Modello in our builds.

All this looks like a lot of work, but it is actually pretty straightforward.   While this might seem dull to someone not developing Nexus, this work is going to bring real value once it is completed.    In addition to solving our documentation problems, Enunciate is going to open up a world of possibilities once we migrate our REST services over to the framework.

For more information about Enunciate, the Enunciate Wiki contains a nice example of how to use Enunciate in case like ours is, without JAX-RS. Example is shown here.  Examples of Enunciate generated documentation can be seen on it’s site. There is a great walk-through, with static examples.

Expect More Changes in the Next Few Months

As Nexus graduated from alphas, betas and now is at a 1.5.0 version, we realize we have to change gears to keep up. Enunciate is the 1st “newcomer” technology to Nexus stack.  There will be more to come.   Think of this as the Nexus 100,000 mile checkup.  We’re taking a look at the stack and taking this as an opportunity to upgrade where necessary.

One last note, this post is not about any deficiencies in Restlet.  Restlet is a great framework, and it served us well.  We – the Nexus Project team – are very thankful to Restlet.org project with all the help we got from them and for the great library they made.

I get this question frequently so it is time to write down my thoughts on the answer so I can stop repeating myself. Here’s the question:

Should I put the urls to my repositories in my poms or in my settings?

The short answer is: settings.

The long answer is: it depends.

There are two scenarios to consider here. Enterprise software (generally not published externally) and public software. Lets take Enterprise software first. Continue reading this post for a full explanation of both scenarios.

Enterprise

In an Enterprise scenario, you will typically want to have a repository manager like Nexus sitting on your front lines. It will be proxying all external repositories and hosting your internal ones.

When Maven looks for an artifact, it walks down the list of repositories defined in the POMs and settings until it finds what it wants. If you define your repository manager as a repository in your POMs Maven will still fall back to the built-in Central repository when artifacts are not found in the repository manager.

One possible solution to this is to overload the “central” repository id and point this at your repository manager. This can work, but you would want to do this in your corporate pom so you don’t need to define it in every project you have. Once you’ve overloaded “central”, you have a “Catch-22″. In a clean environment, you need to know where the repository is to find the parent POM — to tell you where the repository is. You will end up having to define this repository in your settings anyway just to bootstrap.

Simply redefining Central has a few other problems. Specifically, it doesn’t redirect repositories that may be defined in other POMs you include transitively. This causes a few problems: first, it will slow down your builds as Maven goes out to all the external repositories looking for artifacts…possibly even your internal ones that would never be found there. Second, it means something may build for one developer but not another. Third, it means as an organization you have no idea where your artifacts are coming from.

As an organization, you generally will want all your developers using the same set of repositories for their builds, and make all requests via a controlled mechanism. This is best accomplished with a mirrorOf * entry in your settings to redirect all lookup requests to your repository manager. It is not possible to define a mirrorOf in a POM. See this section of the Nexus Book for examples of what a good setup will look like.

With all these things considered, you can see that defining the repositories in your poms doesn’t really help you much and generally just gets in the way.

This all presumes that your artifacts are not consumed externally. If they are, then you also fall into the next category. (They are not mutually exclusive)

Open Source Projects

If you are publishing your software and others will check it out and build it, then there are more points to consider. If all your dependencies are available in the Central repository, then you have nothing else to do. If however, you have artifacts that may exist only in your repository (think snapshots of your parent POMs), or other third party repos, then developers will have a hard time building your source. Only in this case does it make sense to add repository entries to your POMs. However, there are side effects to this that should be noted:

• The entries you have defined will be burned forever into your released POMs. This means that, should the URLs change down the road, anyone consuming your POMs will face these broken URLs and have to track down the new ones manually.
• Each of these entries will end up in your consumer’s builds since Maven needs to check them all for missing dependencies. Maven currently isn’t able to tell when you introduce a repository which dependencies are supposed to be found there (and it gets worse when you consider transitivity).

If the product of your build is a tool (like Nexus) rather than components used as dependencies, then adding the repository to the POM is fairly safe. In this case, it is unlikely others will depend on your artifacts directly in some other build, and the above concerns are nullified since presumably the new source would have the correct repository URLs.

If you are publishing jars that will be consumed by others, then you should think about getting them synced to the Central repository. This means that they will always be available to all users no matter what happens to your repository or URLs, and you won’t accidentally introduce new repositories to their builds. Central will eventually reject POMs with repository elements for this reason.

Summary

So to sum up, if you want to have repeatable builds and good control over your organization internally, use a repository manager and use a mirrorOf entry in everyone’s settings.xml to point at that url.

If you are exposing your source and want to make it easy for others to build, then consider adding a repository entry to your POM, but don’t pick a URL lightly, think long-term, and use a URL that will always be under your control. If your URL has to change down the road, make sure that you will always be able to track 404s and write the appropriate mod_rewrite rules to ensure that future builds will be able to find the appropriate artifacts.

PS. If you got here from the Jfrog blog, then I suggest you read my response.

Roberto Galoppini just published a brief interview with Mark de Visser this morning which covers Sonatype’s open documentation efforts. As someone who has been involved with Sonatype’s open book efforts along with Jason, Brian, John, Jason, Bruce, and our other contributing authors it is interesting to see the traffic and interest that is generated by something as simple as free documentation. I’ve long been a big believer that books about open source software should be as free as the software itself, and I’m also convinced that solid documentation is a necessary foundation for a vibrant open-source community. Without a good “free” book, it is nearly impossible for an open source project to grow a community. Here’s an excerpt where Mark discusses our relationship with O’Reilly, and how we’re currently trying to find ways to get our books into print format via print-on-demand.

Mark de Visser: Our publisher, O’Reilly, has been an invaluable part of the success of Maven: The Definitive Guide. When you write a book, you usually deliver a product to the production department of a publisher and that publisher prints a few thousand copies which are distributed to a network of book sellers and intermediaries. Once you deliver the manuscript, both the content and the community are out of your hands. This “dead-tree model” of publishing is as antiquated as it is impersonal, and, with the Maven book, we saw a chance to break the cycle and work with a publisher like O’Reilly who is very open to the idea of publishing a freely available book. Our editor, Mike Loukides, wasn’t hesitant at all to agree to publish a free book and talked about the success they have had with books like the Subversion book and the Asterisk book, both of which were free but generated a great deal of print sales. We will jointly evaluate options to deliver print-on-demand versions of the print books, which match closer to the dynamic nature of our constantly updated online books.

Read more of Galoppini’s Interview at his blog “Commercial Open Source Software”

Not only are we interested in pursuing less traditional avenues such as print-on-demand, we’re currently evaluating some of the more open electronic book formats such as ePub. Since our documentation is written in the DocBook XML format, there are some fairly straightforward open source projects designed to create ePub output from a standard DocBook or DITA document. Stay tuned.

Are you having problems with a particularly crazy Maven build?  Is there a part of Maven that you just don’t have a handle on, even after reading and rereading The Definitive Guide or the Apache Maven site?    We’re here to support the community, and Sonatype is serious about helping to invest in the foundational, open-source documentation that will help the community around Maven grow and evolve.    I’m biased because I focus on documentation, but I’ve always thought that good documentation makes the difference between open source projects that evolve over time and open source projects that fade into obscurity.   The docs are the interface to the community, and as widespread as Maven is, there are still people adopting the tool and learning from step 1.    If you have any requests for documentation, we’d encourage you to let us know.

1. Get Satisfaction, if you have a request for documentation let us know through our Get Satisfaction page.
2. If you have a request for a video, create an account at Vimeo and make a request via our Vimeo Profile.
3. Send a message to book@sonatype.com

We encourage you to make the request via a public channel such as Get Satisfaction or Vimeo because it will provide the best community feedback and accountability.   Get Satisfaction is an interesting customer service experiment, it isn’t merely a company-driven customer service site, it is an experiment in transparent and accountable customer-driven service.   When you ask us a question on Get Satisfaction, the questions and answers are visible to everyone.   If you have an idea for documentation, please feel free to share it with us. We’re taking requests.

Good news, O’Reilly has just completed the Second Printing of Maven: The Definitive Guide. Aside from some typos and some small updates to the test, there is not much a difference between the first edition and the second edition, and I feel confident that the core concepts of Maven and the introductory material in the book will age well over time. Whenever a publisher decides to publish a book on a fast moving topic like Maven they always ask you to justify how the content will age. Will it grow quickly irrelevant? Or, will the content remain viable for a few years?

With Maven: The Definitive Guide, I’m convinced that the core material… the lifecycle, binding plugin goals to lifecycle phases, plugins. All of these things are mature concepts which are not likely to be deprecated in future versions of Maven. While the Maven team continues to evolve with projects like Mercury and Tycho, the core of this pivotal tool remains a solid bedrock for this documentation effort. No one is going to “reinvent” the idea of the Lifecycle during the transition between Maven 2.0 and Maven 3.

If you haven’t picked up a copy yet, buy one from Amazon. I tend to find it easier to just pick up a book and read it away from the computer and away from the distractions of twitter and email. There’s also something about being able to dog-ear and highlight a physical book that cannot be replicated on a computer screen.

Thanks to all of the people who purchased a copy of the book, and thank you to all of the people who have taken the time to report issues and suggestions to our GetSatisfaction page for the book.