Maven 3 Site Plugin – How To

Creating various helpful reports in a Maven based project is quite easy and straight forward. Such reports vary from simple javadoc to dependency reports and code coverage analysis and having them can be a major advantage during development. In the following post, I present an understandable how-to of generating these reports.

Configuration

Site and report generation is not a base feature of Maven (anymore [see footnote below]) , instead there is a plugin that is responsible for this tasks. The site plugin can be configured in the plugins section of a pom.xml. The configuration itself can contain several report plugins. The following snippet configures the site plugin and adds a number of useful report plugins to it. Simply copy this configuration to your personal pom.xml and adopt any parameters to your needs. Make sure to remove or replace the configuration file location within the maven-checkstyle-plugin.

 
<build>
<plugins>
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.0-beta-3</version>
  <configuration>
    <reportPlugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.2</version>
        <reports>
          <report>index</report>
          <report>project-team</report>
          <report>license</report>
          <report>mailing-list</report>
          <report>dependencies</report>
          <report>dependency-convergence</report>
          <report>plugin-management</report>
          <report>cim</report>
          <report>issue-tracking</report>
          <report>scm</report>
          <report>summary</report>
        </reports>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>2.6</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.7</version>
      </plugin>     
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>2.6</version>
        <configuration>
          <!-- Adopt config location to your needs, or remove configuration entry completly to use default version.
          <configLocation>http://stud.hs-heilbronn.de/~nischmid/development/checkstyle-config.xml</configLocation&gt;
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>findbugs-maven-plugin</artifactId>
        <version>2.3.1</version>
        <configuration>
          <argLine>-Xmx256m</argLine>
          <argLine>-XX:MaxPermSize=256m</argLine>
        </configuration>
        <!-- Usually findbugs needs a lot of memory, change these values if needed. -->
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>jdepend-maven-plugin</artifactId>
        <version>2.0-beta-2</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>cobertura-maven-plugin</artifactId>
        <version>2.4</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>taglist-maven-plugin</artifactId>
        <version>2.4</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jxr-plugin</artifactId>
        <version>2.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-pmd-plugin</artifactId>
        <version>2.5</version>
        <configuration>
          <linkXref>true</linkXref>
          <minimumTokens>100</minimumTokens>
          <minimumPriority>3</minimumPriority>
          <!-- Change minimum priority to see more or less messages -->
          <targetJdk>1.6</targetJdk>
        </configuration>
      </plugin>
    </reportPlugins>
  </configuration>
</plugin>
</plugins>
</build>

 

Report generation

Once, your configuration is set up, you can trigger a report generation with the command mvn site. Depending on the reports used, this may take a while. The final reports will be placed within the target folder. Just open target/site/index.html and you should see something similar to the following screenshot. Click on one of the two red-circled links to expand the report sections. Enjoy reading through the reports and improving your code.

Example Page - Maven Site Plugin

Note: With the introduction of Maven 3, there have been changes in the area of site and report generation, thus the shown pom.xml snippet does only work for Maven 3.0 or later.

Advertisements

Wie man Code-Qualität mit Eclipse, Maven, Findbugs, PMD und Checkstyle erreichen kann

Heute möchte ich ein paar Worte über Code-Qualität loswerden, oder vielmehr über Tools, mit denen man Code-Qualität fördern kann. Und da das Thema für mich irgendwie so einen typisch deutschen Charakter hat, gibt es den Eintrag heute mal in deutsch. Nicht das man in anderen Ländern nicht auch auf Qualität achten würde, aber in Deutschland hat man meiner Meinung nach schon einen sehr starken hang zu Qualitätsmaßnahmen und formalen Methoden um diese zu spezifizieren und zu verifizieren.

Nun aber zum Inhalt, die Idee ist es ein paar Tools, welche die Code-Qualität enorm verbessern können, mittels Maven so in ein Projekt zu integrieren, dass eine Reihe von Tools automatisch bei den Entwicklern in der Eclipse IDE eingebunden werden. Voraussetzung hierzu ist natürlich, dass zum einen das Projekt auf Maven basiert und zum anderen, dass Eclipse als IDE verwendet wird.

