JSpecify Null Safety Example

Null references remain a major source of runtime errors in Java. Over the years, the ecosystem produced many competing annotation libraries and analysis tools to reduce “nullness” bugs. JSpecify is an industry effort to create a small, standard set of annotations and an interoperable specification for nullness annotations so tooling and libraries can agree on semantics. Let us delve into understanding how JSpecify tackles null pointer exceptions and how it helps in writing more reliable code.

1. What Is JSpecify?

JSpecify is a community-driven specification that provides a standardized way to annotate and define nullness behavior in Java programs. Its goal is to bring consistency across different tools and frameworks by defining a minimal but essential set of annotations. Instead of replacing every existing annotation library, JSpecify focuses on being the common denominator so that IDEs, static analyzers, and compilers can all understand and interpret nullness contracts in a unified way.

• @Nullable — value may be null.
• @NonNull (also expressed in some tooling as @NotNull) — value is not null (default for some systems).
• Annotations can be applied at method return types, parameters, and fields to ensure contracts are explicit.
• JSpecify emphasizes API clarity, making it easy for developers and tools to reason about nullness guarantees.
• It is designed for gradual adoption — teams can start small, add annotations progressively, and still gain benefits.

By providing these standard annotations and semantics, JSpecify reduces confusion caused by inconsistent null-safety annotations across libraries like javax.annotation, org.jetbrains, and others. The ultimate vision is to create a shared language of null-safety across the Java ecosystem.

1.1 Why Care About Null Safety?

Null-related errors, especially the dreaded NullPointerException, are among the most common sources of runtime bugs in Java. JSpecify helps tackle this problem by introducing clear contracts, which make programs more predictable, maintainable, and safer.

• Fewer runtime NPEs: Static analysis tools can catch potential NullPointerException issues before runtime.
• Clearer APIs: Method contracts explicitly communicate if null values are allowed, preventing misuse by API consumers.
• Easier reasoning: Annotated contracts simplify code reviews and make refactoring less risky.
• Interoperability: JSpecify provides a shared foundation so that tools, compilers, and frameworks agree on nullness semantics.
• Better documentation: Annotations serve as inline, always-up-to-date documentation for developers.
• Gradual improvement: Even partial adoption yields benefits — you don’t need 100% coverage to reduce bugs.

1.2 Use Cases

• Library development: Public APIs can declare clear null contracts to avoid confusion for users.
• Large codebases: Teams can standardize null-safety across thousands of classes, reducing inconsistent practices.
• Tool integration: IDEs and static analyzers can provide better suggestions and warnings with standardized annotations.
• Migration projects: During modernization, JSpecify helps safely refactor legacy code by introducing null contracts step by step.
• Cross-team collaboration: Multiple teams working on the same codebase can follow a single nullness standard.

1.3 Benefits of JSpecify

• Consistency: Removes ambiguity caused by multiple competing annotation libraries.
• Safety: Reduces runtime errors and improves application reliability.
• Adoption ease: Can be introduced gradually without disrupting existing workflows.
• Compatibility: Works well with existing tools, compilers, and frameworks.
• Clarity: Makes APIs self-documenting and easier for new developers to understand.

2. Code Example

The following is a minimal, runnable skeleton you can drop into a Gradle project to try JSpecify annotations, with a simple adapter and a service that demonstrates null-safety contracts.

2.1 Add Dependencies (build.gradle)

To start using JSpecify in your Java project, add the following dependency in your build.gradle file:

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    // JSpecify annotations - compileOnly so no runtime dependency
    compileOnly 'org.jspecify:jspecify:0.1'

    // Example runtime dependency - none required for annotations

    // Test
    testImplementation 'junit:junit:4.13.2'
}

Here, compileOnly ensures JSpecify annotations are available only at compile time and do not add any runtime overhead. This means your final application will not include JSpecify in its runtime classpath, while still benefiting from null-safety checks during development and testing.

2.2 Create a Model Class

First, create a simple User model class that uses JSpecify annotations to define nullability for fields and methods:

