Maven License Plugin (Official & Original)

Basically, when you are developing a project either in open source or in a company, you often need to add at the top of your source files a license to protect your work. I didn’t find any maven plugin on Internet to help you maintain these license headers. By maintaining, i mean checking if the header is here or not, generating a report and of course having the possibility to update / reformat missing license headers.

Table of contents

Features

Contributors

Please let me know if your name is missing!

Releases

Available in Maven Central Repository: https://repo1.maven.org/maven2/com/mycila/license-maven-plugin/

Reports

The detailed Maven Plugin Documentation generated for each build is available here:

NOTE: Between versions 4.0 and 3.0 the configuration syntax has been changed. The plugin now has the concept of License Sets, which allow you to work with one or more license configurations in a single execution of the plugin. In simple terms, a <licenseSet> wraps the previous configuration options for a license. The previous configuration syntax is still supported but deprecated, and may be removed in future.

WARNING: there is good chances the latest version is greater than latest documentation, if nothing has changed concerning the plugin configurations.

WARNING : Java version compatibility

Version 4.6 is the latest release compatible with Java 8.

Version >= 5.0.0 will require Java 11.

Version >= 6.0.0 will require Java 17.

Documentation

Plugin declaration

<plugin>
  <groupId>com.mycila</groupId>
  <artifactId>license-maven-plugin</artifactId>
  <version>4.6</version>
  <configuration>
    <properties>
      <owner>Mycila</owner>
      <email>mathieu.carbou@gmail.com</email>
    </properties>
    <licenseSets>
      <licenseSet>
        <header>com/mycila/maven/plugin/license/templates/APACHE-2.txt</header>
        <excludes>
          <exclude>**/README</exclude>
          <exclude>src/test/resources/**</exclude>
          <exclude>src/main/resources/**</exclude>
        </excludes>
      </licenseSet>
    </licenseSets>
  </configuration>
</plugin>

Note: inlineHeader can also be used instead of header to specify directly the header content in the POM.

For Multi-Licensing

If your source code makes use of multi-licensing, then instead of a <header> or <inlineHeader> element in the configuration you can use a <multi> element.

The <multi> element allows you to specify an optional preamble, one or more header (or inlineHeader) and separators between them. These options are concatenated together to produce a header template.

<plugin>
  <groupId>com.mycila</groupId>
  <artifactId>license-maven-plugin</artifactId>
  <version>4.6</version>
  <configuration>
    <licenseSets>
      <licenseSet>
        <multi>
          <preamble><![CDATA[This product is dual-licensed under both the GPLv2 and Apache 2.0 License.]]></preamble>
          <header>GPL-2.txt</header>
          <separator>======================================================================</separator>
          <header>com/mycila/maven/plugin/license/templates/APACHE-2.txt</header>
        </multi>
        <excludes>
          <exclude>**/README</exclude>
          <exclude>src/test/resources/**</exclude>
          <exclude>src/main/resources/**</exclude>
        </excludes>
      </licenseSet>
    </licenseSets>
    <properties>
      <owner>Mycila</owner>
      <email>mathieu.carbou@gmail.com</email>
    </properties>
  </configuration>
</plugin>

Goals

Configuration

The table below shows all the available options you can use in the configure section of the plugin. A lot of are also available from the command-line. To use them, simply launch your maven command with a property like -Dproperty=value (i.e. mvn license:check -Dlicense.header=src/etc/header.txt)

All plugin configuration options are described in the Detailed Maven documentation but here are some details.

License templates

Maven license plugin comes with the following license templates:

You can find those license templates with preconfigured placeholders here

Properties and placeholders

Properties which can be used as placeholder comes from:

Properties are built per-document. You can provide a dependency JAR file to the plugin which contains an implementation of com.mycila.maven.plugin.license.PropertiesProvider:

public interface PropertiesProvider {
  Map<String, String> getAdditionalProperties(AbstractLicenseMojo mojo, Properties currentProperties, Document document);
}

You have access to the Mojo, the current built properties and the document being checked or formatted. The plugin uses the JDK ServiceLoader mechanism to find all PropertiesProvider implementations on the plugin classpath and execute them. Thus, just add the implementation class name in the file META-INF/services/com.mycila.maven.plugin.license.PropertiesProvider in your JAR file.

Supported comment types

The plugin has been designed so that it is very easy to add new supports for new sorts of comment. The plugin currently support these types of comment:

(automatically right-adjusts the closing comment)

(4 spaces, then the lines of the header)

(inserted after the <?php> tag)

All the styles can be found here: https://github.com/mathieucarbou/license-maven-plugin/tree/master/license-maven-plugin/src/test/resources/styles

Custom mapping

The plugin enables you to add any other mapping you want.* I.e., if you are developing a Tapestry web application, you may need to add license header in .jwc files and .application files. since these files are xml files, you only need to add in your project pom the following mapping for the license-maven-plugin:

<mapping>
  <jwc>XML_STYLE</jwc>
  <application>XML_STYLE</application>
  <apt.vm>DOUBLETILDE_STYLE</apt.vm>
  <vm>SHARPSTAR_STYLE</vm>
  <apt>DOUBLETILDE_STYLE</apt>
</mapping>

You can use composed-extensions like *.apt.vm and redefine them, but you will have to make sure that the mapping of apt.vm is before the mapping of the vm extension. The order in the mapping section is important: extensions seen first take precedence.

Java packages

Another use case for custom mappings is when writing Java code in packages; the licence header should come after the package declaration line in this case. Simply add this to the plugin configuration:

<mapping>
  <java>JAVAPKG_STYLE</java>
</mapping>

Changing header style definitions

In license-maven-plugin, each header style is defined by patterns to detect it and also strings to insert it correctly in files. If we take for example the Javadoc style header definition. It is defined as follow:

<?xml version="1.0" encoding="ISO-8859-1"?>
<additionalHeaders>
  <javadoc_style>
    <firstLine>/**</firstLine>
    <beforeEachLine> * </beforeEachLine>
    <endLine> */</endLine>
    <afterEachLine></afterEachLine>
    <!--skipLine></skipLine-->
    <firstLineDetectionPattern>(\s|\t)*/\*.*$</firstLineDetectionPattern>
    <lastLineDetectionPattern>.*\*/(\s|\t)*$</lastLineDetectionPattern>
    <allowBlankLines>false</allowBlankLines>
    <multiLine>true</multiLine>
    <padLines>false</padLines>
  </javadoc_style>