Die Tools die hierbei eingebunden werden sollen sind: Checkstyle, Findbugs und PMD. Ersteres prüft Source-Code auf Styling-Conventions hin und die beiden letzteren führen eine statische Code-Analyes durch um eine Reihe bekannter Quellen für Bugs im Source-Code aufzudecken. Zu allen drei Tools existieren Eclipse-Plugins, die sich jeder Entwickler zunächst in seiner IDE installieren muss. Der Installationsprozess soll hier kein Thema sein, sondern vielmehr die Konfiguration von Maven um die Tools automatisch mit in die Eclipse Projektkonfiguration aufzunehmen. Alle Tools können auch direkt in den Maven-Build integriert werden, und dies ist auch in jedem Fall zu empfehlen. Es hat sich jedoch gezeigt, dass die wenigsten Entwickler regelmäßig auf den Build-Server gehen und sich die jeweiligen Reports ansehen. Daher die so wichtige Integration direkt in die Entwicklungsumgebung.

Nachdem die Plugins erfolgreich in Eclipse installiert wurden, muss das Projekt POM angepasst werden. Wer ein allgemeines Parent POM hat, dass von allen Projekten verwendet wird, kann die Anpassungen gleich hier vornehmen, so gelten sie in Zukunft für alle Projekte. Für das Erstellen der Eclipse-Projekt-Konfiguration ist das Maven-Eclipse-Plugin zuständig, und eben jenem Plugin müssen lediglich die drei zusätzlichen Projectnatures sowie Buildcommands hinzugefügt werden.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-eclipse-plugin</artifactId>
            <configuration>
                <additionalProjectnatures>   
                    <nature>net.sf.eclipsecs.core.CheckstyleNature</nature>
                    <nature>edu.umd.cs.findbugs.plugin.eclipse.findbugsNature</nature>
                    <nature>net.sourceforge.pmd.eclipse.plugin.pmdNature</nature>
                </additionalProjectnatures>
                <additionalBuildcommands>
                    <name>net.sf.eclipsecs.core.CheckstyleBuilder</name>
                    <name>edu.umd.cs.findbugs.plugin.eclipse.findbugsBuilder</name>
                    <name>net.sourceforge.pmd.eclipse.plugin.pmdBuilder</name>
                </additionalBuildcommands>
            </configuration>
        </plugin>
    </plugins>
</build>

Wird nun das Maven-Eclipse-Plugin von einem Entwickler aufgerufen, und das Projekt anschließend in Eclipse importiert, verwendet dieses automatisch die drei Plugins für Checkstyle, Findbugs und PMD. Wer zusätzlich die Konfiguration zu den jeweiligen Tools anpassen und für alle Entwickler gesamtheitlich hinterlegen möchte, fügt ein paar weitere Zeilen in der Maven-Eclipse-Plugin Section hinzu. Exemplarisch sei hier gezeigt, wie eine Checkstyle-Konfiguration, die auf einem für alle Entwickler erreichbaren Server hinterlegt ist, eingebunden werden kann. Das Einbinden weiterer Konfigurations-Dateien erfolgt analog, Details zur Erstellung dieser Dateien finden sich auf den jeweiligen Tool Homepages.


    </additionalBuildcommands>
    <additionalConfig>
        <file>
            <name>.checkstyle</name>
            <content>
            <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
            <fileset-config file-format-version="1.2.0" simple-config="true">
                <local-check-config name="meine-checkstyle-checks" location="http://someserver/somepath/checkstyle-config.xml" type="remote" description="">
                    <additional-data name="cache-file" value="false"/>
                </local-check-config>
                <fileset name="all" enabled="true" check-config-name="meine-checkstyle-checks" local="true">
                    <file-match-pattern match-pattern="." include-pattern="true"/>
                </fileset>
            </fileset-config>]]>
            </content>
        </file>
    </additionalConfig>
</configuration>

Das war auch schon alles, von nun an bekommt jeder Entwickler direkt in seiner IDE angezeigt, wenn er gegen Style-Conventions verstößt, oder potenzielle Fehlerquellen in den Source-Code einbaut. Die so erzeugten Informationen gehen also nicht irgendwo auf dem Build-Server verloren.

Nochmal in der Übersicht:

1. Plugins in Eclipse installieren
2. Project-Nature und Buildcommands in POM eintragen
3. Individuelle Konfigurationen zur Verfügung stellen und ebenfalls im POM verlinken