Coding Chica

Table of Contents

1. Table of Contents
2. Introduction
3. Default Reports
4. Project Information: About Page
5. Project Information: Summary Page
   1. Project Information
   2. Project Organization
   3. Build Information
   4. Download
6. Project Information: Plugin Management
7. Project Information: Plugins
8. Project Information: Dependency Information
9. Project Information: Dependencies
   1. Project Dependencies
   2. Project Transitive Dependencies
   3. Project Dependency Graph
   4. Licenses
   5. Dependency File Details
10. CI Management
11. Pinning the Plugin Version
12. Configuring the Plugin

Introduction

If we want to generate a site describing our Java project, then Maven supports the generation of one as part of the build.

Default Reports

Out of the box, without any additional configuration, Maven will generate a very basic set of HTML pages with project details just by running:

# Generate the ./target/site into the existing folders
mvn site

# Delete the ./target folder before generating the ./target/site
# If this errors on rerun - it may be because you are viewing the site in your browser and therefore a lock is present on the folder/file.
mvn clean site

This will use the maven-project-info-reports-plugin without any additional configuration in our build.

Project Information: About Page

If we do this for the java101 project and then in the IntelliJ IDE find java101/target/site/index.html -> Right click -> Open In -> Browser -> Choose your favorite locally installed browser, then we will see a message like:

About java101

There is currently no description associated with this project.

java101/target/site/index.html

If we add a description in our java101/pom.xml just under the name and then rerun:

<name>java101</name>
<description>This is a very simple Java project with a Maven build, which is intended to showcase different Java syntax, build, coding conventions and unit testing approaches.</description>

The description we use in the pom.xml should now be displayed on the java101/target/site/index.html if we reload it in the browser. This could be as simple or as elaborate as your team chooses. While above, we chose to only include a simple sentence, the https://maven.apache.org/plugins/maven-project-info-reports-plugin/index.html is a much longer index.html page.

Project Information: Summary Page

This page is generated at java101/target/site/summary.html. It contains several sections.

Project Information

The java101/pom.xml was generated with a url tag, but it points to the wrong URL and contains a FIXME comment to correct it. Let’s update the value and remove the FIXME comment. In my case, I’m going to use the URL to the github repo.

<!-- FIXME change it to the project's website -->
<url>http://www.example.com</url>

This section relays the following information:

Project Organization

The project organization section relays information about the larger organization to which the application team belongs. Including the following information:

Build Information

The build information section relays information about the Java project and the artifact(s) it produces.

Download

The download section includes the following information:

Project Information: Plugin Management

This page summarizes plugins defined in the project.build.pluginManagement.plugins section of the pom.xml. These plugins are available for possible use in this project or any of its Maven sub-modules. This page is generated at java101/target/site/plugin-management.html.

Project Information: Plugins

This page summarizes the plugins defined in the pom.xml for use in this Maven project based upon the project.build.plugins. There may be overlap with the Plugin Management page, depending upon how the pom.xml was defined. This page is generated at java101/target/site/plugins.html.

Project Information: Dependency Information

This page is generated at java101/target/site/dependency-info.html and summarizes how this project’s artifacts can be consumed as a dependency in other project’s builds using different build tools, such as:

• Apache Maven
• Apache Buildr
• Apache Ivy
• Groovy Grape
• Gradle/Grails
• Scala SBT
• Leiningen

Project Information: Dependencies

This page is generated at java101/target/site/dependencies.html and summarizes the dependencies consumed in this project’s build.

Project Dependencies

Those dependencies consumed directly as a top-level dependency based upon those explicitly defined in the pom.xml. Within this section, the dependencies will be grouped by the Maven dependency scope.

Project Transitive Dependencies

The dependencies that come along as a result of including other, top-level dependencies in our pom.xml. This section is again sub-divided by Maven dependency scope.

Project Dependency Graph

A tree representation of dependencies, where transitive dependencies are indented in the line under the dependency that caused it to be included. For example, in our current java101 project, it shows:

codingchica:java101:jar:0.1-SNAPSHOT [Information]
    org.junit.jupiter:junit-jupiter-params:jar:5.9.2 (test) [Information]
        org.junit.jupiter:junit-jupiter-api:jar:5.9.2 (test) [Information]
            org.opentest4j:opentest4j:jar:1.2.0 (test) [Information]
            org.junit.platform:junit-platform-commons:jar:1.9.2 (test) [Information]
        org.apiguardian:apiguardian-api:jar:1.1.2 (test) [Information]
    org.projectlombok:lombok:jar:1.18.28 (provided) [Information]

• The left-most item is the artifact generated by this project.
• The items listed at the first level of indenting are direct dependencies of this project.
• Those items at the second level of indenting are transitive dependencies included into the project because of the first item above them that is at the prior level of indenting.
  • For example org.junit.jupiter:junit-jupiter-params:jar:5.9.2 causes org.junit.jupiter:junit-jupiter-api:jar:5.9.2 and org.apiguardian:apiguardian-api:jar:1.1.2 to be included as transitive dependencies.
• The nesting may continue further. Each indenting level indicates that transitive dependencies are being included because of a more-direct dependency.

The Maven scope of each dependency is shown within parenthesis (). If you click on the Information [i] button, it also displays the following for that dependency:

• Description
• URL
• Project Licenses

The dependency tree information can come in very handy when either troubleshooting dependencies, looking for dependency documentation or checking which dependencies are used in the event of security vulnerabilities.

Licenses

License details for the current project and its various dependencies, where known.

Dependency File Details

Summary information about the size and contents of the individual dependencies, such as:

• Size
• Entries
• Classes
• Packages
• Java Version (If available)
• Debug Information

CI Management

If populated in the pom.xml, this page will relay details about the continuous integration management, such as which tool is used for automated builds and where the build can be found.

Pinning the Plugin Version

Even if we do not want to customize the configuration of the plugin, having the plugin version information called out in the java101 pom.xml will make our build a little more stable, as the plugin version won’t change without us directly modifying the pom.xml.

Without this step, if the plugin were to release a new version that modifies the text / formatting, then the site could change suddenly and be difficult to troubleshoot, as there would be no indication in our code base of what changed.

To pin the version, let’s add it to our project.build.pluginManagement section:

<plugin>
    <artifactId>maven-project-info-reports-plugin</artifactId>
    <version>3.4.5</version>
</plugin>

Configuring the Plugin

To change the behavior of one or more of the reports, add the plugin (no version needed, if it’s already part of the project.build.pluginManagement section) to the pom.xml’s project.reporting.plugins section. For example, to only generate the dependencies report, assuming the version is not needed for this reason:

...
<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-project-info-reports-plugin</artifactId>
            <reportSets>
                <reportSet>
                    <reports>
                        <report>dependencies</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
        ...
    </plugins>
</reporting>
...