The first thing to define are the general project details, user access rights, and notification methods, which are displayed in the “Basic” tab (see Figure 7-6). You will need to save this information before LuntBuild will let you proceed to the other screens.

An important part of this screen concerns user rights. In LuntBuild, you can assign different levels of access to different users for each project. There are three types of access:

You also define notification methods here. LuntBuild supports several types of notification: Email, MSN Messager, Jabber, Sametime, and Blog sites. These notification types are configured in the server configuration pages (see Configuring the LuntBuild Server): in the project screens, you simply indicate which notification methods should be used for this project.

You also indicate who must be notified. In addition to being able to specify users by name, you can also tell LuntBuild to notify users who have made recent updates to the source repository. For example, you may want to systematically notify the lead developer (specify by name), as well as any other users who have committed any recent changes: this avoids wasting time for developers who haven’t made any updates, and therefore, who shouldn’t be concerned by integration issues.

Finally, you can define project variables. Project variables can be used in ONGL expressions that can in turn be used to build the names of successive build versions. This approach can be used to build sophisticated version naming strategies (see Using Project Variables for Version Numbering).

Figure 7-6. Adding a new project

The next step involves configuring the VCS adaptors (see Figure 7-7). This is where you define where LuntBuild should look for the project source code. LuntBuild supports a wide range of VCS products, including CVS, Subversion, StarTeam, AccuRev, ClearCase, and even Visual SourceSafe. Since each VCS product has its own peculiarities, each VCS adaptor has its own specific configuration screen. The Subversion screen, for example, recognizes the Subversion convention of storing the main development trunk, separate branches, and revision tags in separate specific directories. If you are using a VCS product that does not support atomic commits, such as CVS, ClearCase, or Visual SourceSafe (just to name a few), you can also define a “quiet time.” This forces LuntBuild to wait until the VCS has been inactive for a certain period of time before it starts to check out a new version. The idea is to make sure any in-progress commits have been finished before LuntBuild starts its build.

Once you have configured the VCS adaptor, you need to define some modules. Modules let you check out different parts of the project from different areas in your source code repository. Depending on what VCS you are using, and how your source code repository is organized, this will be more or less useful. For example, if your project is stored on a dedicated Subversion repository, with no subprojects, modules will be of little use. By contrast, if you are using a Subversion repository that is shared among many projects, you will need to define a module corresponding to your project in the repository. If you are using CVS, the module will be your project directory on the repository server.

Although it is not a mandatory field, LuntBuild in fact expects you to define at least one. If you want to check out the entire project, just create a module with a dot (“.”) for the source path.

You can also define several VCS adaptors if you really need to; if different parts of your project come from different SCM repositories, for example.

Figure 7-7. VCS Adaptors

One of the distinctive features of LuntBuild is the way that it distinguishes between configuring the builds and scheduling them. The Builders page (see Figure 7-8) lets you configure one or more build scripts for a project. LuntBuild handles several different types of build scripts: Ant, Maven and Maven 2, command-line build scripts, and Rake (a build language similar to Ant for Ruby).

You should give your build a meaningful name (such as “Integration tests,” “Nightly build,” or “Maven site build”). LuntBuild lets you assign the same build to several different schedules, or several different builds may be assigned to the same schedule, so it is useful to be able to recognize your build configurations at a glance.

Configuring a build script is fairly intuitive. You need to provide the build script location, and (where appropriate) the goals or targets to be called. You can also provide build properties and environment variables, which can be used to customize the behavior of your build script.

Figure 7-8. Builders

Builders let you tell LuntBuild how to build your project; schedulers let you specify when the build scripts will be run (see Figure 7-9). By providing a clean separation of concerns, LuntBuild lets you configure modular build scripts that can be used and reused in different schedules.

Once you have provided a meaningful name and description, you define a naming strategy for the builds generated by this scheduler, using the “Next build version” field. This field displays the label of the next planned build. Each build has a unique, automatically-generated label, such as “myproject-1.14” or “library-core-1.0 (build 123).” By default, LuntBuild will simply increment the last number in the expression: “myproject-1.14” will become “myproject-1.15,” and “library-core-1.0 (build 123)” will become “library-core-1.0 (build 124).” If you need a more sophisticated naming strategy, you can use project variables and OGNL expressions to build the version label programmatically (see Using Project Variables for Version Numbering).

