Jspecify provides a set of annotations to explicitly declare the nullness expectations of the Java code.

Add jSpecify support in Maven projects

If you are using Maven, then add the jspecify dependency in pom.xml. In pom.xml, update or add the maven-compiler-plugin, to include the following configuration.

xml
1<dependencies>
2    <dependency>
3        <groupId>org.jspecify</groupId>
4        <artifactId>jspecify</artifactId>
5        <version>1.0.0</version>
6    </dependency>
7</dependencies>
8
9<build>
10    <plugins>
11        <plugin>
12            <groupId>org.apache.maven.plugins</groupId>
13            <artifactId>maven-compiler-plugin</artifactId>
14            <version>3.14.1</version>
15            <configuration>
16                <release>25</release>
17                <encoding>UTF-8</encoding>
18                <fork>true</fork>
19                <compilerArgs>
20                    <arg>-XDcompilePolicy=simple</arg>
21                    <arg>--should-stop=ifError=FLOW</arg>
22                    <arg>-Xplugin:ErrorProne -XepDisableAllChecks -Xep:NullAway:ERROR -XepOpt:NullAway:OnlyNullMarked -XepOpt:NullAway:JSpecifyMode=true</arg>
23                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</arg>
24                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED</arg>
25                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED</arg>
26                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED</arg>
27                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</arg>
28                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED</arg>
29                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</arg>
30                    <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED</arg>
31                    <arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED</arg>
32                    <arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED</arg>
33                </compilerArgs>
34                <annotationProcessorPaths>
35                    <path>
36                        <groupId>com.google.errorprone</groupId>
37                        <artifactId>error_prone_core</artifactId>
38                        <version>2.42.0</version>
39                    </path>
40                    <path>
41                        <groupId>com.uber.nullaway</groupId>
42                        <artifactId>nullaway</artifactId>
43                        <version>0.12.12</version>
44                    </path>
45                </annotationProcessorPaths>
46            </configuration>
47        </plugin>
48    </plugins>
49</build>

Add jSpecify support in Gradle projects

If you are using Gradle, then add the jspecify dependency. In build.gradle or build.gradle.kts, update or add the following jspecify configuration.

groovy
1plugins {
2    id("net.ltgt.errorprone") version "4.3.0"
3}
4
5tasks.withType(JavaCompile).configureEach {
6    options.errorprone {
7        disableAllChecks = true // Other error prone checks are disabled
8        option("NullAway:OnlyNullMarked", "true") // Enable nullness checks only in null-marked code
9        error("NullAway") // bump checks from warnings (default) to errors
10        option("NullAway:JSpecifyMode", "true") // https://github.com/uber/NullAway/wiki/JSpecify-Support
11    }
12    // Keep a JDK 25 baseline
13    options.release = 25
14}
15
16dependencies {
17    implementation("org.jspecify:jspecify:1.0.0")
18    errorprone("com.google.errorprone:error_prone_core:2.42.0")
19    errorprone("com.uber.nullaway:nullaway:0.12.12")
20}

Add @NullMarked to package-info.java files

In every java package under the application main source code (src/main/java), create package-info.java if not exists already, and add the @NullMarked annotation as follows:

java
1@org.jspecify.annotations.NullMarked
2package com.mycompnay.myproject;

If package-info.java file already exists, update the file to add @org.jspecify.annotations.NullMarked annotation. DO NOT REMOVE ANY OTHER EXISTING CODE IN package-info.java FILE.

Verify jSpecify support

If python is installed, after adding the jSpecify support, run scripts/verify_nullmarked.py to check if all non-empty packages has package-info.java file or not.