<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) GK Software AG and others 2014, 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
<title>Using null type annotations</title>
</head>
<body>
<h1> Using null type annotations </h1>
<p>
Starting with Java 8, null annotations can be used in a new and more powerful way,
because the new concept of "type annotations" (JSR 308) supports the use of 
annotations as an extension to the type system.
</p>
<p>
Technically, this is determined by two new elements in
the enum <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/annotation/ElementType.html"
    ><code>java.lang.annotation.ElementType</code></a>: <code>TYPE_USE</code> and
<code>TYPE_PARAMETER</code>. Notably, when saying <code>@Target(ElementType.TYPE_USE)</code>
the annotation thus marked can be attached basically to all usages of a type. 
</p>
<p>
By interpreting null annotations as part of the type system we interpret each
class or interface <code>Cn</code> in the system as introducing two distinct types: 
"<code>@NonNull Cn</code>" and "<code>@Nullable Cn</code>".
The former type contains all instances of <code>Cn</code> whereas the latter type
additionally contains the value <code>null</code>.
This implies that <code>@NonNull Cn</code> is a subtype of <code>@Nullable Cn</code>
with all regular consequences regarding assignability.
So ideally for every value in a program we will know if it can be null 
(and must be checked before dereference) or not.
The un-annotated type will be considered a legacy type just like raw types are legacy
types since the introduction of generics: a way for interfacing with old code,
to be flagged with warnings about unchecked conversions.
If we systematically avoid such legacy types, then the compiler can rigorously
flag <em>every</em> unsafe usage.
</p>
<p>
In order to achieve completeness of null analysis, checks regarding null type annotations
have been integrated with all type checking tasks of the compiler (active if null annotations
are enabled).
</p>
<p>
Users <em>migrating</em> from null annotations in previous versions to Java-8-style
null type annotations are advised to check the section about <a href="#compatibility">compatibility</a>.
</p>

<h2 id="generics">Generics</h2>
Perhaps the main advantage of type annotations for null analysis is the ability to annotate
the parameters and arguments of generic classes and interfaces.
Programmers only <em>using</em> generic classes may directly skip to the section on
<a href="#typeArguments">type arguments</a> but designers of generic classes should
take the time to understand the different implications of annotating these elements:
<ul>
<li><a href="#typeParameters">type parameters</a></li>
<li><a href="#typeVariables">type variables</a></li>
<li><a href="#typeArguments">type arguments</a></li>
</ul>
<h3 id="typeParameters">Type parameters</h3>
<p>
A generic class, interface or method may <em>declare</em> one or more type parameters.
Technically these are declarations, and hence it was a mere oversight that these cannot
be annotated in Java 5. 
In Java 8 an annotation can declare <code>@Target(ElementType.TYPE_PARAMETER)</code>
to be applicable in this position. JDT's null type annotations
<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNull.html"><code>@NonNull</code></a> and
<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/Nullable.html"><code>@Nullable</code></a>
are declared with
<code>@Target({ TYPE_USE })</code>, which includes usage on type parameter declarations.
</p>
<p>
With respect to null type annotations, each type parameter can be specified at one
of these levels:
</p>
<dl>
<dt><strong>unconstrained</strong></dt>
<dd>the type parameter does not impose any nullness-constraints on the arguments that
  a client my substitute for the type parameter.</dd>
<dt><strong>constrained by an upper bound</strong></dt>
<dd>the type parameter has an <code>extends</code> clause that specifies
  minimal nullness-requirements on type arguments provided by clients</dd>
<dt><strong>exactly specified</strong></dt>
<dd>the type parameter restricts usage to types of exactly one particular nullness</dd>
</dl>
<p>
Constraining a type parameter via an <strong>upper bound</strong> relies on the fact that each type
'<code>@NonNull Cn</code>' is a subtype of the corresponding type '<code>@Nullable Cn</code>'.
Hence, a <code>@Nullable</code> upper bound does not impose any restriction, whereas a
<code>@NonNull</code> upper bound prohibits the substitution by a <code>@Nullable</code>
type argument:
<pre>    // declarations:
    class C0&lt;T0 extends @Nullable Object&gt; {} // meaningless, no constraint imposed
    class C1&lt;T1 extends @NonNull Object&gt; {}
    ...
    // usage:
    C1&lt;@NonNull String&gt; c1String;  // legal
    C1&lt;@Nullable String&gt; c1String; // illegal
