In this tutorial, we will learn about the Apache Rat tool and the Apache Maven Rat Plugin for Java applications. We will also see how to integrate the plugin into the verify phase of the Maven build lifecycle. Lastly, we will configure the plugin to detect and approve our custom license headers.
1. What is Apache Rat?
Apache Rat is a release audit tool, focused on licenses. It audits the source code files to verify whether they contain the license information and copyright notices like the ASF Source Header and Copyright Notice Policy .
This tool helps in improving accuracy and efficiency when checking source code files for licenses, which could be otherwise a time-consuming process, quite prone to error.
Apache Rat offers built-in support for quite a few license types that can be used to audit source files for common-licenses.
2. Apache Maven Rat Plugin
Apache Rat also provides a plugin for Apache Maven to audit source code files at the time of building the project. The Apache Maven Rat Plugin can be used for Maven versions 2.2.1 or later.
2.1. Basic Illustration
Using the Maven Rat plugin is quite simple and straightforward. We just need to configure the plugin in the pom.xml.
The below illustration shows the basic usage of the Rat plugin.
Rat Plugin Example
<plugins> .... <plugin> <groupId>org.apache.rat</groupId> <artifactId>apache-rat-plugin</artifactId> <version>0.13</version> </plugin> .... </plugins>
The latest available version of Apache Rat is 0.13.
3. Goals
The Maven Rat Plugin provides two goals for running the audit operations.
- apache-rat:check
- apache-rat:rat
3.1. Check
The apache-rat:check goal runs the audit tool and generates a report, which by default is written to a plain text file rat.txt in the target folder.
3.2. Rat
Theapache-rat:rat the goal is similar to the check goal, but the generated report is added to the generated site.
4. Reporting With the Rat Plugin
Apache Maven provides the ‘site’ plugin to generate a site for the project. As a result, we can place additional content (e.g. documentation, resources, etc.) on our site. The generated site is available in the target/site/ directory.
We can use the Maven Rat plugin in addition to the Maven Site plugin. Hence, the Rat plugin will run, generate a report and add it to the site whenever we execute the following command:
mvn site
The following snippet shows the sections of the pom to achieve reporting.
Reporting
<reporting>
<plugins>
....
<plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<version>0.13</version>
</plugin>
....
</plugins>
</reporting>
...
<plugins>
....
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.9.1</version>
</plugin>
<plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<version>0.13</version>
</plugin>
....
</plugins>
5. Build Lifecycle Verify Phase Example
The Apache Maven Rat plugin can also be configured to run automatically as part of the "verify" phase of the Maven build lifecycle.
The following code snippet demonstrates this.
Verify Phase Example
<plugins>
....
<plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<version>0.13</version>
<executions>
<execution>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
....
</plugins>
6. Custom License Matchers
Apache Rat comes with built-in support for matching and verifying some typical licenses. However, there may be cases where we need a custom license matcher for our custom header in the source code files.
6.1. Custom Header
For instance, our source code might contain a header like the following:
Custom Header
/** * Java Code Geeks Custom License 1.0 * * Long text, specifying the copyrights etc. */
6.2. Custom Header Matcher
A license matcher is an implementation of org.apache.rat.analysis.IHeaderMatcher. The predefined license matchers provided by Apache Rat can be found here.
In this section, we will configure the Maven Rat plugin to use a custom implementation of a license matcher. The following snippet of pom.xml illustrates the use of a custom license matcher.
Custom License Matcher
<plugins> <plugin> <groupId>org.apache.rat</groupId> <artifactId>apache-rat-plugin</artifactId> <version>0.13</version> <configuration> <licenses> <license implementation="org.apache.rat.analysis .license.SimplePatternBasedLicense"> <licenseFamilyCategory> JCGL </licenseFamilyCategory> <licenseFamilyName> Java Code Geeks License (JCGL) 1.0 </licenseFamilyName> <notes></notes> <patterns> <pattern> Java Code Geeks Custom License 1.0 </pattern> </patterns> </license> </licenses> </configuration> </plugin> </plugins>
Let’s discuss some of the terms used in the above example:
- licenseFamilyCategory: This is a short string that identifies the license. For example, MIT, GPL , AL etc.
- licenseFamilyName: It is a large string in comparison to the
licenseFamilyCategoryand represents the full name of the license. e.g. GNU General Public License, version 2. - pattern: This string specifies a pattern to be matched against the source code files that may contain the license header.
6.3. Adding Custom License to Rat Approved Licenses
In the above section, we detected our custom header successfully. However, it is not enough. In spite of this, Rat does not consider our license as approved.
In order to add our license to the set of licenses approved by Rat, we need to provide a custom implementation of org.apache.rat.license.ILicenseFamily.
We can configure the plugin by providing an instance of the built-in SimpleLicenseFamily for our custom license. As a result, our custom license will be considered as approved by Rat.
The following snippet of pom.xml shows the complete configuration to support Custom Headers in our source code.
Adding Custom License to Rat Approved Licenses
<plugins> <plugin> <groupId>org.apache.rat</groupId> <artifactId>apache-rat-plugin</artifactId> <version>0.13</version> <configuration> <licenses> <license implementation="org.apache.rat.analysis .license.SimplePatternBasedLicense"> <licenseFamilyCategory> JCGL </licenseFamilyCategory> <licenseFamilyName> Java Code Geeks License (JCGL) 1.0 </licenseFamilyName> <notes></notes> <patterns> <pattern> Java Code Geeks Custom License 1.0 </pattern> </patterns> </license> </licenses> <licenseFamilies> <licenseFamily implementation="org.apache.rat.license .SimpleLicenseFamily"> <familyName> Java Code Geeks License (JCGL) 1.0 </familyName> </licenseFamily> </licenseFamilies> </configuration> </plugin> </plugins>
The familyName used in the above example should be the same as the licenseFamilyName in the custom license matcher.
7. Optional Parameters
In this section, we will discuss some of the parameters that can be optionally used to configure the Maven Rat plugin.
consoleOutput:A boolean value to configure if the file names with unapproved licenses should be output to the console.exludes:A String[] type to specify files that should be excluded from the report. By default, Rat excludes none of the files.ignoreErrors: A boolean value, if set to true, will ignore Rat errors and display a message if any. It is not RECOMMENDED to use this.reportFile:A name specifying the filename to store the report.reportStyle:A string value that specifies the output format of the report. The values could be “plain”(default) for a plain-text file or “xml” for an XML based report.
Visit the official goals page of Maven Rat plugin to view the other optional parameters.
8. Conclusion
In this article, we learned about the Apache Maven Rat Plugin. At first, we saw a basic implementation of the Rat plugin followed by the supported goals. After that, we used the Rat plugin along with the Maven Site plugin.
Additionally, we configured the rat plugin to run automatically in the verify phase of the Maven build lifecycle. Lastly, we used our custom header matcher to detect our license header in the source code and configured Rat to approve our license.
9. Download the source code
All the code examples provided in this tutorial are available in a Maven project and should be easy to import and run.
Please find the individual pom.xml for each of the sections in this project in the src/main/resources folder.
You can download the full source code of this example here: Apache Maven Rat Plugin Tutorial