The “Trigger Type” field lets you specify when and how a build is to be scheduled. You can schedule a build in one of three ways. “Manual” builds must be triggered by hand. “Simple” builds are run at regular intervals. And “cron” builds use a cron expression to determine when they should be run. LuntBuild does not support the polling approach.

By default, builds will be run only if an update is detected in the VCS. A build will also run if another build on which it depends has been rebuilt. This behavior suits most circumstances well. If it doesn’t suit yours, you can use the “Build necessary condition” field to modify or fine-tune this behavior. Typical alternatives are “always” (always run the build), “never” (ignore this build), or “alwaysIfFailed” (keep trying to rebuild after a build has failed, even if there are no updates in the VCS).

LuntBuild is a flexible tool, and you can assign builds to a scheduler in several ways. The most common is to use the “Associated builders” field: The builders listed here will be executed in turn whenever this scheduler is run. You can also define “postbuilders,” which will be run after the main builds, if certain conditions are met. A typical use of a postbuild would be to deploy an application to a test server if and only if the nightly build succeeded.

LuntBuild also lets you configure a number of other scheduling options. You can configure builds to be clean (working directories are deleted and the whole project is rebuilt) or incremental. New labels may be generated after every build, or only if the build succeeds. The “Notify Strategy” lets you decide when notification messages should be sent: always, only if the build fails, whenever the build status changes (i.e., one message when a build breaks, then another when it is fixed), and so on.

You can also define dependencies between schedules. Suppose that your project depends on other libraries or components, which are also handled in LuntBuild. You may want to add dependencies to these projects so that any rebuilds in these dependent projects will automatically trigger a build in your project.

Figure 7-9. Schedules

As a rule, it is better if your LuntBuild logins correspond to your VCS account names. This allows LuntBuild to know automatically who has made modifications in the source code repository, and send notifications as appropriate.

However, there are times when this is just not practical. Your VCS accounts may be a strange combination of letters and numbers that only a systems administrator can understand (yes, I’ve seen it done), and you may prefer more user-friendly logins for your LuntBuild system. This is where the Login Mapping screen (see Figure 7-10) comes in handy. This screen lets you map VCS logins to your LuntBuild user names. So, you can keep your user-friendly LuntBuild logins, and LuntBuild will still manage to notify the right users when changes are made in the repository.

Figure 7-10. Login Mappings

Luntbuild comes out-of-the-box with Junit integration; if your project build runs any JUnit tests, the build view will provide a convenient link to the corresponding JUnit reports. Test coverage reports (Chapter 12) can complement these unit test results nicely. Code coverage reports let you investigate how much of your code is actually being tested by your unit tests, and can be an excellent means of improving the quality of your unit tests. There are several code coverage tools available, both open source and commercial. One of the best open source code coverage tools is Cobertura (see Chapter 9). In this section, we will discuss how to produce and display Cobertura code coverage reports directly from within your Luntbuild build results, right alongside the standard unit test reports. We will also see how to extend Luntbuild functionalities using JavaBeans and Luntbuild extension points.

You can extend Luntbuild functionalities fairly easily using simple JavaBean classes. You encapsulate your new functionalities in a standard JavaBean class. You can access your bean from within Luntbuild using OGNL expressions. However, you need to give this file to Luntbuild in a form that it can cope with. Each Luntbuild extension is presented in the form of a JAR file containing the relevant classes along with a special properties file that tells Luntbuild how to integrate this extension. You bundle your bean, and any other classes it needs, into a JAR file containing the special property file named “luntbuild_extension.properties.” This file must contain two property values:

Once you have bundled all this into a JAR file, you have your brand new Luntbuild extension! Note that you can only create one extension per JAR file.

So creating a Luntbuild extension is quite an easy task. Now let’s have a look at the bean we will be using to integrate Cobertura reports into LuntBuild. This JavaBean will basically tell Luntbuild where it can find the coverage report generated by Cobertura:

package com.javapowertools.luntbuild.addon;

import java.io.File;

public class CoberturaIntegration {
  private final String coberturaReportDir = "cobertura_report_dir";

  public String getCoberturaReportDir(String publishDir) {
    return publishDir + "\\" + coberturaReportDir;
  }

  public String getCoberturaReportDir() {
    return coberturaReportDir;
  }

  public String getCoberturaSite(String publishDir) {
    File pathToFile = (new File(getCoberturaReportDir(publishDir)+ 
    File.separator + "index.html"));
    if(pathToFile.exists()) {
      return coberturaReportDir + "/index.html";
    } else {
      return null;
    }
  }
}

