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