From 591024998bd3291896619b9cd8068e5711c0018a Mon Sep 17 00:00:00 2001 From: Tomas Langer Date: Tue, 29 Jun 2021 17:46:23 +0200 Subject: [PATCH] Nonnull and Nullable annotations added. Signed-off-by: Tomas Langer --- .../main/java/jakarta/annotation/Nonnull.java | 37 +++++++++ .../java/jakarta/annotation/Nullable.java | 43 +++++++++++ spec/src/main/asciidoc/annotations-spec.adoc | 2 +- spec/src/main/asciidoc/spec.adoc | 77 +++++++++++++++++++ 4 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 api/src/main/java/jakarta/annotation/Nonnull.java create mode 100644 api/src/main/java/jakarta/annotation/Nullable.java diff --git a/api/src/main/java/jakarta/annotation/Nonnull.java b/api/src/main/java/jakarta/annotation/Nonnull.java new file mode 100644 index 0000000..7288949 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/Nonnull.java @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; + +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +/** + * The annotated element must not be null. + *

+ * Annotated fields must not be null after construction has completed. + *

+ * When this annotation is applied to a method it applies to the method return value. + * + * @see jakarta.annotation.Nullable + * @since 2.0 + */ +@Documented +@Retention(RUNTIME) +public @interface Nonnull { +} diff --git a/api/src/main/java/jakarta/annotation/Nullable.java b/api/src/main/java/jakarta/annotation/Nullable.java new file mode 100644 index 0000000..5370caf --- /dev/null +++ b/api/src/main/java/jakarta/annotation/Nullable.java @@ -0,0 +1,43 @@ +/* + * Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; + +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +/** + * The annotated element could be null under some circumstances. + *

+ * In general, this means developers will have to read the documentation to + * determine when a null value is acceptable and whether it is necessary to + * check for a null value. + *

+ * This annotation is useful mostly for overriding a {@link Nonnull} annotation. + * Static analysis tools should generally treat the annotated items as though they + * had no annotation, unless they are configured to minimize false negatives. + *

+ * When this annotation is applied to a method it applies to the method return value. + * + * @see jakarta.annotation.Nonnull + * @since 2.0 + */ +@Documented +@Retention(RUNTIME) +public @interface Nullable { +} diff --git a/spec/src/main/asciidoc/annotations-spec.adoc b/spec/src/main/asciidoc/annotations-spec.adoc index 5a46c65..e119eb0 100644 --- a/spec/src/main/asciidoc/annotations-spec.adoc +++ b/spec/src/main/asciidoc/annotations-spec.adoc @@ -1,5 +1,5 @@ // -// Copyright (c) 2017, 2020 Contributors to the Eclipse Foundation +// Copyright (c) 2017, 2021 Contributors to the Eclipse Foundation // = Jakarta Annotations diff --git a/spec/src/main/asciidoc/spec.adoc b/spec/src/main/asciidoc/spec.adoc index 03126c3..14a727e 100644 --- a/spec/src/main/asciidoc/spec.adoc +++ b/spec/src/main/asciidoc/spec.adoc @@ -732,6 +732,83 @@ public @interface Priority { } ---- +=== jakarta.annotation.Nonnull + +The _Nonnull_ annotation is used to mark +elements that cannot be `null`. + +This information can be used for validation by IDEs, static analysis tools, and runtime. + +The annotation may be present on any target. +This specification defines behavior on following targets: + +- Method - return type will never be `null` +- Parameter - parameter must not be `null` +- Field - field cannot be `null` after construction of the object is completed + +[source,java] +---- +package jakarta.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; + +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +@Documented +@Retention(RUNTIME) +public @interface Nonnull { +} +---- + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +public interface StockQuoteService { + @Nonnull + BigDecimal quote(@Nonnull String marker); +} +---- + +=== jakarta.annotation.Nullable + +The _Nullable_ annotation is used to mark +elements that may be `null`. + +This information can be used for validation by IDEs, static analysis tools, and runtime. + +The annotation may be present on any target. +This specification defines behavior on following targets: + +- Method - return type may be `null` +- Parameter - parameter may be `null` +- Field - field may be `null` + +[source,java] +---- +package jakarta.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; + +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +@Documented +@Retention(RUNTIME) +public @interface Nullable { +} +---- + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +public interface StockQuoteService { + BigDecimal quote(String marker, @Nullable BigDecimal defaultValue); +} +---- + === jakarta.annotation.security.RunAs The _RunAs_ annotation defines the security