Writing a report plugin is very similar to writing any other Mojo Plugin (see e.g. "Better Builds with Maven", Chapter 5 for an introduction into that). The most significant difference is that you do extend the
AbstractMavenReport class rather than the
You need to implement your Mojo as AbstractMavenReport, then you can simply add it to the <plugin> section within the <reporting><plugins> section of your POM and your report will be generated and linked into the Maven site automagically:
and so on.
@phase site binds your plugin to the site lifecycle of the build. You need to implement or override the following methods:
public void executeReport(Locale defaultLocale) throws MavenReportException- This method is called during site phase to actually produce your report.
- Other methods:
For the use of getBundle() you need to provide a resource bundle in
src/main/resources/my-report.propertiesthat contains the necessary keys for your plugin, e.g.
Note If you want to create the report without using Doxia, e.g. via XSL transformation from some XML file, then simply add the following method to your Mojo:
Keep in mind that in that case Maven will not be able to include the navigation into your report so you have to leave it out or include it yourself.
You will need the following dependencies to build your report plugin:
For a relatively straightforward report, you can take advantage of AbstractMavenReportRenderer.
This class will handle the basic negotiations with the Doxia sink, setting up the head, title, and body. You implement a renderBody method to fill in the middle. it provides utilities for sections and tables.
You also need to use the Doxia Sink API to have complete decoration (ie. menus). That is quite straightforward. You simply import
org.apache.maven.doxia.sink.Sink and get an instance by simply calling the class method
getSink() (you don't even have to implement it). Then you can do things like that:
Here is another complete example:
As one can easily see, the Sink API reproduces the major structural elements of HTML (and most other text markup languages). Start tag is denoted by
xxxx() method and end of tag by
xxxx_() method. You can do pretty much anything you could do with (x)HTML as there is even a
rawText() method that outputs exactly what you give it.
Note that the
text() method takes care of escaping characters.
Caveat: the sectionning is strict which means that section level 2 must be nested in section 1 etc.
Note: To find out more about the possible markup (that is the available methods) you need to read the sources at http://svn.apache.org/repos/asf/maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.javasince there is no documentation on http://maven.apache.org/doxia/doxia-sink-api/index.html at the moment.
More than one report from one plugin
If you want to have more than one goal in your plugin to generate several reports, simply add another Mojo with its own
@goal something tag. From the POM, you can control which goal is executed within the
<reportSet> section as follows:
Maven Changes Plugin
One of the best possibilities to understand how reporting works at this level is to have a look into the sources of the Maven Changes Plugin at https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-changes-plugin/(or the current TAG inhttps://svn.apache.org/repos/asf/maven/plugins/tag, if you prefer that). The sources aren't hard to read and it takes little time to understand the mechanism.