| 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 {} |