Maven

Apache Maven Rat Plugin Tutorial

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 licenseFamilyCategory and 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.

Download
You can download the full source code of this example here: Apache Maven Rat Plugin Tutorial

Anmol Deep

Anmol Deep is a senior engineer currently working with a leading identity security company as a Web Developer. He has 8 years of programming experience in Java and related technologies (including functional programming and lambdas) , Python, SpringBoot, Restful architectures, shell scripts, and databases relational(MySQL, H2) and nosql solutions (OrientDB and MongoDB). He is passionate about researching all aspects of software development including technology, design patterns, automation, best practices, methodologies and tools, and love traveling and photography when not coding.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Back to top button