The methods are pretty straightforward; the harder part is when to use which method. By providing the directory where all reports should be copied, the getCoberturaReportDir() method returns the exact path where to copy the Cobertura reports to. The other method, getCoberturaSite(), points to the path used by the Luntbuild web server to find the start page for all the Cobertura reports.

Now let’s create the “luntbuild_extension.properties” file. This file must contain the following two lines:

luntbuild.extension.name=CoberturaIntegration
luntbuild.extension.class=com.javapowertools.luntbuild.addon.CoberturaIntegration

Now create a jar, with the bean and the property file. Luntbuild expects extension jars to be placed in the $LUNTBUILD_HOME/web/WEB-INF/lib directory. Copy your jar here and restart Luntbuild. Luntbuild will now be able to detect and use this extension. In the next section, we discuss how to use the new plug-in.

The next step is to integrate the extension into the build process. In our case, we need to use this extension in the builder configuration screen of a project, and in the BuildView.html page which actually displays the build reports. You can however, use this bean in any OGNL expression throughout Luntbuild.

Luntbuild needs to know into which directory the Cobertura reports needs to be copied. You need to expose this information in the parameter coberturaHtmlReportDir. Have a look at the following image that shows the ant builder configuration (see Figure 7-19).

Figure 7-19. Ant builder configuration within the Luntbuild project wizard

Note the value for the coberturaHtmlReportDir. This OGNL expression uses the current build object. This object has a system member variable, which you use to access the Luntbuild extensions. Here, we obtain the reference to the CoberturaIntegration object, using the name that is defined in the luntbuild_extension.properties file. From there on, we can just manipulate methods of our bean. The next section will show you what you can do with this parameter from ant. Now let’s have a look at the BuildViewer.html file that can be found in the WEB-INF folder.

The views use Tapestry. I am not giving you an introduction into Tapestry because you do not need it for this adjustment. Actually you can copy part of the junit example in this file. However, you need to know how to write the ognl expression. Search for this piece of code:

<td width="10%" align="center" class="buildTitleRight">
  <span jwcid="@Conditional" condition="ognl:junitHtmlReport!=null">
    <span jwcid="@GenericLink" href="ognl:'publish/'+build.schedule.project.name+'/'+
      build.schedule.name+'/'+build.version+ '/'+junitHtmlReport" 
      title="junit report">junit report</span>
  </span>
</td>

Now add the following lines between the first “td” tag and the first “span”:

<span jwcid="@Conditional" 
    condition="ognl:build.system.getExtension('CoberturaIntegration')
    .getCoberturaSite(build.publishDir)!=null">
  <span jwcid="@GenericLink" 
    href="ognl:'publish/'+build.schedule.project.name+'/'+build.schedule.name+'/'
      +build.version+ '/'+build.system.getExtension('CoberturaIntegration').
      getCoberturaSite(build.publishDir)" title="maven site">cobertura report</span>
</span>

The construction of the path to the report resembles the method within the Luntbuild configuration screen. The second span that creates the href uses some other exposed properties to create the complete link. All these parameters are accessed through the BuildView object that contains a getBuild() method. From there on, you can find all the other objects as well. We have to use the ognl extension point as discussed before. Have a look at the following image (see Figure 7-20) to get the feeling how this all looks in a browser.

Figure 7-20. Build results screen showing the link to the Cobertura reports in the red box

Clicking the link will show you the Cobertura screen (see Figure 7-21).

Figure 7-21. The sample Cobertura code coverage report

Until now, we did not show how to configure ant in order to create the Cobertura report. There are some steps to perform. This section will give you the different steps.

First, obtain the directories where to copy the junit and the Cobertura reports:

<property name="testdata"  location="${junitHtmlReportDir}"/>
<property name="coveragedata"  location="${coberturaHtmlReportDir}"/>

Then we must make Cobertura available to Ant:

<property name="cobertura.dir" value="D:/java/cobertura/cobertura-1.8"/>
<path id="cobertura.classpath">
    <fileset dir="${cobertura.dir}">
        <include name="cobertura.jar" />
        <include name="lib/**/*.jar" />
    </fileset>
</path>
<taskdef classpathref="cobertura.classpath" resource="tasks.properties" />

The next step is to instrument or post compile the classes. Cobertura adjusts the classes in a way that it can track which lines are called. This way it can calculate the code coverage and show you the nice reports. The instrumentation is shown in the next target:

