/* * Copyright 2018-2020 The JSpecify Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jspecify.annotations; import static java.lang.annotation.ElementType.CONSTRUCTOR; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.MODULE; import static java.lang.annotation.ElementType.PACKAGE; import static java.lang.annotation.ElementType.TYPE; import static java.lang.annotation.RetentionPolicy.RUNTIME; import java.lang.annotation.Documented; import java.lang.annotation.Retention; import java.lang.annotation.Target; /** * Indicates that the annotated element and the code transitively {@linkplain * javax.lang.model.element.Element#getEnclosedElements() enclosed} within it are null-marked * code: there, type usages are generally considered to exclude {@code null} as a value unless * specified otherwise. Using this annotation avoids the need to write {@link NonNull @NonNull} many * times throughout your code. * *

For a comprehensive introduction to JSpecify, please see jspecify.org. * *

Effects of being null-marked

* *

Within null-marked code, as a general rule, a type usage is considered non-null (to * exclude {@code null} as a value) unless explicitly annotated as {@link Nullable}. However, there * are several special cases to address. * *

Special cases

* *

Within null-marked code: * *

* *

Where it can be used

* * {@code @NullMarked} and {@link NullUnmarked @NullUnmarked} can be used on any package, class, * method, or constructor declaration; {@code @NullMarked} can be used on a module declaration as * well. Special considerations: * * */ @Documented @Target({MODULE, PACKAGE, TYPE, METHOD, CONSTRUCTOR}) @Retention(RUNTIME) public @interface NullMarked {}