Maven: A Developer's Notebook

Generating a Quality Dashboard

You've seen how to generate some quality reports, such as a testing report, a test coverage report, a best practice violations report, and duplicate code reports. There are actually lots of other Maven reports related to quality (for instance, JavaNCSS, JDepend, and JCoverage, to name a few). Having all those reports generated is great, but it's a bit difficult to get a clear picture of the overall quality of a project. In addition, all these plug-ins generate reports for single projects and not multiprojects. How do you get aggregated quality reports that span a complete multiproject?

How do I do that?

In the previous labs you added reports to the qotd/core subproject. Now you'll use the Maven Dashboard plug-in to provide quality visibility to the full QOTD multiproject.

Add the maven-dashboard-plugin report to the reports section in your master project's POM. For the QOTD multiproject this is the qotd/project.xml file. Now tell the Dashboard plug-in what subprojects to include in the report. By default the Dashboard plug-in uses the values from the following three multiproject properties, seen in Chapter 3 and shown here with their default values:

maven.multiproject.basedir = ${basedir}
maven.multiproject.includes = */project.xml
maven.multiproject.excludes =

In the case of the QOTD multiproject, these default values are fine because all the subprojects are matching the */project.xml pattern.

The Dashboard plug-in introduces the notion of aggregators. An aggregator represents a metric. More than 25 aggregators are available. Here are some examples:

cserrors

Computes the total number of Checkstyle errors

clovertpc

Computes the total Test Coverage Percentage (TPC) using Clover

simiantdl

Computes the total number of duplicate lines found by Simian

javancssncsstotal

Computes the total number of noncommented source statements as computed by JavaNCSS

The aggregators to display in the Dashboard report are controlled by the maven.dashboard.aggregators property. The default aggregators included in the report are:

maven.dashboard.aggregators = cserrors,cswarnings,clovertpc,cloverloc,cloverncloc

Running maven site on the master project in qotd/ generates the report in Figure 4-9.

Figure 4-9. Dashboard report for the QOTD multiproject

By default the Dashboard plug-in executes the necessary goals to generate the reports that the aggregators are relying on (Checkstyle, Clover, etc.) before extracting the metrics and aggregating them in the master project's report, as shown in Figure 4-9. That makes it very easy to run the Dashboard plug-in, but it's not always the most efficient way. If the subprojects already generate some of the individual reports aggregated by the Dashboard, these reports will be executed several times, wasting some precious build time.

Fortunately, the Dashboard plug-in supports a mode that integrates well with the multiproject:site goal and lets each subproject generate its individual reports. Start by asking the Dashboard report not to generate the individual reports itself, by adding the following properties to your qotd/project.properties file:

maven.dashboard.runreactor = false
maven.dashboard.rungoals = false

Now tell the Multiproject plug-in to call the dashboard:report-single goal for each subproject. You do this by setting the maven.multiproject.site.goals property in qotd/project.properties:

maven.multiproject.site.goals = site,dashboard:report-single

The dashboard:report-single goal creates a ${maven.build.dir}/dashboard-single.xml file in each subproject, containing the aggregator metrics. The Dashboard plug-in gathers all the individual dashboard-single.xml files to produce the master report for all subprojects.

For this to work, you'll of course need to ensure that each subproject has the correct reports defined in the reports section of their POMs. The Dashboard report will now be generated when you run maven multiproject:site.

What just happened?

You have discovered how to use some Maven plug-ins that will improve your intrinsic code quality. You have also discovered how to report the violations found. However, very often, simply reporting is not enough, and failing the build in case of violation should be preferred. In the next lab we'll discuss how to provide visibility about project activity.

What about...

...drawing history graphs?

You're right, that would be fabulous, but the Dashboard plug-in doesn't support this yet. Actually, the Dashboard plug-in has probably grown to the point where it should be made a separate, Maven-independent project. It could be similar to Checkstyle, PMD, Clover, and other similar projects. Then you could refactor the Dashboard plug-in to use this external Dashboard project.

Tip

Best practice: don't write too much code that isn't purely build-related in maven.xml or Maven plug-ins. If you find yourself doing this, consider externalizing the non-build-related code in a separate Java project, and refactor your Jelly code to use it instead.

Note

Don't be a report maniac! Prefer quality checks that fail the build over nice reports that nobody pays attention to....