not annotated method overrides method annotated with @nonnullapi

ELiv 2025

3 min read

·

06-03-2025

10

0

Share

This article explores the complexities and potential pitfalls of overriding a method annotated with @NonNullApi in Java without using the same annotation on the overriding method. We'll delve into the implications for null safety and best practices for maintaining code clarity and preventing runtime exceptions.

Understanding @NonNullApi

The @NonNullApi annotation, introduced as part of the Checker Framework, is a powerful tool for enhancing null safety in Java code. When applied to a class or package, it signifies that methods within that scope are expected to not return null unless explicitly documented otherwise. This helps improve code readability and reduces the risk of NullPointerExceptions.

However, using @NonNullApi requires careful consideration when dealing with inheritance and method overriding.

The Problem: Inconsistent Annotations

The core issue arises when a method annotated with @NonNullApi in a superclass is overridden in a subclass without the @NonNullApi annotation. This creates an inconsistency: the superclass guarantees (or strongly suggests) non-null return values, while the subclass offers no such guarantee.

This inconsistency can lead to unexpected behavior and, critically, potential NullPointerExceptions at runtime. A caller expecting a non-null value from the superclass's method might receive null from the subclass's override, causing a program crash.

Example Scenario

Let's illustrate with a simple example:

// Superclass with @NonNullApi annotation
@NonNullApi
class ParentClass {
    public String getName() {
        return "Parent"; // Always returns a non-null string
    }
}

// Subclass without @NonNullApi annotation
class ChildClass extends ParentClass {
    @Override
    public String getName() {
        return null; // Potentially returns null!
    }
}

public class Main {
    public static void main(String[] args) {
        ChildClass child = new ChildClass();
        String name = child.getName();
        System.out.println(name.length()); // Potential NullPointerException here!
    }
}

In this scenario, the getName() method in ChildClass overrides the getName() method in ParentClass. However, the lack of @NonNullApi in ChildClass breaks the implicit contract established by the superclass. The NullPointerException will occur when name.length() is called if getName() returns null.

Best Practices and Solutions

The ideal solution is to maintain consistency in null handling across the inheritance hierarchy. If a method in a superclass annotated with @NonNullApi is overridden, the overriding method should also be annotated with @NonNullApi (or use a suitable alternative annotation such as @Nullable).

1. Annotate the Overriding Method:

The simplest and most effective solution is to explicitly add @NonNullApi to the overriding method in the subclass:

@NonNullApi
class ChildClass extends ParentClass {
    @Override
    public String getName() {
        return null; // Compiler error – explicitly indicates a violation of @NonNullApi
    }
}

This will result in a compiler error (if you're using a tool that enforces @NonNullApi), highlighting the potential null return and forcing you to address it correctly.

2. Handle Nulls Explicitly:

If the overriding method legitimately needs to return null, explicitly handle this possibility within the code, perhaps by throwing an exception or returning a default value:

class ChildClass extends ParentClass {
    @Override
    public String getName() {
        // ... some logic that might result in null ...
        if(someCondition) {
            return null;
        } else {
            return "Child";
        }
    }
}

3. Re-evaluate the @NonNullApi Annotation:

If the @NonNullApi annotation on the superclass method is too restrictive for the subclass, consider removing it from the superclass or refining the contract to allow nulls where appropriate. This should be done carefully and only if necessary, as it could introduce null safety issues elsewhere in the codebase.

Conclusion

Overriding methods annotated with @NonNullApi requires careful attention to null safety. Maintaining consistent annotation across the inheritance hierarchy (or handling nulls explicitly) is crucial to prevent runtime exceptions and maintain code clarity. Always prioritize clarity and explicitly address null handling to avoid unexpected behavior and maintain robust, reliable software.