</pre>
<p>
For <strong>exact specification</strong> a null annotation may be attached to the type parameter
declaration itself, which is interpreted as defining both an upper and a lower bound.
In other words, only types with the exact same null type annotation are legal as type arguments:
</p>
<pre>    // declaration:
    class C2&lt;@Nullable T2&gt; {}
    ...
    // usage:
    C2&lt;@NonNull String&gt; c2String;  // illegal
    C2&lt;@Nullable String&gt; c2String; // legal
</pre>
<p>
Given the asymmetry, that in Java a type parameter may declare only upper bounds but
no lower bounds, the following three styles can be recommended:
<ul>
<li>Use a <code>@NonNull</code> upper bound for constraining type arguments to nonnull types.</li>
<li>Directly specify a type parameter as <code>@Nullable</code> for constraining type arguments to nullable types.</li>
<li>Use an unconstrained type parameter to support type arguments of either nullness.</li>
</ul>
<h3 id="typeVariables">Type variables</h3>
<p>
Within the scope of a generic declaration (class, interface or method), the name of a
type parameter can be used as a <em>type variable</em>, i.e., a placeholder for a type
that is not known at this point.
</p>
<p>
A type variable will typically be used without (further) null annotations, which implies
that the annotations from the type parameter declaration will apply as detailed below.
In some situations, however, it is useful to annotate an individual use of a type variable.
As an example consider the library method <code>java.util.Map.get(Object)</code>,
which should actually be annotated like this:
</p>
<pre>    @Nullable V get(Object key)</pre>
<p>
By this declaration we would indicate that the return type is <strong>the nullable variant
of whatever type V may represent</strong>. In other words, a null annotation on the use
of a type variable <em>overrides</em> any other null information that would otherwise
apply to this type. In particular any null annotation on the corresponding type parameter
declaration (or its bound) is overridden by a null annotation in this position.
</p>
<p>
On the other hand, when using a type variable without immediate null annotations the following rules apply
depending on the declaration of the corresponding type parameter:
</p>
<p>
A type variable corresponding to a type parameter with a <strong><code>@NonNull</code> upper bound</strong>
denotes a type that is <em>known to be nonnull</em>.
</p>
<pre>    class C1&lt;T1 extends @NonNull Number&gt; {
        int consume(T1 t) {
            return t.intValue(); // OK since T1 is known to be nonnull
        }
        T1 provide() {
            return null;         // NOT OK since T1 requires nonnull
        }
    }
</pre>
<p>
A type variable corresponding to a type parameter <strong>specified as <code>@Nullable</code></strong>
denotes a type that is <em>known to be nullable</em>.
</p>
<pre>    class C2&lt;@Nullable T2 extends Number&gt; {
        int consume(T2 t) {
            return t.intValue(); // NOT OK since T2 is known to be nullable
        }
        T2 provide() {
            return null;         // OK: returning null is legal
        }
    }
</pre>
<p>
A type variable corresponding to an <strong>unconstrained</strong> type parameter requires <strong>pessimistic
checking</strong> in order to guarantee safety with all legal substitutions: this type can
neither be assumed to be nullable nor nonnull.
</p>
<pre>    class C&lt;T extends Number&gt; {
        int consume(T t) {
            return t.intValue(); // NOT OK since T could be nullable
        }
        T provide() {
            return null;         // NOT OK since T could require nonnull
        }
    }
</pre>
<p>
The last point may look surprising at first, but please see that an unconstrained type parameter
implies that we may not assume anything about the nullness of the type represented by
the corresponding type variable. Even more: we must actively support nullable <em>and</em>
nonnull types. On the other hand this simply extends the existing rule that the only
type being compatible with an unbounded type variable is the type variable itself.
To explain this situation in the context of null analysis, the compiler will raise the 
following error against the return in <code>provide()</code>:
</p>
<blockquote>
Null type mismatch (type annotations): 'null' is not compatible to the free type variable 'T'
</blockquote>
<p>
By enforcing this defensive strategy regarding unconstrained type parameters we obtain the benefit
of allowing clients to freely choose the rules for a particular generic instantiation,
as will be shown next.
</p>
<h3 id="typeArguments">Type arguments</h3>
<p>
When instantiating a generic type or when invoking a generic method, the constraints put
forward by the type parameter must be observed. Hence, when a provider of a generic type or method
specified the required nullness, this must be obeyed and the compiler will flag any violations.
</p>
<p>
When, on the other hand, a type parameter does not impose any restrictions, a client may
freely choose the nullness of his type arguments:
<pre>
    int processWithoutNulls (@NonNull List&lt;<strong>@NonNull Integer</strong>&gt; ints) {
        int result = 0;
        for (int i = 0; i &lt; ints.size(); i++) {
            Integer element = ints.get(i);
            result += element.intValue(); // OK: list element is known to be nonnull
            ints.set(i, null);            // NOT OK: list does not accept null value
        }
        return result;
    }
    int processWithNulls (@NonNull List&lt;<strong>@Nullable Integer</strong>&gt; ints) {
        int result = 0;
        for (int i = 0; i &lt; ints.size(); i++) {
            Integer element = ints.get(i);
            result += element.intValue(); // NOT OK: list element can be null
            ints.set(i, null);            // OK: list accepts null value
        }
        return result;
    }
