The Cabe Maven Plugin

The Cabe Maven Plugin is a community-contributed plugin that integrates Cabe bytecode instrumentation with Maven projects. Cabe is a Java bytecode instrumentation tool that inserts runtime checks based on JSpecify annotations into your class files.

Purpose and Benefits

Cabe helps implement the Fail-Fast Principle by automatically adding runtime checks for annotated method parameters. This provides several benefits:

Early Detection: Violations of nullability contracts are detected immediately at the point of violation
Improved Debugging: Clear error messages that identify the exact parameter that violated the contract
Reduced Boilerplate: No need to manually write null checks for annotated parameters
Consistent Enforcement: Ensures that nullability contracts are enforced consistently across your codebase

Requirements

Java 17 or later
Maven 3.6.0 or later
JSpecify annotations (typically org.jspecify:jspecify:1.0.0)

Usage

1. Add the Plugin to Your POM

Add the Cabe Maven Plugin to your project's pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>com.dua3.cabe</groupId>
      <artifactId>cabe-maven-plugin</artifactId>
      <version>4.1</version>
      <executions>
        <execution>
          <goals>
            <goal>cabe</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

2. Configure the Compiler to Use a Separate Output Directory

To avoid processing class files multiple times, configure the Maven Compiler Plugin to output compiled classes to a separate directory:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
  <executions>
    <execution>
      <id>default-compile</id>
      <configuration>
        <compilerArgs>
          <arg>-d</arg>
          <arg>${project.build.directory}/unprocessed-classes</arg>
        </compilerArgs>
      </configuration>
    </execution>
  </executions>
</plugin>

3. Configure the Cabe Plugin

Configure the Cabe plugin to process the unprocessed classes:

<plugin>
  <groupId>com.dua3.cabe</groupId>
  <artifactId>cabe-maven-plugin</artifactId>
  <version>4.1</version>
  <configuration>
    <inputDirectory>${project.build.directory}/unprocessed-classes</inputDirectory>
    <verbosity>1</verbosity>
    <configurationString>STANDARD</configurationString>
    <strict>false</strict>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>cabe</goal>
      </goals>
    </execution>
  </executions>
</plugin>

4. Add JSpecify Dependency

Add the JSpecify annotations to your project:

<dependencies>
  <dependency>
    <groupId>org.jspecify</groupId>
    <artifactId>jspecify</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>

5. Use JSpecify Annotations in Your Code

Use JSpecify annotations in your code to specify nullability contracts:

import org.jspecify.annotations.NonNull;

public class Hello {
    public static void main(String[] args) {
        sayHello("World"); // Works fine
        sayHello(null);    // Will throw NullPointerException at runtime
    }

    public static void sayHello(@NonNull String name) {
        System.out.println("Hello, " + name + "!");
    }
}

Configuration Options

The Cabe Maven Plugin supports the following configuration options:

verbosity

Controls the level of logging output.

Possible values:

0: Show warnings and errors only (default)
1: Show basic processing information
2: Show detailed information
3: Show all information

inputDirectory

The directory containing the compiled class files to process.

<inputDirectory>${project.build.directory}/unprocessed-classes</inputDirectory>

Default: ${project.build.outputDirectory}

outputDirectory

The directory where processed class files will be written.

<outputDirectory>${project.build.outputDirectory}</outputDirectory>

Default: ${project.build.outputDirectory}

configurationString

The configuration mode for Cabe processing.

<configurationString>STANDARD</configurationString>

Possible values:

STANDARD: Use standard assertions for private API methods, throw NullPointerException for public API methods (default)
DEVELOPMENT: Failed checks will always throw an AssertionError, also checks return values
NO_CHECKS: Do not add any null checks (class files are copied unchanged)
Custom configuration string: For advanced configuration (see Cabe documentation for details)

strict

Whether to enable strict mode for equals(Object) checks.

Default value is false. When set to true, instrumentation will fail if the equals(Object) contract is violated. When set to false, a warning will be logged instead.

Complete Example

Here's a complete example of a Maven project using the Cabe Maven Plugin:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>hello-maven</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.jspecify</groupId>
      <artifactId>jspecify</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>

  <build>
    <finalName>hello-maven</finalName>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
        <executions>
          <execution>
            <id>default-compile</id>
              <configuration>
                  <compilerArgs>
                      <arg>-d</arg>
                      <arg>${project.build.directory}/unprocessed-classes</arg>
                  </compilerArgs>
              </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>com.dua3.cabe</groupId>
        <artifactId>cabe-maven-plugin</artifactId>
        <version>4.1</version>
        <configuration>
          <inputDirectory>${project.build.directory}/unprocessed-classes</inputDirectory>
          <verbosity>1</verbosity>
          <configurationString>STANDARD</configurationString>
          <strict>false</strict>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>cabe</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.4.2</version>
        <configuration>
          <archive>
            <manifest>
              <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
              <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
              <addClasspath>true</addClasspath>
              <mainClass>hello.Hello</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Troubleshooting

Common Issues

Class Files Not Being Processed

If your class files aren't being processed, check:

The inputDirectory configuration is correct
The Maven Compiler Plugin is configured to output to the correct directory
The Cabe plugin is bound to the correct phase (default is process-classes)

NoClassDefFoundError for JSpecify Annotations

If you get NoClassDefFoundError for JSpecify annotations at runtime, make sure:

The JSpecify dependency is correctly added to your project
The dependency scope is appropriate (usually compile)

Unexpected NullPointerExceptions

If you're getting unexpected NullPointerExceptions:

Check that your code respects the nullability contracts specified by the annotations
Consider using a different configurationString during development (e.g., DEVELOPMENT)
Increase the verbosity level to get more detailed information about the processing

Cabe 3 Help