</additionalHeaders>

And for XML:

<?xml version="1.0" encoding="ISO-8859-1"?>
<additionalHeaders>
  <xml_style>
    <firstLine><![CDATA[<!--\n]]></firstLine>
    <beforeEachLine>    </beforeEachLine>
    <endLine><![CDATA[-->]]></endLine>
    <afterEachLine></afterEachLine>
    <skipLine><![CDATA[^<\?xml.*>$]]></skipLine>
    <firstLineDetectionPattern><![CDATA[(\s|\t)*<!--.*$]]></firstLineDetectionPattern>
    <lastLineDetectionPattern><![CDATA[.*-->(\s|\t)*$]]></lastLineDetectionPattern>
    <allowBlankLines>false</allowBlankLines>
    <multiLine>true</multiLine>
    <padLines>false</padLines>
  </xml_style>
</additionalHeaders>

With the headerDefinitions option, you can redefine existing header styles and also add some if we do not support the styles you want yet. You just have to provide a list of headerDefinition containing a resource name. Like the header, the resource is searched on the file system, in the classpath of the project, the plugin and also as a URL.

Full Example

This page will show you how you can define extended header definitions to fit your needs. The next example will define headers in a region area allowed in C# source files:

<?xml version="1.0" encoding="ISO-8859-1"?>
<additionalHeaders>
  <csregion_style>
    <firstLine>#region LicenseEOL/**</firstLine>
    <beforeEachLine> * </beforeEachLine>
    <endLine> */EOL#endregion</endLine>
    <firstLineDetectionPattern>#region.*^EOL/\*\*.*$</firstLineDetectionPattern>
    <lastLineDetectionPattern>\*/EOL#endregion"</lastLineDetectionPattern>
    <allowBlankLines>true</allowBlankLines>
    <multiLine>true</multiLine>
  </csregion_style>
</additionalHeaders>

You now have to add this new header definition file to the plugin configuration. It is done as the following in your pom:

<headerDefinitions>
  <headerDefinition>yourdefinition.xml</headerDefinition>
</headerDefinitions>

You now have to add the new mapping for *.cs files to use this new header definition. It is done as the following in your pom:

<mapping>
  <cs>CSREGION_STYLE</cs>
</mapping>

And it should generate headers like:

    #region License
    /**
     * Copyright (C) 2008 http://code.google.com/p/license-maven-plugin/
     *
     * Licensed under the Apache License, Version 2.0 (the "License");
     * you may not use this file except in compliance with the License.
     * You may obtain a copy of the License at
     *
     *         http://www.apache.org/licenses/LICENSE-2.0
     *
     * Unless required by applicable law or agreed to in writing, software
     * distributed under the License is distributed on an "AS IS" BASIS,
     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     * See the License for the specific language governing permissions and
     * limitations under the License.
     */
    #endregion