</pre>

<h2 id="inference">Inference</h2>
<p>
With null type annotations affecting type arguments, the language features one
more location amenable to inference: during type inference for the invocation
of a generic method (lambda expression etc.), type inference shyly attempts to
also infer the appropriate null type annotations. Example:
</p>
<pre>    &lt;T&gt; T check(T in) { return in; }
    void test(@NonNull List&lt;@Nullable String&gt; someStrings) {
        @NonNull List&lt;@Nullable String&gt; checked;
        checked = check(someStrings); // inferring types for this invocation
        ...
    }
</pre>
<p>
In this trivial example, inference will indeed instantiate the generic parameter <code>&lt;T&gt;</code>
to <code>@NonNull List&lt;@Nullable String&gt;</code>. More complex scenarios are inferred, too,
but no guarantee is made, that a possible solution will always be found. In case inference fails
to infer suitable null type annotations, users are advised to revert to explicitly specify 
type arguments even of a generic method invocation.
</p>

<h2 id="more_locations">More locations</h2>
<h3>Cast and instanceof</h3>
<p>
Syntactically, type annotations can be used also in casts and instanceof expressions.
For null annotations, however, this has limited value.
</p>
<p>
<strong>Casting</strong> to a null-annotated type is always an <em>unchecked cast</em> because the
compiler is not allowed to insert runtime checks that would make the cast meaningful.
If a runtime check is desired, please consider using a small helper function like:
</p>
<pre>    static @NonNull &lt;T&gt; T castToNonNull(@Nullable T value, @Nullable String msg) {
        if (value == null) throw new NullPointerException(msg);
        return value;
    }
</pre>
<p>
Casts affecting the type arguments of a generic type will always be unchecked casts due to erasure.
</p>
<p>
<strong>instanceof</strong> checks with null type annotations are not meaningful.
Hence the compiler flags this as illegal usage of a null type annotation.
</p>
<h3>Locations that are nonnull by definition</h3>
<p>
Syntactically, type annotations can also be used for
</p>
<ul>
<li>allocation expressions</li>
<li>method receiver (pseudo argument by the name of <strong>this</strong>)</li>
<li>catch parameter</li>
</ul>
<p>
In each of these constructs, the type is nonnull by definition.
Hence a null type annotation in one of these positions is flagged as illegal use.
This doesn't, however, restrict the use of null type annotations on type arguments
of the given type.
</p>

<h2 id="compatibility">Compatibility</h2>
<p>
Migrating from declaration annotations to type annotations has a few unavoidable
implications, regarding the syntax, regarding project configuration and regarding
the semantics.
</p>
<h3 id="compatibility_syntax">Syntax</h3>
<p>
For two constructs the JLS introduces a syntactic change:
</p>
<table border="1" cellspacing="0" cellpadding="5" summary="Syntax Changes">
<tr><th>Declaration Annotations (Java 7 or below)</th><th>Type Annotation (Java 8)</th></tr>
<tr><td><code>@NonNull String[]</code></td><td><code>String @NonNull[]</code></td></tr>
<tr><td><code>@NonNull java.lang.String</code></td><td><code>java.lang.@NonNull String</code></td></tr>
</table>
<p>
In both cases the new syntax has been introduced to provide more options.
</p>
<p>
For <strong>arrays</strong> a type annotation before the leaf element type will now denote
an array whose individual cells have the given nullness - here: cells cannot be null.
In Java 7 and below the same syntax expressed a property of the corresponding variable
and hence captured the nullness of the array itself.
To express the same using Java-8 type annotations, viz. that the array itself can or cannot be null,
the type annotation is placed before the square brackets denoting the array dimensions.
This implies that the old syntax is still valid, but its meaning has changed:
</p>
<pre>
    // annotated leaf type:
    @NonNull Object [] o1;
    o1 = null;          // OK
    o1 = new Object[1];
    o1[0] = null;       // NOT OK
    ...
    // annotated array type:
    Object @NonNull[] o2;
    o2 = null;          // NOT OK
    o2 = new Object[1];
    o2[0] = null;       // OK
    ...
    // multi-dimensional array:
    Object @NonNull[] @Nullable[] o3;
    o3 = null;          // NOT OK, outer array is nonnull
    o3 = new Object[1] @Nullable[];
    o3[0] = null;       // OK, inner array is nullable
