Specifying nullness

Null annotations in method signatures can be interpreted as null contracts, however, a more general approach considers null annotations as an extension of the type system. Since the availability of JSR 308 all type references should either include or exclude null, which allows for complete checking of any possible dereferencing of null. In other words, a fully annotated program which passes the type checker will never raise an NPE at runtime.

To achieve this guarantee two annotations are used. The specific annotations types can be selected as a preference, but the following defaults are provided:

For any variable who's type is annotated with @NonNull (or the configured equivalent) the following rules apply:

It is illegal to bind null or a value that can be null to the variable. (For fields and local variables this applies to initialization and assignments, for method argument binding a value means to pass an actual argument in a method call).

It is legal and safe to dereference such a variable for accessing a field or a method of the bound object.

For any variable who's type is annotated with @Nullable (or the configured equivalent) the following rules apply:

It is legal to bind null or a value that can be null to the variable (see details above).

It is illegal to dereference such a variable for either field or method access.

The above rules imply that the value from a @NonNull variable can be bound to a variable annotated with @Nullable, but the opposite direction is generally illegal.
Only after an explicit null check can a @Nullable variable be treated as being @NonNull for the sake of binding to another @NonNull variable or for dereferencing. For fields the situation is actually more complex — please read "The case of fields".

For Plug-in projects it is recommended to add an optional, versioned dependency to the bundle org.eclipse.jdt.annotation

Define @NonNull as the default at the granularity of your choice (package/type):

package: add a file package-info.java with contents like this:

@NonNullByDefault package org.my.pack.age;

type: add @NonNullByDefault to the type declaration.

At this point you should see plenty of new errors and warnings

Hints:Setting the default to @NonNull is the recommended option for new projects, but for existing projects this could require a major clean-up in terms of inserting explicit @Nullable annotations in many locations. Experience shows, that this is a non-trivial task since in existing code the original intention, which parameter/return value should be allowed to be null, is usually blurred. Here starting with no default but adding individual annotations where the intention is clear will cause less disruption. This incremental approach should be seen as a long-term yet low effort task, not only for getting rid of NPEs but also for sorting the responsibilities in the code, which may have eroded over time.For more hints on adpoting these annotations see Adoption Null Annotations.

Cleaning up

When applying the new analysis to a big existing project, the sheer number of new problems may look intimidating but that's where quick fixes will come to the rescue.
Currently the following problems offer a quickfix:

Note, that some quick fixes require to modify another compilation unit (file) than the one
where the problem was observed. For these quickfixes the current implementation doesn't
support fixing several equal issues in bulk (for the technical background see
bug 337977).

Defaults at different levels

If no null annotations are used, the compiler uses the original Java semantics,
where the following is legal for all variables of reference types:

assign null, and

dereference without check.

To generally avoid these weak semantics you may want to declare that by default all types should be considered as nonnull.

This is done using the annotation 'NonNullByDefault'. The qualified type
name of this annotation can be configured using the preference "'NonNullByDefault' annotation".
The built-in value for these preference is org.eclipse.jdt.annotation.NonNullByDefault.

This annotation takes an optional parameter that can be used to cancel a default that may possible apply at the current location. This is useful when, e.g., sub-classing a legacy class without null annotation, where the sub-class sits in a place that would otherwise apply non-null as the default, which would make all overrides incompatible with inherited methods.

When using version 1.x of org.eclipse.jdt.annotation specify false as the annotation argument.

When using version 2.x of org.eclipse.jdt.annotation specify {} as the annotation argument.

This annotation can be applied to any package, Java type or method, and has the following effect:

Java ≤ 1.7

The annotation affects all method returns and parameters with undefined null status within their scope.