Debian Codegraph @

src/main/java/org/jspecify/annotations/NullMarked.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.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 {}