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

I don't think those annotations come from Java Bean Validation's API. What library/framework are you using? Doesn't it have documentation for it's annotations? — Shivan Dragon, Sep 06 '12 at 13:51
Neither seems to be part of a regular Java API. Where are they implemented? — vainolo, Sep 06 '12 at 13:51
Updated the description. It is part of JSR-305 and the implementation I am using is FindBugs. — vitaly, Sep 06 '12 at 15:30
worth noting that bug " overriding @Nullable parameter" http://sourceforge.net/p/findbugs/bugs/1139/ has been fixed in findbugs. So we can override it with \@Nonull in implementations — Ronan Quillevere, Jan 17 '14 at 14:02

score 37 · Accepted Answer · edited May 23 '17 at 12:34

37

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.

edited May 23 '17 at 12:34

Community

1
1

answered Sep 06 '12 at 14:05

lbalazscs

17,474
7
42
50

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 Sep 06 '12 at 15:24
I cannot find any mention of @CheckForNull here: http://findbugs.sourceforge.net/bugDescriptions.html (@NonNull is there) – vitaly Sep 07 '12 at 07:07
@vitaly - FindBugs 2.0.1 reports the `@CheckForNull` violation as [`NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE`](http://findbugs.sourceforge.net/bugDescriptions.html#NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE). – David Harkness Sep 15 '12 at 00:51
`@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. – David Harkness Sep 15 '12 at 00:58
@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`. – vitaly Sep 17 '12 at 07:38
@vitaly - From a [summary of the nullness annotations](https://groups.google.com/forum/?fromgroups=#!topic/jsr-305/mU-HqM4jwtk), 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 Sep 17 '12 at 07:53

score 10 · Answer 2 · edited Jun 30 '19 at 15:25

10

@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());
    }
}

edited Jun 30 '19 at 15:25

Jared Burrows

54,294
25
151
185

answered Sep 06 '12 at 14:48

Alexander Pavlov

2,264
18
25

1

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 Sep 06 '12 at 14:51
1

FindBugs 2.0.1 detects the `@CheckForNull` case: "Possible null pointer dereference due to return value of called method." – David Harkness Sep 15 '12 at 00:49
@DavidHarkness - I can't reproduce it using 2.0.1: https://github.com/lischenko/flaming-ninja (see findbugs.null.analysis). findbugs-maven-plugin=v2.5.2 - the latest, annotations=2.0.1 – vitaly Sep 17 '12 at 07:13
@vitaly - I'm using the [Software Quality Environment plugin for NetBeans](http://kenai.com/projects/sqe/pages/Home) 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 Sep 17 '12 at 07:42
@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. – David Harkness Sep 17 '12 at 20:08
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. – Hakanai Jun 22 '15 at 03:17

score 5 · Answer 3 · edited Sep 20 '12 at 09:14

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.

javax.annotation: @Nullable vs @CheckForNull

3 Answers3

Linked