Inline styles

This is also possible to configure new header style inline within the POM without using external files. This is a useful feature for module inheritance.

The following example will redefine the header file for text files:

<plugin>
    <groupId>com.mycila</groupId>
    <artifactId>license-maven-plugin</artifactId>
    <configuration>
      <mapping>
        <txt>SMILEY_STYLE</txt>
      </mapping>
      <defaultInlineHeaderStyles>
        <defaultInlineHeaderStyle>
          <name>SMILEY_STYLE</name>
          <firstLine>:(</firstLine>
          <beforeEachLine> ( </beforeEachLine>
          <endLine>:(</endLine>
          <firstLineDetectionPattern>\:\(</firstLineDetectionPattern>
          <lastLineDetectionPattern>\:\(</lastLineDetectionPattern>
          <allowBlankLines>false</allowBlankLines>
          <multiLine>false</multiLine>
        </defaultInlineHeaderStyle>
      </defaultInlineHeaderStyles>
    </configuration>
</plugin>

Dependency enforcement

This plugin can be configured to break the build when its dependencies do not adhere to a configured license policy. This plugin relies on the accuracy of the <licenses> maven property configured in the pom of artifacts your project declares in <dependencies>.

There are currently three types of policies which can be enforced:

  1. LICENSE_URL - strict match on the URL element of a License
  2. LICENSE_NAME - strict match on the name of a License
  3. ARTIFACT_PATTERN - regex on a groupdId:artifactId

Rules can be defined in the plugin configuration like so:

<plugin>
    <groupId>com.mycila</groupId>
    <artifactId>license-maven-plugin</artifactId>
    <configuration>
        <dependencyEnforce>true</dependencyEnforce>
        <dependencyExceptionMessage>A custom error message for how to handle approvals in your organization</dependencyExceptionMessage>
        <dependencyPolicies>
            <dependencyPolicy>
                <type>LICENSE_NAME</type>
                <rule>APPROVE</rule>
                <value>Public Domain</value>
            </dependencyPolicy>
            <dependencyPolicy>
                <type>LICENSE_URL</type>
                <rule>APPROVE</rule>
                <value>https://www.apache.org/licenses/LICENSE-2.0.txt</value>
            </dependencyPolicy>
            <dependencyPolicy>
                <type>ARTIFACT_PATTERN</type>
                <rule>APPROVE</rule>
                <value>com.mycila.*</value>
            </dependencyPolicy>
            <dependencyPolicy>
                <type>ARTIFACT_PATTERN</type>
                <rule>DENY</rule>
                <value>com.example.*</value>
            </dependencyPolicy>
            <dependencyPolicy>
                <type>ARTIFACT_PATTERN</type>
                <rule>ALLOW</rule>
                <value>com.example.subpackage:other-artifact:jar:1.0.0</value>
            </dependencyPolicy>
        </dependencyPolicies>
    </configuration>
</plugin>

There is also an implicit default deny artifact pattern policy, so if you enable dependency enforcement and have any dependencies, you must configure a policy. The ordering of the declared dependencyPolicies does not matter, and in aggregate they will be enforced in the following way:

  1. defaultPolicy included in the plugin, matching all artifacts with a deny rule
  2. APPROVE policies
  3. DENY policies

Given the above configuration example, you could state:

Development

Requirements

Some Maven commands

Making sure the project builds:

./mvnw clean install site

When developing, build fast with:

./mvnw clean install -Dfast

Releasing a version

# Example: 4.0.rc1
./mvnw release:prepare -DreleaseVersion=4.0.rc1 -Dtag=license-maven-plugin-4.0.rc1 -DdevelopmentVersion=4.0-SNAPSHOT

# Example: 4.0
./mvnw release:prepare -DreleaseVersion=4.0 -Dtag=license-maven-plugin-4.0 -DdevelopmentVersion=4.1-SNAPSHOT

Then:

export MAVEN_GPG_PASSPHRASE=...
./mvnw release:perform -Darguments="-Dgpg.keyname=EDEA921A"

# If the release perform fails, restart it with (from the target/checkout folder):
`./mvnw deploy -Dgpg.keyname=EDEA921A -DperformRelease=true`

Then, go to https://oss.sonatype.org/ to “close and release”. Then you should see a few minutes later the new version at https://repo1.maven.org/maven2/com/mycila/license-maven-plugin/

Generate site from any branch or tag

./mvnw clean install site