Debian Codegraph @

src/main/java/org/jspecify/annotations/Nullable.java

raw
1 /*
2 * Copyright 2018-2020 The JSpecify Authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.jspecify.annotations;
17
18 import static java.lang.annotation.ElementType.TYPE_USE;
19 import static java.lang.annotation.RetentionPolicy.RUNTIME;
20
21 import java.lang.annotation.Documented;
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.Target;
24
25 /**
26 * Indicates that the annotated <a href="https://github.com/jspecify/jspecify/wiki/type-usages">type
27 * usage</a> (commonly a parameter type or return type) is considered to include {@code null} as a
28 * value.
29 *
30 * <p>Example usages:
31 *
32 * <pre>{@code
33 * @Nullable String field;
34 *
35 * @Nullable String getField() { return field; }
36 *
37 * void setField(@Nullable String value) { field = value; }
38 *
39 * List<@Nullable String> getList() { … }
40 * }</pre>
41 *
42 * <p>For a comprehensive introduction to JSpecify, please see <a
43 * href="http://jspecify.org">jspecify.org</a>.
44 *
45 * <h2>Meaning per each kind of type usage</h2>
46 *
47 * <p>The essential meaning of this annotation is always the same: the type it annotates is
48 * considered to include {@code null} as a value. But this may affect your code a little differently
49 * based on the kind of type usage involved.
50 *
51 * <ul>
52 * <li>On a <b>parameter type</b>: The {@code setField} method (at top) permissively accepts a
53 * "string-or-null", meaning that it is okay to pass an actual string, or to pass {@code
54 * null}. (This doesn't guarantee that passing {@code null} won't produce an exception at
55 * runtime, but it should be much less likely.) This also applies to the type of a lambda
56 * expression parameter, if that type is given explicitly (otherwise its nullness must be
57 * inferred from context).
58 * <li>On a <b>method return type</b>: The {@code getField} method returns a "string-or-null", so
59 * while the caller might get a string back, it should also address the possibility of getting
60 * {@code null} instead. (This doesn't guarantee there is any circumstance in which {@code
61 * null} <i>will</i> actually be returned.)
62 * <li>On a <b>field type</b>: The {@code field} field has the type "string-or-null", so at times
63 * it might hold a string, and at times it might hold {@code null}. (Of course, every field of
64 * a reference type <i>originally</i> holds {@code null}, but as long as the class ensures
65 * that its uninitialized states can't be observed, it's appropriate to overlook that fact.)
66 * <li>On a <b>type argument</b>: A type usage of "nullable string" appears <i>within</i> the
67 * compound type {@code List<@Nullable String>}. No matter how this type is used (return type,
68 * etc.), this means the same thing: every appearance of {@code E} in {@code List}'s member
69 * signatures will be considered nullable. For a list, this means it may contain null
70 * <i>elements</i>. If the list reference itself might be null as well, we can write
71 * {@code @Nullable List<@Nullable String>}, a "nullable list of nullable strings".
72 * <li>On the upper bound of a <b>type parameter</b>: For example, as seen in {@code class List<E
73 * extends @Nullable Object>}. This means that a <i>type argument</i> supplied for that type
74 * parameter is permitted to be nullable if desired: {@code List<@Nullable String>}. (A
75 * non-null type argument, as in {@code List<String>}, is permitted either way.)
76 * <li>On a usage of a <b>type variable</b>: A type parameter, like the {@code E} in {@code
77 * interface List<E>}, defines a "type variable" of the same name, usable only <i>within</i>
78 * the scope of the declaring API element. In any example using {@code String} above, a type
79 * variable like {@code E} might appear instead. {@code @Nullable} continues to mean "or null"
80 * as always, but notably, this works without regard to whether the type argument is
81 * <i>already</i> nullable. For example, suppose that {@code class Foo<E extends @Nullable
82 * Object>} has a method {@code @Nullable E eOrNull()}. Then, whether {@code foo} is of type
83 * {@code Foo<String>} or {@code Foo<@Nullable String>}, the expression {@code foo.eOrNull()}
84 * is nullable either way. Using {@code @Nullable E} in this way is called "nullable
85 * projection" (<a href="NonNull.html#projection">non-null projection</a> is likewise
86 * supported, but less commonly useful).
87 * <li>On a <b>nested type</b>: In most examples above, in place of {@code String} we might use a
88 * nested type such as {@code Map.Entry}. The Java syntax for annotating such a type as
89 * nullable looks like {@code Map.@Nullable Entry}.
90 * <li>On a <b>record component</b>: As expected, {@code @Nullable} here applies equally to the
91 * corresponding parameter type of the canonical constructor, and to the return type of a
92 * generated accessor method as well. If an explicit accessor method is provided for this
93 * record component, it must still be annotated explicitly. Any non-null components should be
94 * checked (for example using {@link java.util.Objects#requireNonNull}) in a <a
95 * href="https://docs.oracle.com/en/java/javase/19/language/records.html">compact
96 * constructor</a>.
97 * </ul>
98 *
99 * <h2 id="applicability">Where it is applicable</h2>
100 *
101 * <p>This annotation and {@link NonNull} are applicable to any <a
102 * href="https://github.com/jspecify/jspecify/wiki/type-usages">type usage</a> <b>except</b> the
103 * following cases, where they have no defined meaning:
104 *
105 * <ul>
106 * <li>On any<b> intrinsically non-null type usage</b>. Some type usages are incapable of
107 * including {@code null} by the rules of the Java language. Examples include any usage of a
108 * primitive type, the argument to {@code instanceof}, a method return type in an annotation
109 * interface, or the type following {@code throws} or {@code catch}. In such locations, a
110 * nullness annotation could only be contradictory ({@code @Nullable}) or redundant
111 * ({@code @NonNull}).
112 * <li>On the root type of a <b>local variable</b> declaration. The nullness of a local variable
113 * itself is not a fixed declarative property of its <i>type</i>. Rather it should be inferred
114 * from the nullness of each expression assigned to the variable, possibly changing over time.
115 * (<a href="https://bit.ly/3ppb8ZC">Why?</a>). Subcomponents of the type (type arguments,
116 * array component types) are annotatable as usual.
117 * <li>On the root type in a <b>cast expression</b>. To inform an analyzer that an expression it
118 * sees as nullable is truly non-null, use an assertion or a method like {@link
119 * java.util.Objects#requireNonNull}. (<a href="https://bit.ly/3ppb8ZC">Why?</a>)
120 * Subcomponents of the type (type arguments, array component types) are annotatable as usual.
121 * <li>On any part of a <b>receiver parameter</b> type (<a
122 * href="https://docs.oracle.com/javase/specs/jls/se18/html/jls-8.html#jls-8.4">JLS 8.4</a>).
123 * <li>If both {@code @Nullable} and {@code @NonNull} appear on the same type usage,
124 * <i>neither</i> one is recognized.
125 * </ul>
126 *
127 * Whether the code is {@link NullMarked} also has no consequence in the above locations.
128 *
129 * <h2>Unannotated type usages</h2>
130 *
131 * <p>For a type usage where nullness annotations are <a href="#applicability">applicable</a> but
132 * not present, its nullness depends on whether it appears within {@linkplain NullMarked
133 * null-marked} code; see that class for details. Note in particular that nullness information from
134 * a superclass is never automatically "inherited".
135 */
136 @Documented
137 @Target(TYPE_USE)
138 @Retention(RUNTIME)
139 public @interface Nullable {}