Table of Contents

• 1. License
• 2. Overview
• 3. Usage
• 4. Sample
• 5. Options
  • 5.1. NotNull Annotations
  • 5.2. NotNullByDefault Annotations
  • 5.3. Nullable Annotations
  • 5.4. Instrumentations Types
  • 5.5. Exception to Throw
  • 5.6. Exception Text
  • 5.7. Logging
  • 5.8. Log Location

1. License

See the LICENSE file for license rights and limitations (MIT).

2. Overview

It does not make sense to create a Maven plugin for simplifying the Javac plugin usage like is done for Gradle due to rather restrictive Maven facilities (more details on that here). So, we just provide information and examples on how to configure your Maven build to be able to use the target Javac plugin.

3. Usage

Mandatory

It’s necessary to configure maven-compiler to use the Javac plugin

<project>

  <!-- ... -->
  
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
          <compilerArgs>
            <arg>-Xplugin:Traute</arg>
          </compilerArgs>
          <annotationProcessorPaths>
            <path>
              <groupId>tech.harmonysoft</groupId>
              <artifactId>traute-javac</artifactId>
              <version>1.1.10</version> <!-- use the latest available version here -->
            </path>
          </annotationProcessorPaths>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Optional

It’s possible to specify additional options available in the Javac plugin:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.7.0</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
        <compilerArgs>
          <arg>-Xplugin:Traute</arg>
          <arg>-Atraute.annotations.not.null=mycompany.util.NotNul</arg>
          <arg>-Atraute.instrumentations=parameter</arg>
          <arg>-Atraute.log.verbose=true</arg>
        </compilerArgs>
      </configuration>
    </plugin>
  </plugins>
</build>

4. Sample

A sample Traute-aware Maven project can be found here.

5. Options

5.1. NotNull Annotations

NotNull annotations to use are defined through the traute.annotations.not.null option (multiple annotations might be specified separated by the colon (:)):

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Add null-checks only for method parameters/return values marked by @my.company.NotNull -->
  <arg>-Atraute.annotations.not.null=my.company.NotNull</arg>
</compilerArgs>

More details on that can be found here.

5.2. NotNullByDefault Annotations

NotNullByDefault annotations to use are defined through the traute.annotations.not.null.by.default. option prefix followed by the instrumentation type:

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Use my.custom.NotNullByDefault for method parameters -->
  <arg>-Atraute.annotations.not.null.by.default.parameter=my.custom.NotNullByDefault</arg>
</compilerArgs>

More details on that can be found here.

5.3. Nullable Annotations

Nullable annotations to use are defined through the traute.annotations.nullable option (multiple annotations might be specified separated by :):

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Do not generate null-checks for method parameters/return values marked by @my.company.Nullable -->
  <arg>-Atraute.annotations.not.null=my.company.Nullable</arg>
</compilerArgs>

More details on that can be found here.

5.4. Instrumentation Types

Instrumentations types to use are defined through the traute.instrumentations option:

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Add checks only for method parameters (do not add check for return values) -->
  <arg>-Atraute.instrumentations=parameter</arg>
</compilerArgs>

More details on that can be found here.

5.5. Exception to Throw

Custom exception class to throw from failed null-checks is defined through the traute.exception. option prefix followed by the instrumentation type:

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Throw a IllegalArgumentException when a null is given to a method parameter marked by @NotNull -->
  <arg>-Atraute.exception.parameter=IllegalArgumentException</arg>
  <!-- Throw a IllegalStateException when a null is given from a method marked by @NotNull -->
  <arg>-Atraute.exception.return=IllegalStateException</arg>
</compilerArgs>

More details on that can be found here.

5.6. Exception Text

Custom exception text to use in exceptions thrown from failed null-checks is defined through the traute.failure.text. option prefix followed by the instrumentation type:

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Use exception message like 'MyArg must not be null' for a method parameter names 'myArg' -->
  <arg>-Atraute.failure.text.parameter=$${capitalize(PARAMETER_NAME)} must not be null</arg>
</compilerArgs>

More details on that can be found here.

5.7. Logging

Logging verbosity is defined through the traute.log.verbose option:

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Use verbose logging -->
  <arg>-Atraute.log.verbose=true</arg>
</compilerArgs>

More details on that can be found here.

5.8. Log Location

Plugin’s log file is defined through the traute.log.file option:

<compilerArgs>
  <arg>-Xplugin:Traute</arg>
  <!-- Instruct the plugin to write its logs to the /home/me/traute.log -->
  <arg>-Atraute.log.file=/home/me/traute.log</arg>
</compilerArgs>

More details on that can be found here.