</pre>
<p>
Unfortunately, checking proper initialization of an array with nonnull content
is beyond the capabilities of JDT's static analysis.
</p>
<p>
For <strong>qualified type names</strong> the type annotation must be placed directly preceding the
actual type name. This way it is possible to give different type annotations for
inner classes and their enclosing like in <code>org.project.@Immutable Outer.@Nullable Inner</code>.
This distinction, however, is not useful for null annotations, because the enclosing
of a non-static inner class is by definition always non-null. Users of null type
annotations only need to understand that the old syntax for this case is illegal
for type annotations and how to convert this into legal Java 8 code (see the table above).
</p>
<h3 id="compatibility_configuration">Project configuration</h3>
<p>
Properly designed annotation types can be distinguished by looking at their <code>@Target</code>
declaration (the use of null annotations lacking a <code>@Target</code> declaration is discouraged).
To support both styles of annotations, JDT has published a major update of the annotation
bundle <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/package-summary.html"><code>org.eclipse.jdt.annotation</code></a>: 
Versions 1.1.x are old style declaration annotations; versions 2.0.0 and onward are type annotations.
By increasing the major version an incompatibility is signaled. Users are advised to
reference this library with an explicit version range, either <code>[1.1.0,2.0.0)</code>
for declaration annotations or <code>[2.0.0,3.0.0)</code> for type annotations.
</p>
<p>
The exact configuration depends of course on the flavor of project:
<dl>
<dt>Plain Java</dt>
<dd>JDT continues to offer a quickfix for copying the annotation library into the
project. The version will be determined by the compliance settings of the project.</dd>
<dt>Maven</dt>
<dd>Both versions of the annotation bundle will be published to <code>repo.eclipse.org</code>,
from where they can be consumed using the regular maven mechanisms: be sure to specify
the correct version; specifying <code>&lt;scope&gt;compile&lt;/scope&gt;</code> is recommended
for this dependency.</dd>
<dt>OSGi / Eclipse</dt>
<dd>When developing OSGi bundles / Eclipse plugins the version range should be specified as
mentioned above. Unfortunately, OSGi doesn't support a concept of compile time dependencies.
The PDE specific mechanism in file <code>build.properties</code> is problematic because
it doesn't support specifying a version range. Thus the best approximation of the desired
semantics is to use a <code>Require-Bundle</code> dependency. 
qualified with <code>resolution:=optional</code> in order to avoid forcing this dependency
on the runtime:
<pre>
Require-Bundle: ...,
 org.eclipse.jdt.annotation;bundle-version="[2.0.0,3.0.0)";resolution:=optional
</pre></dd>
</dl>
<h3 id="compatibility_semantics">Semantics &ndash; NonNullByDefault</h3>
<p>
While the fundamental semantics of null annotation remains unchanged,
the annotation <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
	><code>@NonNullByDefault</code></a> has been changed slightly:
<ul>
<li>This annotation can now affect more locations.</li>
<li>The locations to be affected can be fine tuned using the 
<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html#value--"
	><code>value</code></a> property of the annotation
	(see also the enum <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/DefaultLocation.html"
	><code>DefaultLocation</code></a>).</li>
<li>As a consequence, the notation for canceling a default from an outer scope has been changed, too:
<table border="1" cellspacing="0" cellpadding="5" summary="Cancelling a default">
<tr><th>Declaration Annotations (Java 7 or below)</th><th>Type Annotation (Java 8)</th></tr>
<tr><td><code>@NonNullByDefault(false)</code></td><td><code>@NonNullByDefault({})</code></td></tr>
</table>
</li>
</ul>
Although the Java 8 variant of
	 <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
	><code>@NonNullByDefault</code></a> affects more locations, two noteworthy exceptions exist
	(as specified in <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/DefaultLocation.html"
	><code>DefaultLocation</code></a>):