package com.example.jspecify.model;

import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

public final class User {
    private final String id;
    private final @Nullable String displayName;

    public User(@NonNull String id, @Nullable String displayName) {
        this.id = id;
        this.displayName = displayName;
    }

    @NonNull
    public String getId() { return id; }

    @Nullable
    public String getDisplayName() { return displayName; }
}

Here, the id field is always required (@NonNull), while displayName is optional (@Nullable). This allows tools and developers to understand exactly which values can be null.

2.3 Create a Repository Class

Next, define a repository to manage User objects. JSpecify annotations make the contract explicit: the id must not be null, and the result may be null if the user is missing.

package com.example.jspecify.repo;

import com.example.jspecify.model.User;
import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

import java.util.HashMap;
import java.util.Map;

public class UserRepositoryImpl {
    private final Map<String, User> store = new HashMap<>();

    public UserRepositoryImpl() {
        // Seed with two users, one without displayName
        store.put("u1", new User("u1", "Alice"));
        store.put("u2", new User("u2", null));
    }

    public @Nullable User findById(@NonNull String id) {
        if (id == null) throw new IllegalArgumentException("id must not be null");
        return store.get(id);
    }
}

The method findById guarantees that id cannot be null, but it may return null if no matching user exists.

2.4 Create a Service Class

The service layer uses the repository and applies null-safety checks to return safe defaults instead of null.

package com.example.jspecify.service;

import com.example.jspecify.model.User;
import com.example.jspecify.repo.UserRepositoryImpl;
import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

public class UserService {
    private final UserRepositoryImpl repo;

    public UserService(@NonNull UserRepositoryImpl repo) {
        this.repo = repo;
    }

    /**
     * Returns a displayable name for the given id. If user or displayName is missing,
     * returns a fallback string. Contract: id must be non-null.
     */
    @NonNull
    public String getDisplayNameFor(@NonNull String id) {
        User user = repo.findById(id);
        if (user == null) {
            return "(unknown)";
        }
        String dn = user.getDisplayName();
        return dn != null ? dn : "(no-name)";
    }
}

Here, JSpecify annotations help make it clear that getDisplayNameFor never returns null, even if the underlying data is missing or incomplete.

2.5 Create a Main Class

Finally, create the App entry point to test the flow:

package com.example.jspecify;

import com.example.jspecify.repo.UserRepositoryImpl;
import com.example.jspecify.service.UserService;

public class App {
    public static void main(String[] args) {
        UserRepositoryImpl repo = new UserRepositoryImpl();
        UserService service = new UserService(repo);

        System.out.println(service.getDisplayNameFor("u1"));      // Alice
        System.out.println(service.getDisplayNameFor("u2"));      // (no-name)
        System.out.println(service.getDisplayNameFor("missing")); // (unknown)
    }
}

When you run the program, you’ll see that null values are safely handled and never propagated to the caller. This demonstrates how Java jspecify null safety annotations can make your code safer and easier to maintain.

2.6 Run the Code

Once the classes are in place, you can compile and run the application using Gradle or your IDE. If using the command line with Gradle, run:

./gradlew run

This will execute the App class and print the results to the console.

2.7 Code Output

Alice
(no-name)
(unknown)

The output shows how java jspecify null safety helps avoid unexpected NullPointerException scenarios.

• For user u1, a valid display name (Alice) is returned.
• For user u2, where displayName is null, a safe fallback (no-name) is used.
• For a missing user, the service returns (unknown) instead of propagating null.

3. Conclusion

JSpecify provides a pragmatic path toward consistent nullness annotations across Java projects. It lowers the friction of using nullness annotations by proposing a small, interoperable spec that tooling can rely on. For meaningful results, combine JSpecify annotations with static analysis tools (NullAway, Error Prone, Checker Framework), a clear adoption plan, and CI enforcement. Start by annotating public APIs, add gradual checks, and iterate — the result will be fewer runtime null-pointer surprises and clearer API contracts.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.