<target name="cobertura.instrument" depends="compile"
    description="Create the isntrumented classes used by cobertura">
  <cobertura-instrument todir="${build.instrumented}">
    <ignore regex="org.apache.log4j.*" />
    <fileset dir="${build}">
      <include name="**/*.class" />
    </fileset>
  </cobertura-instrument>
</target>

Now we need to put the instrumented classes in front of the other classes while executing the junit test. This is done in the following part of the junit task. We also must tell junit where to find the Cobertura data file. This is done with a system property.

<target name="test" depends="compile,cobertura.instrument" 
description="Runs JUnit tests">
  <junit printsummary="yes" fork="true" errorProperty="test.failed" 
   failureProperty="test.failed">
    <sysproperty key="net.sourceforge.cobertura.datafile" 
     file="${basedir}/cobertura.ser" />
    <classpath>

      <path location="${build.instrumented}"/>
      <path location="${build}"/>
      <path location="${buildtest}"/>
      <path location="lib/easymock-1.2_Java1.3.jar"/>
    </classpath>
    <classpath refid="cobertura.classpath" />
    <formatter type="xml"/>
    <batchtest todir="${testdata}">
      <fileset dir="${test}">
        <include name="**/*Test.java"/>
      </fileset>
    </batchtest>
  </junit>
  <fail if="test.failed">Unit tests failed.</fail>
</target>

Finally, you want to create the reports based on the gathered data. This is done with the following target:

<target name="cobertura.report" depends="clean,test">
  <cobertura-report format="html" datafile="${basedir}/cobertura.ser"
    destdir="${coveragedata}" srcdir="${src}"/>
</target>

Now you are done. You can do the complete build, junit, and Cobertura reports by issuing the following command:

ant cobertura.report

Before doing this you need the complete Ant file, including the following targets: init, compile, dist, clean, and some extra properties. These are all presented in the following code listing:

<property name="src" location="src/main/java"/>
<property name="build" location="build"/>
<property name="proplocation" location="src/main/resources"/>
<property name="dist"  location="dist"/>
<property name="test"  location="src/test/java"/>
<property name="testdata"  location="${junitHtmlReportDir}"/>
<property name="coveragedata"  location="${coberturaHtmlReportDir}"/>
<property name="buildtest" location="buildtest"/>
<property name="build.instrumented" location="instrumented"/>

<target name="init">
  <tstamp/>
  <mkdir dir="${build}"/>
  <mkdir dir="${buildtest}"/>
  <mkdir dir="${testdata}"/>
  <mkdir dir="${build.instrumented}"/>
</target>

<target name="compile" depends="init" description="compile the source " >
  <javac srcdir="${src}" destdir="${build}" debug="true"/>
  <javac srcdir="${test}" destdir="${buildtest}">
    <classpath>
      <path location="${build}"/>
      <path location="lib/easymock-1.2_Java1.3.jar"/>
    </classpath>
  </javac>
</target>

<target name="dist" depends="compile" description="generate the distribution" >
  <mkdir dir="${dist}/lib"/>
  <copydir dest="${build}" src="${proplocation}"/>
  <jar jarfile="${dist}/lib/JavaPowerToolsSample-${DSTAMP}.jar" basedir="${build}"/>
</target>

<target name="clean" description="clean up" >
  <delete dir="${build}"/>
  <delete dir="${buildtest}"/>
  <delete dir="${dist}"/>
  <delete dir="${testdata}"/>
  <delete dir="${coveragedata}"/>
  <delete dir="${build.instrumented}"/>
  <delete file="cobertura.ser" />
</target>

Continuous Integration servers do a good job at, well, continuously building (and integrating) code. Another useful thing that you may want to do is to automatically generate and publish up-to-date project reports about different aspects of the project, such as javadoc, unit test reports, code coverage reports, and so on. You can use both Ant and Maven, both of which integrate well with Luntbuild (see Builders) to generate this type of report.

You can also use Luntbuild to publish these reports for each build, which allows you to automatically generate and publish updated reports on a regular basis, and also to keep track of the reports generated for previous builds. In this section, we will see how to generate and publish a Maven-generated web site, which contains a wide range of quite useful reports. First, we write a Maven Mojo (plug-in class) that enables us to copy the generated Maven web site to the appropriate folder for Luntbuild to pick it up. Then we look at how to add the new Mojo to Maven. Finally, we configure Luntbuild to use our new Mojo to display the Maven web site on the Luntbuild build results pages.

