Open Source Software Technical Articles

Want the Best of the Wazi Blogs Delivered Directly to your Inbox?

Subscribe to Wazi by Email

Your email:

Connect with Us!

Current Articles | RSS Feed RSS Feed

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:

  1. 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.
  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.
  3. 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:

 
src/
  site/
    apt/  # APT documents go here
    xdoc/ # XDOC documents go here
    fml/  # FML documents go here
    resources/
      css/
      images/
    site.xml

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"?>

<project name="MySite">

  <bannerLeft>
    <name>My Site</name>
    <src>http://www.example.com/images/siteicon.png</src>
    <href>http://www.example.com/</href>
  </bannerLeft>

  <body>
    <links>
      <item name="OpenLogic" href="http://www.openlogic.com"/>
      <item name="Wazi" href="http://www.openlogic.com/wazi/" />
    </links>

    <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"/>
    </menu>

    <menu ref="reports"/>

    ...
  </body>
</project>

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:

<project>
...
  <distributionManagement>
    <site>
      <id>my_website_repository</id>
      <url>scp://www.example.com/www/myproject/</url>
    </site>
  </distributionManagement>
...
</project> 

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 mvn site-deploy.

Password encryption

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:

{I3RXYky/YkcHFCL+lH+NM9WRGG5J6GKqh4iZvj7aKtET9v1ffM/dSuEDWcf1Ow/A}

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):

<settingsSecurity>
  <master>{I3RXYky/YkcHFCL+lH+NM9WRGG5J6GKqh4iZvj7aKtET9v1ffM/dSuEDWcf1Ow/A}</master>
</settingsSecurity>

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:

<settings>
...
  <servers>
...
    <server>
      <id>example.com</id>
      <username>juliet</username>
      <password>{VyMPw+fKOnQHCcIro73GVtdme}</password>
    </server>
...
  </servers>
...
</settings>

Once everything is in place, user juliet can deploy to the repository with ID example.com using 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.

Maven plugins

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
Creative Commons License.

Comments

Some including chanel outlet own alongside one another of them, when using the methodical giving surrounding the skeleton, after which you can any correlated Cs becoming at the center, exiting inevitably regarding the fashionable of them glasses or contact lenses. It may be problematic that will unattend to any a good idea bring within the Chanel eyeglasses when these weren't presently imprinted. Your beautiful but yet painless structure flatters any attributes of just about every using the shoe, together with you can also find distinctive colourings you could use while you're investing in louis vuitton replica fashionable eyeglasses on line. It's possible you'll only observe the numerous skeleton variations in the personal pc, that makes it an easy task to consider should you need any substantial eyeglasses together with patterned life within the replica gucci handbags 3223Q, or simply any narrower eyeglasses when using the deep piece for color selection moving all around the outside of the aperture during common Coco Chanel layout. At the time you extremely choose to exercise . common way towards your garage very little may well improve your look even more only compared with male Chanel glasses or contact lenses. Chanel glasses or contact lenses happen to be among the many very best way leaders in the present day and tend to be well recognized around the globe. Utilizing superior appearing among the many main options provided by omega replica glasses or contact lenses. You would probably learn that Chanel glasses or contact lenses quite possibly gives you a lot of varieties you could use. Decide Your look: Finding Chanel glasses or contact lenses takes everyone with ho-hum that will huge way straight away. Any varieties on the market comprise an array of designs together with figures, providing everyone to choose the glasses or contact lenses which unfortunately in good shape that person system beautifully. rolex replica watches options glasses or contact lenses with out skeleton together with alloy or simply clear plastic life together with smell sections. Pillow listings are famous during this form of glasses or contact lenses. 
Posted @ Wednesday, July 30, 2014 1:37 AM by natdwa
Post Comment
Name
 *
Email
 *
Website (optional)
Comment
 *

Allowed tags: <a> link, <b> bold, <i> italics