Making the most of Maven
In a previous tutorial I talked about how to get started with Maven, the Java build automation and dependency management tool. If you've read that article and feel you have the Maven basics covered, you can start doing a lot more to streamline and tweak your build system.
Creating a project website
Maven makes it easy to create a website about your project, with documentation and reports based on the project build setup, and anything else you care to add manually – a quick description of the project, for example, or a contributor list, HOWTO, or FAQ. You can use three different formats for writing the documents that will appear on the Maven-generated site:
- Xdoc (file.xml), a sample of which is available with the Maven docs. Xdoc was the main doc format in Maven 1, and is still supported in Maven 2.
- APT (file.apt), a wiki-like near-plain-text format, whose full reference is available online. This is now the main doc format for Maven.
- FML/FAQ format (file.fml), a format for creating FAQ-type documents quickly and easily. The full reference is online.
Other formats are also available, but these are the best-tested. Maven's site-building plugin expects you to arrange your site documentation in a tree like this:
apt/ # APT documents go here
xdoc/ # XDOC documents go here
fml/ # FML documents go here
site.xml is the most important document. It describes the basic site layout, a bit like this:
<?xml version="1.0" encoding="ISO-8859-1"?>
<item name="OpenLogic" href="http://www.openlogic.com"/>
<item name="Wazi" href="http://www.openlogic.com/wazi/" />
<menu name="Site Navigation">
<item name="Home" href="index.html"/>
<item name="About This Site" href="about.html"/>
<item name="Best Articles" href="bestof.html"/>
The XML here should be fairly self-explanatory, though you can check out the Xdoc reference link above for more detail.
Notice the "reports" menu link, which enables you to add Maven-generated reports to your site to show the current project status. You can use the Project Info Reports plugin for this. You'll also need to create a
<reporting> section in the POM.
When you run the command
mvn site, Maven will merge the Xdoc, APT, and FML directories to form the root directory of the site, and will make the contents of the resources directory available in the appropriate places in your generated site, depending on whether they're CSS or image files. After you run the command you should see the site in the target/site/... directory. (Your target directory will already be specified in your basic Maven project setup.)
If you wish to deploy the site to your web server, rather than just building and accessing it locally, you'll also need to add a section like this to the pom.xml file:
Deployment over SSH (via SCP) is the only supported option, so you need to make sure your SSH keys are set up appropriately or provide them when required. my_website_repository identifies a specific repository, allowing you to set up credentials via the
<servers> element in settings.xml. Check out the section below on password encryption for instructions on how to store your SSH password securely.
To deploy the site, run the command
When you set up a website, you need to present authorization credentials. As of version 2.1.0, Maven supports server password encryption. This feature is useful when every developer uses the same server and the same settings.xml file, but only some users have particular privileges. This is often the case among development staffs, where deployment capabilities may be limited, but the same approach can be used for any server operations that require authorization.
The first job is to create a master password:
mvn --encrypt-master-password mystrongpassword
mystrongpassword is in plaintext; there's no option to prompt for a password. You'll probably want to edit your command history afterward to remove this line. The command will spit out an encrypted version of the password, like:
Create a file .m2/settings-security.xml in the authorized user's home directory, and add the following directives to it (note that encrypted password; just paste it in there):
If there are any braces other than the ones at the start and end of the encrypted password, escape them with \ in front of them or Maven will think that the rest of the password is a comment.
Next, get each individual to encrypt her own password:
mvn --encrypt-password myindividualpassword
In settings.xml on the server, add a section like this for each authorized user:
Once everything is in place, user
juliet can deploy to the repository with ID
mvn deploy:deploy-file. You can also use this technique to deploy a whole Maven-generated project website to a web server.
For increased security you can copy the master password to a removable device and use the
<relocation> directive instead of
<master> in the user's settings-security.xml to point to a settings-security.xml file on the removable drive.
You can use exactly the same process, but with your own local settings.xml, if you need to talk to a remote server that wants a password, as described by Tim O'Brien.
Any time you have a plaintext password in settings.xml, consider using this method to encrypt it.
Build debugging with dependency trees
Possibly the most important and useful feature of Maven is its dependency management, but sometimes the fact that Maven is doing all of that for you under the hood can become problematic. For example, if you have more than one version of a particular JAR kicking around, and one of the versions is broken, it can be difficult to diagnose the problem. You need to track down the dependency that Maven is using and either replace it or otherwise prevent it from being used.
Happily, Maven makes it easy to locate all of your dependencies. Run the command
mvn dependency:tree in a project directory to see all of the dependencies that Maven is importing for you. So, for example, if the library foo.jar is importing bar-1.1.jar, and you are elsewhere using bar-1.2.jar and getting problems thereby, this command enables you to spot the problem and do something about it.
Finally, remember that Maven is fundamentally a plugin-based system. It can use a great many contributed plugins to do nearly anything you can think of. (For example, use maven-jar-plugin to create an executable JAR.) You can also create your own plugins with relative ease (check out the Maven Plugin Developers Centre for info) – but before you go off reinventing wheels, check for something that you can use off-the-shelf. Maven is, after all, intended to make your life easier!
This work is licensed under a Creative Commons Attribution 3.0 Unported License