Debian Codegraph @

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

raw
1 /*
2 * Copyright 2022 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 <i>exclude</i> {@code null}
28 * as a value; rarely needed within {@linkplain NullMarked null-marked} code.
29 *
30 * <p>This annotation serves two primary purposes:
31 *
32 * <ul>
33 * <li>To mark any sporadic non-null type usages inside a scope that is not ready to be fully
34 * {@link NullMarked} yet.
35 * <li>To perform a <i>non-null projection</i> of a type variable, explained below.
36 * </ul>
37 *
38 * <p>For a comprehensive introduction to JSpecify, please see <a
39 * href="http://jspecify.org">jspecify.org</a>.
40 *
41 * <h2 id="projection">Non-null projection</h2>
42 *
43 * <p>In the following example, {@code MyOptional}'s type parameter {@code T} accepts only non-null
44 * type arguments, but {@code MyList}'s type parameter {@code E} will accept either a non-null or
45 * nullable type argument.
46 *
47 * <pre>{@code
48 * // All the below is null-marked code
49 *
50 * class MyOptional<T> { … }
51 *
52 * interface MyList<E extends @Nullable Object> {
53 * // Returns the first non-null element, if such element exists.
54 * MyOptional<E> firstNonNull() { … } // problem here!
55 * }
56 *
57 * MyList<@Nullable String> maybeNulls = …
58 * MyList<String> nonNulls = …
59 * }</pre>
60 *
61 * <p>Because {@code MyOptional} accepts only non-null type arguments, we need both {@code
62 * maybeNulls.firstNonNull()} and {@code nonNulls.firstNonNull()} to produce the same return type:
63 * {@code MyOptional!<String!>} (see <a
64 * href="https://github.com/jspecify/jspecify/wiki/notation#shorthand-notation">notation</a>).
65 * However, as specified above, they won't do that. In fact, there is a problem with the {@code
66 * firstNonNull} signature, since the type argument {@code String?} would not meet the requirements
67 * of {@code MyOptional}'s type parameter.
68 *
69 * <p>The solution is to <b>project</b> the type argument to its non-null counterpart:
70 *
71 * <pre>{@code
72 * // Returns the first non-null element, if such element exists.
73 * MyOptional<@NonNull E> firstNonNull() { … } // problem fixed!
74 * }</pre>
75 *
76 * <p>Here, {@code @NonNull E} selects the non-null form of the type argument, whether it was
77 * already non-null or not, which is just what we need in this scenario.
78 *
79 * <p>If {@code E} has a non-null upper bound, then the apparent projection {@code @NonNull E} is
80 * redundant but harmless.
81 *
82 * <p><a href="Nullable.html#projection">Nullable projection</a> serves the equivalent purpose in
83 * the opposite direction, and is far more commonly useful.
84 *
85 * <p>If a type variable has <i>all</i> its usages being projected in one direction or the other, it
86 * should be given a non-null upper bound, and any non-null projections can then be removed.
87 *
88 * <h2>Where it is applicable</h2>
89 *
90 * <p>{@code @NonNull} is applicable in all the <a href="Nullable.html#applicability">same
91 * locations</a> as {@link Nullable}.
92 */
93 @Documented
94 @Target(TYPE_USE)
95 @Retention(RUNTIME)
96 public @interface NonNull {}