| 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.CONSTRUCTOR; |
| 19 |
import static java.lang.annotation.ElementType.METHOD; |
| 20 |
import static java.lang.annotation.ElementType.MODULE; |
| 21 |
import static java.lang.annotation.ElementType.PACKAGE; |
| 22 |
import static java.lang.annotation.ElementType.TYPE; |
| 23 |
import static java.lang.annotation.RetentionPolicy.RUNTIME; |
| 24 |
|
| 25 |
import java.lang.annotation.Documented; |
| 26 |
import java.lang.annotation.Retention; |
| 27 |
import java.lang.annotation.Target; |
| 28 |
|
| 29 |
/** |
| 30 |
* Indicates that the annotated element and the code transitively {@linkplain |
| 31 |
* javax.lang.model.element.Element#getEnclosedElements() enclosed} within it are <b>null-marked |
| 32 |
* code</b>: there, type usages are generally considered to exclude {@code null} as a value unless |
| 33 |
* specified otherwise. Using this annotation avoids the need to write {@link NonNull @NonNull} many |
| 34 |
* times throughout your code. |
| 35 |
* |
| 36 |
* <p>For a comprehensive introduction to JSpecify, please see <a |
| 37 |
* href="http://jspecify.org">jspecify.org</a>. |
| 38 |
* |
| 39 |
* <h2 id="effects">Effects of being null-marked</h2> |
| 40 |
* |
| 41 |
* <p>Within null-marked code, as a <i>general</i> rule, a type usage is considered non-null (to |
| 42 |
* exclude {@code null} as a value) unless explicitly annotated as {@link Nullable}. However, there |
| 43 |
* are several special cases to address. |
| 44 |
* |
| 45 |
* <h3 id="effects-special-cases">Special cases</h3> |
| 46 |
* |
| 47 |
* <p>Within null-marked code: |
| 48 |
* |
| 49 |
* <ul> |
| 50 |
* <li>We might expect the type represented by a <b>wildcard</b> (like the {@code ?} in {@code |
| 51 |
* List<?>}) to be non-null, but it isn't necessarily. It's non-null only if it {@code |
| 52 |
* extends} a non-null type (like in {@code List<? extends String>}), or if the <i>class</i> |
| 53 |
* in use accepts only non-null type arguments (such as if {@code List} were declared as |
| 54 |
* {@code class List<E extends String>}). But if {@code List} does accept nullable type |
| 55 |
* arguments, then the wildcards seen in {@code List<?>} and {@code List<? super String>} must |
| 56 |
* include {@code null}, because they have no "upper bound". (<a |
| 57 |
* href="https://bit.ly/3ppb8ZC">Why?</a>) |
| 58 |
* <ul> |
| 59 |
* <li>Conversely, a <b>type parameter</b> is always considered to have an upper bound; when |
| 60 |
* none is given explicitly, {@code Object} is filled in by the compiler. The example |
| 61 |
* {@code class MyList<E>} is interpreted identically to {@code class MyList<E extends |
| 62 |
* Object>}: in both cases the type argument in {@code MyList<@Nullable Foo>} is |
| 63 |
* out-of-bounds, so the list elements are always non-null. (<a |
| 64 |
* href="https://bit.ly/3ppb8ZC">Why?</a>) |
| 65 |
* </ul> |
| 66 |
* <li>Otherwise, being null-marked has no consequence for any type usage where {@code @Nullable} |
| 67 |
* and {@code @NonNull} are <a href="Nullable.html#applicability"><b>not applicable</b></a>, |
| 68 |
* such as the root type of a local variable declaration. |
| 69 |
* <li>When a type variable has a nullable upper bound, such as the {@code E} in {@code class |
| 70 |
* Foo<E extends @Nullable Bar>}), an unannotated usage of this type variable is not |
| 71 |
* considered nullable, non-null, or even of "unspecified" nullness. Rather it has |
| 72 |
* <b>parametric nullness</b>. In order to support both nullable and non-null type arguments |
| 73 |
* safely, the {@code E} type itself must be handled <i>strictly</i>: as if nullable when |
| 74 |
* "read from", but as if non-null when "written to". (Contrast with {@code class Foo<E |
| 75 |
* extends Bar>}, where usages of {@code E} are simply non-null, just like usages of {@code |
| 76 |
* String} are.) |
| 77 |
* <li>By using {@link NullUnmarked}, an element within null-marked code can be excluded and made |
| 78 |
* null-unmarked, exactly as if there were no enclosing {@code @NullMarked} element at all. |
| 79 |
* </ul> |
| 80 |
* |
| 81 |
* <h2 id="where">Where it can be used</h2> |
| 82 |
* |
| 83 |
* {@code @NullMarked} and {@link NullUnmarked @NullUnmarked} can be used on any package, class, |
| 84 |
* method, or constructor declaration; {@code @NullMarked} can be used on a module declaration as |
| 85 |
* well. Special considerations: |
| 86 |
* |
| 87 |
* <ul> |
| 88 |
* <li>To apply this annotation to an entire (single) <b>package</b>, create a <a |
| 89 |
* href="https://docs.oracle.com/javase/specs/jls/se19/html/jls-7.html#jls-7.4.1">{@code |
| 90 |
* package-info.java}</a> file there. This is recommended so that newly-created classes will |
| 91 |
* be null-marked by default. This annotation has no effect on "subpackages". <b>Warning</b>: |
| 92 |
* if the package does not belong to a module, be very careful: it can easily happen that |
| 93 |
* different versions of the package-info file are seen and used in different circumstances, |
| 94 |
* causing the same classes to be interpreted inconsistently. For example, a package-info file |
| 95 |
* from a {@code test} source path might hide the corresponding one from the {@code main} |
| 96 |
* source path, or generated code might be compiled without seeing a package-info file at all. |
| 97 |
* <li>Although Java permits it to be applied to a <b>record component</b> declaration (as in |
| 98 |
* {@code record Foo(@NullMarked String bar) {...}}), this annotation has no meaning when used |
| 99 |
* in that way. |
| 100 |
* <li>Applying this annotation to an instance <b>method</b> of a <i>generic</i> class is |
| 101 |
* acceptable, but is not recommended because it can lead to some confusing situations. |
| 102 |
* <li>An advantage of Java <b>modules</b> is that you can make a lot of code null-marked with |
| 103 |
* just a single annotation (before the {@code module} keyword). {@link NullUnmarked} is not |
| 104 |
* supported on modules, since it's already the default. |
| 105 |
* <li>If both {@code @NullMarked} and {@code @NullUnmarked} appear together on the same element, |
| 106 |
* <i>neither</i> one is recognized. |
| 107 |
* </ul> |
| 108 |
*/ |
| 109 |
@Documented |
| 110 |
@Target({MODULE, PACKAGE, TYPE, METHOD, CONSTRUCTOR}) |
| 111 |
@Retention(RUNTIME) |
| 112 |
public @interface NullMarked {} |