Section 6.10. Writing a Plug-in That Generates Reports | Maven: A Developers Notebook (Developers Notebooks)

6.10. Writing a Plug-in That Generates Reports

Throughout this book you have used several Maven plug-ins that generate reports when you type maven site (Checkstyle, Dashboard, JUnit, etc.). Wouldn't it be nice if you could add your own report type that users of your plug-in could add to their reports section in the POM? In this lab you'll add a report that displays the logs generated by the Logging Aspect of your Logifier plug-in.

6.10.1. How do I do that?

Any plug-in can generate a report. All you need to do is define three goals in your plug-in's plugin.jelly file. Assuming you want to name the report maven-logifier-plugin, these goals are:

maven-logifier-plugin:register
maven-logifier-plugin:deregister
maven-logifier-plugin:report

Have a look at how to implement the maven-logifier-plugin:register goal:

<?xml version="1.0"?>    <project     xmlns:j="jelly:core"     xmlns:ant="jelly:ant"     xmlns:maven="jelly:maven"     xmlns:doc="doc"> [...]    <goal name="maven-logifier-plugin:register">     <doc:registerReport          name="Logifier"         pluginName="maven-logifier-plugin"         description=             "Report showing all debugging logs generated by the Logging                 Aspect" link="logifier-report"/>   </goal>

You need to understand how the maven-logifier-plugin:register goal fits in the report generation lifecycle. It is called by the XDoc plug-in when the user types maven site (as you'll recall, the XDoc plug-in is used by the Site plug-in). The XDoc plug-in gets the list of reports defined in the reports section of the POM (as seen in Section 1.1) and calls the [report name]:register goal for each report found. Inside this goal you need to use the doc:registerReport tag provided by the XDoc plug-in to register your report. This registration provides information to the XDoc plug-in so that it can generate a menu entry for each report in the navigation menu. A typical reports section of the navigation menu is shown in Figure 6-6.

Figure 6-6. reports section showing all registered reports

The attributes for doc:registerReport provide the following information:

name: The name that appears in the navigation menu in Figure 6-6.
pluginName: The internal plug-in name that the XDoc plug-in uses to store your registration information. You can use any name you want. However, as you'll see later on, this name will be used by the Site plug-in to compute the goal to call for generating the report.
description: The report descriptions that appears in Figure 6-6 in the table of the Overview section.
link: The report file name that is called when the user clicks the report link, excluding the HTML extension.

The maven-logifier-plugin:deregister goal is even simpler:

  <goal name="maven-logifier-plugin:deregister">     <doc:deregisterReport name="maven-logifier-plugin"/>   </goal>

In practice this goal is not called by the Site plug-in. A Maven project using your plug-in would call it if it wanted to remove your report from the list of registered reports.

The last goal to implement is maven-logifier-plugin:report. This goal is called automatically by the Site plug-in when it generates the web site. It computes the goal name by getting the pluginName attribute that you used in the doc:registerReport tag, using the [pluginName]:report formula.

You want your report to integrate with the look-and-feel of the Maven web site, so you're going to generate a report in the standard XDoc format (see Section 2.1) used for project documentation. Before you can do that, you need to output Logifier's debug logs in XML so that they can be easily transformed to the XDoc format using the Jelly Scripting Language (JSL).

Modifying the Logging.aj Aspect to output an XML file instead of System.out logs is outside the scope of this lab. If you are interested in seeing how the Logifier has been altered to output XML, check the source code at http://www.mavenbook.org for more information. For the purposes of this lab, all you need to know is the format of the logging output generated by the modified Logging.aj Aspect:

<logs>   <log type="entry" call="name of method called and parameters"/>   <log type="exit" call="name of method called" time="method response time"        return="return value (only if there is one)"/>   [...] </logs>

It's time to learn how to use JSL.

6.10.2. What just happened?

You are slowly transforming the first version of the Logifier to support report generation using the workflow defined in Figure 6-7.

Figure 6-7. The new Logifier's workflow for producing an HTML report

The process in the new Logifier is defined as follows:

The user executes the site goal to generate the project's web site after having added the maven-logifier-plugin report to the reports section of its POM.
The Site plug-in calls the maven-logifier-plugin:report goal, which in turn calls the logifier:logify goal. The first action of this goal is to apply the Logging Aspect on the project's Java .class files.
The Logging Aspect generates "logified" .class files.
The logifier:logify goal calls the jar goal which automatically executes the test:test goal, executing the Java unit tests on the "logified" classes.
As the "logified" classes are instrumented, they generate XML logs to be used in the subsequent report generation.
The maven-logifier-plugin goal now performs a JSL transformation on the XML log, which generates an XDoc file.
The Site plug-in transforms all the XDoc .xml files that have been generated by all registered reports into HTML (using Maven's CSS).

You have reached step 5 so far: the Logifier has gone from a plug-in that applies an Aspect, to a plug-in with a dynamic dependency, to a plug-in which generates an XML file used in the creation of a report. This is no longer just a simple plug-in. You are learning how to create some of the most advanced plug-ins available. And you thought this was going to be a simple introduction to Maven. While this book is a simple introduction to Maven, you should be convinced by now that Maven plug-ins are accessible and easy to create.

The next lab will take you through the process of transforming an XML file to XDoc via JSL, an XSLT-like language with the ability to reuse Jelly and Ant tags.