javax.annotation: @Nullable vs @CheckForNull

Question

What is the difference between the two? Both seem to mean that the value may be null and should be dealt with accordingly i.e. checked for null.

Update: The two annotations above are part of JSR-305/FindBugs: http://findbugs.sourceforge.net/manual/annotations.html

Solution 1

I think it is pretty clear from the link you added: if you use @CheckForNull and the code that uses the value does not check for null, FindBugs will show it as an error.

FindBugs will ignore @Nullable.

In practice this annotation is useful only for overriding an overarching NonNull annotation.

Use @CheckForNull in the cases when the value must always be checked. Use @Nullable where null might be OK.

EDIT: it seems that @CheckForNull is not well supported at the moment, so I suggest avoiding it and using @NonNull (also see Which @NotNull Java annotation should I use?). Another idea would be to get in touch directly with the FindBugs developers, and ask their opinion about the inconsistency in the documentation.

Solution 2

@Nonnull and @Nullable are correctly handled by IntelliJ IDEA. FindBugs found the problem with @Nonnull but missed those for @Nullable and @CheckForNUll. Problems which were detected by IDEA and FindBugs are marked with comments.

package com.db.icestation;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

public class test {

    @Nullable public String nullable() {
        return "";
    }

    @Nonnull public String nonnull() {
        return null; // IDEA, findbugs
    }

    @CheckForNull public String checkForNull() {
        return null;
    }

    public static void main(String[] args) {
        System.out.println(new test().nullable().length()); // IDEA
        System.out.println(new test().nonnull().length());
        System.out.println(new test().checkForNull().length());
    }
}

Solution 3

In the IntelliJ Idea @javax.annotation.Nullable is supported by default and any attempts to dereference @Nullable arguments or return values will result in warning.

@alexander-pavlov, You could add @javax.annotation.CheckForNull in configuration of "Constant conditions & exceptions" inspection. Go File->Settings->Inspections->Probable bugs->Constant conditions & exceptions->Configure annotations.

I prefer doing this as @CheckForNull has more clear meaning than @Nullable as @lbalazscs mentioned in his answer above.

Comments

[vitaly]

Eclipse finds exactly the same, provided that it is configured to perform 'Null analysis' and uses the correct annotations (by default it uses JDT annotations and not JSR-305). Interestingly, there is no configuration for @CheckForNull annotation (but it has @NonNullByDefault).

[vitaly]

The only warning I got from FindBugs after running the code from Alexander's answer is nonnull() may return null, but is declared @NonNull At test.java:[line 19] In method com.db.icestation.test.nonnull() The bug descriptions is Method may return null, but is declared @NonNull. This method may return a null value, but the method (or a superclass method which it overrides) is declared to return @NonNull. Bug kind and pattern: NP - NP_NONNULL_RETURN_VIOLATION

[vitaly]

I cannot find any mention of @CheckForNull here: findbugs.sourceforge.net/bugDescriptions.html (@NonNull is there)

[David Harkness]

FindBugs 2.0.1 detects the @CheckForNull case: "Possible null pointer dereference due to return value of called method."

[David Harkness]

@vitaly - FindBugs 2.0.1 reports the @CheckForNull violation as NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE.

[David Harkness]

@Nullable specifically tells FindBugs to ignore the possibility of null just as it does for all non-annotated references. I believe you should never need to use it except maybe to deal with third-party code you cannot modify.

[vitaly]

@DavidHarkness - I can't reproduce it using 2.0.1: github.com/lischenko/flaming-ninja (see findbugs.null.analysis). findbugs-maven-plugin=v2.5.2 - the latest, annotations=2.0.1

[vitaly]

@DavidHarkness Sorry, I am not quite sure I can follow. The @Nullable annotation helps in cases like System.out.println(new test().nullable().length()); from Alex' code. If I understand correctly, it specifically tells FindBugs to analyse possibility of null.

[David Harkness]

@vitaly - I'm using the Software Quality Environment plugin for NetBeans which includes FindBugs, and the message is tagged as coming from FindBugs. I included the 2.0.1 version in my project to get the annotations, but perhaps the plugin includes an older version (that works).

[David Harkness]

@vitaly - From a summary of the nullness annotations, Bill Pugh has this to say about @Nullable: "Because we allow for default annotations, we should also have an annotation that [is] exactly the same as having no nullness annotation of any kind." At the bottom he states the point is to allow for tools of varying strictness.

[David Harkness]

@vitaly - I installed FB 2.0.1 and have verified that it is not detecting the @CheckForNull annotation correctly. I cannot figure out which version of FB the SQE plugin uses.

[Hakanai]

If you use the JetBrains @NotNull annotation, IDEA instruments the code with added runtime checks, but if you use @Nonnull, it doesn't. I don't know about others, but that is pretty far from "correctly handled" in my opinion.