The Maven core is actually very small: Maven uses plug-ins, or extensions, to implement most of the heavy-duty functionality. In Maven parlance, these plug-ins are called Mojos, and take the form of annotated Java classes.

Writing your Mojo in Java is a big advantage. This way, you can use the programming language you are used to. You can use the tools you are used to and, of course, do junit testing. Reuse of the Mojo over the different projects that you are into is also easy.

It is actually quite easy to build your own. In this section, we will go through the steps required to build a simple Mojo plug-in, which will publish your LuntBuild build results on your Maven web site. This Mojo will simply copy the build results from the LuntBuild web site to a designated directory on your Maven site.

Setting up your project

First, you need to set up a project for your Mojo plug-in. Maven provides a convenient plug-in called maven archetype that helps you set up a standard project directory structure (http://maven.apache.org/plugins/maven-archetype-plugin). There are multiple archetypes available, including web projects, standard Java projects, and Maven Mojos. Use the following command to set up your environment:

mvn archetype:create 
      -DgroupId=com.javapowertools.mojo 
      -DartifactId=maven-copy-site-plugin 
      -DarchetypeArtifactId=maven-archetype-mojo

Figure 7-22. Directory structure after using the special maven archetype plug-in

The directory contains the pom.xml file in the root of the folder and a sample mojo in the Mojo directory.

/**
 * @author Jettro Coenradie
 * 
 * @goal copydirectory
 * 
 * @description Copies the provided directory to the other provided directory 
 */
public class CopyFolderMojo extends AbstractMojo {

   public void execute() throws MojoExecutionException, MojoFailureException {

   }
}

/**
 * Location of the directory to copy from.
 * @parameter expression="${project.build.directory}"
 * @required
 */
private File inputDirectory;

/**
 * Location of the directory to copy to.
 * @parameter expression="${project.copyto.directory}"
 * @required
 */
private File outputDirectory;
    
/**
 * Name of the current project
 * @parameter expression="${project.name}"
 * @required
 */
private String projectName;

public void execute() throws MojoExecutionException, MojoFailureException {
  getLog().info("Input directory : "+inputDirectory.toString()+"\site");
  getLog().info("Output directory : "+outputDirectory.toString());
  File in = new File(inputDirectory,"site");
  if (!in.exists()) {
    getLog().info("No site available to be copied");
    return;
  }
  File out = new File(outputDirectory,projectName);
  if (!out.exists()) {
    out.mkdirs();
  }
  in.renameTo(new File(out,in.getName()));
}

Integrating the Mojo with Maven

Now that we have created the Mojo, it is time to package and install our new Mojo to the maven repository. We do this by issuing the command “mvn install.” This places the plug-in into our repository so we can use it in other projects.

You can invoke the new Mojo from the command line as follows:

mvn com.javapowertools.mojo:maven-copy-site-plugin:1.0-SNAPSHOT:copydirectory

This should result in an error like the one in Figure 7-23, telling us that we are missing a required parameter outputDirectory:

Figure 7-23. Shows the error indicating we are missing the parameter outputDirectory and a possible solution

In order to make it work, we provide the java environment variable like this:

mvn -Dproject.copyto.directory=D:/temp/output 
       com.javapowertools.mojo:maven-copy-site-plugin:1.0-SNAPSHOT:copydirectory

This should get rid of the error, although the logfiles will tell you that there is no site available. That is OK for now. Move on to the Luntbuild configuration.

Now that it is written, integrating this plug-in into Luntbuild is relatively easy, and is done in the build configuration page. Have a look at Figure 7-24.

Figure 7-24. The Builder tab of the project configuration in Luntbuild shows how to configure Maven as a builder

There are two things that you need to configure:

We’ll let the build run from Luntbuild, it should be running fine. Then have a look at the results of the build in Figure 7-25, and you see an additional artifact called “Java Powertools Sample application—The Calculator.” Click on the link and you can browse the uploaded reports. After the first artifacts link, click the link site and then index.html.

Figure 7-25. The build results view, where the red box shows you the uploaded artifact created with Maven and copied with the new plug-in

Figure 7-26. Displaying the Maven site from within the Luntbuild build page

Now you can browse an automatically generated, up-to-date version of the Maven project site for each build of your project (see Figure 7-26).