This is an automated email from the ASF dual-hosted git repository. mattsicker pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 2da4108da52653dbb43f00b0967f16917c6975c0 Author: Matt Sicker <[email protected]> AuthorDate: Mon Jan 1 23:07:05 2024 -0600 Add nullability annotation stereotypes This adds JSpecify annotations as JSR-305-aliased annotations for ease with tool integration. Signed-off-by: Matt Sicker <[email protected]> --- log4j-api/pom.xml | 7 +++- .../org/apache/logging/log4j/lang/NonNull.java | 35 ++++++++++++++++++++ .../org/apache/logging/log4j/lang/NullMarked.java | 36 +++++++++++++++++++++ .../apache/logging/log4j/lang/NullUnmarked.java | 37 ++++++++++++++++++++++ .../org/apache/logging/log4j/lang/Nullable.java | 36 +++++++++++++++++++++ .../apache/logging/log4j/lang/package-info.java | 28 ++++++++++++++++ log4j-parent/pom.xml | 8 +++++ 7 files changed, 186 insertions(+), 1 deletion(-) diff --git a/log4j-api/pom.xml b/log4j-api/pom.xml index bb22c40e74..5db39f09bd 100644 --- a/log4j-api/pom.xml +++ b/log4j-api/pom.xml @@ -36,14 +36,19 @@ <bnd-module-name>org.apache.logging.log4j</bnd-module-name> <bnd-extra-package-options> <!-- No JSR 305 at runtime --> - !javax.annotation.* + !javax.annotation.*, + <!-- No JSpecify at runtime --> + !org.jspecify.annotations.* </bnd-extra-package-options> <bnd-extra-module-options> <!-- No JSR 305 at runtime --> jsr305;ignore=true, + <!-- No JSpecify at runtime --> + org.jspecify;ignore=true, <!-- Used in StringBuilders through reflection --> java.sql;static=true </bnd-extra-module-options> </properties> + </project> diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/NonNull.java b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NonNull.java new file mode 100644 index 0000000000..8f2e743e7e --- /dev/null +++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NonNull.java @@ -0,0 +1,35 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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.apache.logging.log4j.lang; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; +import javax.annotation.Nonnull; +import javax.annotation.meta.TypeQualifierNickname; + +/** + * Annotates an element that should never be null. + * + * @see org.jspecify.annotations.NonNull + */ +@Documented +@Target(ElementType.TYPE_USE) +@TypeQualifierNickname +@Nonnull [email protected] +public @interface NonNull {} diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/NullMarked.java b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NullMarked.java new file mode 100644 index 0000000000..4470082671 --- /dev/null +++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NullMarked.java @@ -0,0 +1,36 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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.apache.logging.log4j.lang; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; +import javax.annotation.Nonnull; +import javax.annotation.meta.TypeQualifierDefault; + +/** + * Annotates an element to indicate all its members should never be null. When applied to a package, this applies + * to all classes in the package. + * + * @see org.jspecify.annotations.NullMarked + */ +@Documented +@Target({ElementType.MODULE, ElementType.PACKAGE, ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR}) +@TypeQualifierDefault({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE_PARAMETER}) +@Nonnull [email protected] +public @interface NullMarked {} diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/NullUnmarked.java b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NullUnmarked.java new file mode 100644 index 0000000000..e5634ab406 --- /dev/null +++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NullUnmarked.java @@ -0,0 +1,37 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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.apache.logging.log4j.lang; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; +import javax.annotation.Nonnull; +import javax.annotation.meta.TypeQualifierDefault; +import javax.annotation.meta.When; + +/** + * Annotates an element to indicate all its members may be null. When applied to a package, this applies + * to all classes in the package. + * + * @see org.jspecify.annotations.NullUnmarked + */ +@Documented +@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR}) +@TypeQualifierDefault({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE_PARAMETER}) +@Nonnull(when = When.MAYBE) [email protected] +public @interface NullUnmarked {} diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/Nullable.java b/log4j-api/src/main/java/org/apache/logging/log4j/lang/Nullable.java new file mode 100644 index 0000000000..f9c28667be --- /dev/null +++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/Nullable.java @@ -0,0 +1,36 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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.apache.logging.log4j.lang; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; +import javax.annotation.Nonnull; +import javax.annotation.meta.TypeQualifierNickname; +import javax.annotation.meta.When; + +/** + * Annotates an element that may be null and should be checked for such at runtime. + * + * @see org.jspecify.annotations.Nullable + */ +@Documented +@Target(ElementType.TYPE_USE) +@Nonnull(when = When.MAYBE) +@TypeQualifierNickname [email protected] +public @interface Nullable {} diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/package-info.java b/log4j-api/src/main/java/org/apache/logging/log4j/lang/package-info.java new file mode 100644 index 0000000000..292eb40f6a --- /dev/null +++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/package-info.java @@ -0,0 +1,28 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ + +/** + * Provides essential type checking annotations for use with tools like SpotBugs. To avoid runtime issues with + * optionally-available annotations, annotations are defined in this package, and annotation-related reflection + * can easily skip over these annotations. + */ +@Export +@Version("1.0.0") +package org.apache.logging.log4j.lang; + +import org.osgi.annotation.bundle.Export; +import org.osgi.annotation.versioning.Version; diff --git a/log4j-parent/pom.xml b/log4j-parent/pom.xml index 79de6205c5..b80bbdc42f 100644 --- a/log4j-parent/pom.xml +++ b/log4j-parent/pom.xml @@ -127,6 +127,7 @@ <jmdns.version>3.5.9</jmdns.version> <jmh.version>1.37</jmh.version> <json-unit.version>2.38.0</json-unit.version> + <jspecify.version>0.3.0</jspecify.version> <junit.version>4.13.2</junit.version> <junit-jupiter.version>5.10.1</junit-jupiter.version> <junit-pioneer.version>2.2.0</junit-pioneer.version> @@ -897,6 +898,13 @@ <scope>provided</scope> </dependency> + <dependency> + <groupId>org.jspecify</groupId> + <artifactId>jspecify</artifactId> + <version>${jspecify.version}</version> + <scope>provided</scope> + </dependency> + <dependency> <groupId>org.osgi</groupId> <artifactId>osgi.annotation</artifactId>