<blockquote>
	<strong>
	Wildcards and the use of type variables are always excluded from 
	<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
	><code>@NonNullByDefault</code></a>.
	</strong>
</blockquote>
<p>
By this rule, type variables and wildcards retain their intended properties as "unknowns" also in terms of nullness,
even when they appear in the context of 
	<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
	><code>@NonNullByDefault</code></a>.
</p>

<h2 id="compiler_messages_explained">Compiler messages explained</h2>
<p>
In addition to
<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm#compiler_messages_explained"
>compiler messages of the previous version</a> the following messages may be issued,
if null type annotations are enabled for analysis:
</p>

<h3>General null type mismatch</h3>
<dl>
<dt><font color="SaddleBrown">Null type mismatch (type annotations): required 'X' but this expression has type 'Y'</font></dt>
<dd>In an assignment context null type annotations don't match.
	Note that the mismatch may relate to any detail of the type (type argument, array element), not necessarily to the main type.</dd>
</dl>
<p>
All mismatches detected based on type annotations are prefixed with "<code>Null type mismatch (type annotations)</code>".
</p>
	
<h3>Various expressions</h3>
<dl>
<dt><font color="SaddleBrown">Potential null pointer access: array element may be null</font></dt>
<dd>An array element is dereferenced, where the array type declares its elements as <code>@Nullable</code>.</dd>
<dt><font color="SaddleBrown">Potential null pointer access: this expression has a '@Nullable' type</font></dt>
<dd>Any expression at the left hand side of a dot has a type that is declared to be nullable.</dd>
<dt><font color="SaddleBrown">Redundant null check: comparing '@NonNull X' against null</font></dt>
<dd>An arbitrary expression known to have a @NonNull type is unnecessarily being compared against null.</dd>
</dl>

<h3>Unchecked conversions</h3>
<dl>
<dt><font color="SaddleBrown">Null type safety (type annotations): The expression of type 'X' needs unchecked conversion to conform to '@NonNull X'</font></dt>
<dd>A value of an un-annotated type is being assigned to a variable of an annotated type.
	Note that the mismatch may relate to any detail of the type (type argument, array element), not necessarily to the main type.</dd>
<dt><font color="SaddleBrown">Null type safety: Unchecked cast from X to '@N Y'</font></dt>
<dd>A value is casted to a null-annotated type, where the nullness is not checked at runtime by the cast.</dd>
</dl>

<h3>Problems specific to generics</h3>
<dl>
<dt><font color="SaddleBrown">Null constraint mismatch: The type 'X' is not a valid substitute for the type parameter 'T'</font></dt>
<dd>Here the type parameter <code>&lt;T&gt;</code> has a constraint in one of the forms mentioned <a href="#typeParameters">above</a>.
	The actual type argument <code>X</code>, however, doesn't conform to this constraint.</dd>
<dt><font color="SaddleBrown">This nullness annotation conflicts with a '@N' annotation which is effective on the same type parameter</font></dt>
<dd>A null annotation on a bound of a type parameter conflicts with another null annotation on another bound or on the type parameter itself.</dd>
<dt><font color="SaddleBrown">Null type mismatch (type annotations): ''null'' is not compatible to the free type variable 'T'</font></dt>
<dd>An attempt is made to assing <code>null</code> to a variable typed to an unconstrained type variable,
	 see the section on <a href="#typeVariables">type variables</a></dd>
<dt><font color="SaddleBrown">Null type mismatch (type annotations): required 'T' but this expression has type '@Nullable T', where 'T' is a free type variable</font></dt>
<dd>An attempt is made to assign a value of a nullable type to a variable typed to an unconstrained type variabled,
	 see the section on <a href="#typeVariables">type variables</a></dd>
<dt><font color="SaddleBrown">Contradictory null annotations: method was inferred as 'T foo(X)', but only one of '@NonNull' and '@Nullable' can be effective at any location</font></dt>
<dd>Type inference for a generic method invocation has produced a signature in which contradictory null annotations clash on the same element.<dd>
</dl>

<h3>Lambda expressions and method references</h3>
For any mismatches in null annotations affecting lambda expressions or method references the corresponding
"descriptor" is mentioned (the single abstract method being implemented by the lambda / method reference).
This is usefull for finding the origin of a null annotation that is not explicit at the current expression.


</body>
</html>