Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

Get the most out of Maven 2 site generation

Steps for creating a Maven-based Website

By John Ferguson Smart, JavaWorld.com, 02/27/06

Team communication is an essential part of any project. And wasting time looking for technical project information can be costly and frustrating. Clearly, any IT project will benefit from having its own dedicated technical Website.

That's where the Maven site generator steps in. With little effort, you can have a professional-quality, low maintenance project Website up and running in no time. Maven lets you generate a one-stop center of information about your project, including:

• General project information such as source repositories, defect tracking, and team members
• Unit test and test coverage reports
• Automatic code reviews with Checkstyle and PMD
• Configuration and versioning information
• Dependencies
• Javadocs
• Source code in indexed and cross-referenced HTML format
• And much more

Maven sites are frequently used on open source projects (see Resources for some examples). A typical project site contains information about the project, largely derived from the pom.xml file, some generated reports (unit tests, Javadocs, Checkstyle code audits, etc.), as well as some project-specific content matter.

In this article, we will walk though what you need to know to get a Maven site up and running in minimal time. Note: The source code used in this tutorial can be downloaded from Resources.

Iteration 1: The project information section

Your Maven site will be one of the first places a newcomer will look to get to know your project, and the project information page is the place they will expect to find a summary of your project's organization. This part of the Website is built entirely using information found in the pom.xml file. The default pom.xml file created will look something like this:

 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v400.xsd>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.javaworld.hotels</groupId>
  <artifactId>HotelWeb</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start Archetype</name>
  <url>http://maven.apache.org</url>


  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project> 

Now you will want to add some details about your project. All zones are optional, but you should put as much information as is relevant to your project. The following sections discuss some useful items to add.

Project name and description

Add an appropriate project name, a description, and the project site URL. This appears on your project's homepage, so don't be stingy:

  ...
   <name>Hotel Database tutorial application</name>
   <url>http://your.project.url</url>
   <description>Write a few paragraphs to say what your project is about.</description>

Issue tracking

Now put the name and URL of your project's issue management system (Bugzilla, Jira, Scarab, or your own favorite issue tracking system), using the issueManagement tag:

  ...
   <issueManagement>
      <system>Bugzilla</system>
      <url>https://bugzilla.wakaleo.com/</url>
   </issueManagement>       

Continuous integration

If your project uses a continuous integration tool of some sort, such as CruiseControl or Continuum, you can provide details in the ciManagement tag, as shown in the code below. (If you are not, consider using one!) Maven 2 integrates well with Continuum: you can install a Maven 2 project onto a Continuum server just by providing the pom.xml file.

  ...
   <ciManagement>
      <system>Continuum</system>
      <url>http://integrationserver.wakaleo.com/continuum</url>
      <notifiers>
         <notifier>
            <type>mail</type>
            <address>duke@wakaleo.com</address>
         </notifier>
      </notifiers>
   </ciManagement>

The project team

People like to know who they are working with, especially these days, when a project team can be spread across organizations and continents. In the developers section, list team member details. The timezone field is useful for international teams; this field is offset from Greenwich Mean Time (GMT), or London time, and lets people see what time it is wherever the team member is located. For example, -5 is for New York time, +1 for Paris, and +10 for Sydney.

  ...
   <developers>
      <developer>
         <id>duke</id>
         <name>Duke Java</name>
         <email>duke@wakaleo.com</email>
         <roles>
            <role>Project Manager</role>
            <role>Architect</role>
         </roles>
         <organization>Acme.com</organization>
         <timezone>-5</timezone>
       </developer>         
   </developers>

Mailing lists

If your project uses mailing lists, describe them in the mailingLists page. A typical mailing list configuration might look like this:

  ...
   <mailingLists>
     <mailingList>
       <name>HotelDatabase project mailing list</name>
       <subscribe>dev-subscribe@wakaleo.com</subscribe>
       <unsubscribe>dev-unsubscribe@wakaleo.com</unsubscribe>
      <post>dev@wakaleo.com</post>
      <archive>http://mail-archives.wakaleo.com/modmbox/dev/</archive>
     </mailingList>
   </mailingLists>

The source repository

Another vital part of any project is the source repository. The scm tag lets you document the configuration of your source repository, both for the Maven Website and for use by other plug-ins. If you are using CVS or Subversion, the source repository page will also give detailed, tool-dependent instructions on how to use the repository. Here is an example of a typical SCM (software configuration management) configuration:

  ...
   <scm>
      <connection>scm:svn:http://svn.wakaleo.com/hoteldatabase/</connection>
      <developerConnection>scm:svn:http://svn.wakaleo.com/hoteldatabase/</developerConnection>
      <url>http://svn.wakaleo.com/viewcvs.cgi/hoteldatabase/</url>
   </scm> 

Now you can try out your new Maven site! The command to generate the Maven site is: mvn site.

Your site will be generated in target/site. Take a look at the project information link; you should find everything you just entered and more (see Figure 1)!

Iteration 2: Add reports

Maven also provides an extensive range of plug-ins for automatic report generation. Report generation in Maven 2 is easy: you just add the report plug-ins you need into the reporting section at the end of the pom.xml file.