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
The following commit(s) were added to refs/heads/main by this push:
new 8f6ad47fbd LOG4J2-1477: Add nullability annotations
8f6ad47fbd is described below
commit 8f6ad47fbdbee1a6829859df19efeeafedf930ea
Author: Matt Sicker <[email protected]>
AuthorDate: Mon Nov 20 15:53:25 2023 -0600
LOG4J2-1477: Add nullability annotations
Signed-off-by: Matt Sicker <[email protected]>
---
.../apache/logging/log4j/lang/CheckForNull.java | 40 +++++++++++++++++++++
.../log4j/lang/ElementsAreNotNullByDefault.java | 31 ++++++++++++++++
.../org/apache/logging/log4j/lang/NotNull.java | 39 ++++++++++++++++++++
.../org/apache/logging/log4j/lang/Tainted.java | 41 ++++++++++++++++++++++
.../org/apache/logging/log4j/lang/Untainted.java | 40 +++++++++++++++++++++
.../apache/logging/log4j/lang/package-info.java | 28 +++++++++++++++
.../logging/log4j/plugins/util/AnnotationUtil.java | 6 ++--
.../LOG4J2-1477_add_nullability_annotations.xml | 25 +++++++++++++
8 files changed, 248 insertions(+), 2 deletions(-)
diff --git
a/log4j-api/src/main/java/org/apache/logging/log4j/lang/CheckForNull.java
b/log4j-api/src/main/java/org/apache/logging/log4j/lang/CheckForNull.java
new file mode 100644
index 0000000000..21e8a5ab3e
--- /dev/null
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/CheckForNull.java
@@ -0,0 +1,40 @@
+/*
+ * 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.
+ */
+@Documented
+@Target({
+ ElementType.FIELD,
+ ElementType.METHOD,
+ ElementType.PARAMETER,
+ ElementType.TYPE_PARAMETER,
+ ElementType.LOCAL_VARIABLE,
+ ElementType.TYPE_USE
+})
+@Nonnull(when = When.MAYBE)
+@TypeQualifierNickname
+public @interface CheckForNull {}
diff --git
a/log4j-api/src/main/java/org/apache/logging/log4j/lang/ElementsAreNotNullByDefault.java
b/log4j-api/src/main/java/org/apache/logging/log4j/lang/ElementsAreNotNullByDefault.java
new file mode 100644
index 0000000000..54d8efdbc4
--- /dev/null
+++
b/log4j-api/src/main/java/org/apache/logging/log4j/lang/ElementsAreNotNullByDefault.java
@@ -0,0 +1,31 @@
+/*
+ * 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 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.
+ */
+@Documented
+@TypeQualifierDefault({ElementType.FIELD, ElementType.METHOD,
ElementType.PARAMETER})
+@Nonnull
+public @interface ElementsAreNotNullByDefault {}
diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/NotNull.java
b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NotNull.java
new file mode 100644
index 0000000000..8735658a70
--- /dev/null
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/NotNull.java
@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+@Documented
+@Target({
+ ElementType.FIELD,
+ ElementType.METHOD,
+ ElementType.PARAMETER,
+ ElementType.TYPE_PARAMETER,
+ ElementType.LOCAL_VARIABLE,
+ ElementType.TYPE_USE
+})
+@TypeQualifierNickname
+@Nonnull
+public @interface NotNull {}
diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/lang/Tainted.java
b/log4j-api/src/main/java/org/apache/logging/log4j/lang/Tainted.java
new file mode 100644
index 0000000000..787d1c6cf5
--- /dev/null
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/Tainted.java
@@ -0,0 +1,41 @@
+/*
+ * 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.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+/**
+ * Annotates an element that is tainted (possibly untrusted or unvalidated
input).
+ *
+ * @see Untainted
+ */
+@Documented
+@Target({
+ ElementType.FIELD,
+ ElementType.METHOD,
+ ElementType.PARAMETER,
+ ElementType.TYPE_PARAMETER,
+ ElementType.LOCAL_VARIABLE,
+ ElementType.TYPE_USE
+})
+@TypeQualifierNickname
[email protected](when = When.MAYBE)
+public @interface Tainted {}
diff --git
a/log4j-api/src/main/java/org/apache/logging/log4j/lang/Untainted.java
b/log4j-api/src/main/java/org/apache/logging/log4j/lang/Untainted.java
new file mode 100644
index 0000000000..7fed3ba68f
--- /dev/null
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/lang/Untainted.java
@@ -0,0 +1,40 @@
+/*
+ * 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.meta.TypeQualifierNickname;
+
+/**
+ * Annotates an element that is untainted (properly validated or escaped).
+ *
+ * @see Tainted
+ */
+@Documented
+@Target({
+ ElementType.FIELD,
+ ElementType.METHOD,
+ ElementType.PARAMETER,
+ ElementType.TYPE_PARAMETER,
+ ElementType.LOCAL_VARIABLE,
+ ElementType.TYPE_USE
+})
+@TypeQualifierNickname
[email protected]
+public @interface Untainted {}
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..cb8eea6faf
--- /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("3.0.0")
+package org.apache.logging.log4j.lang;
+
+import org.osgi.annotation.bundle.Export;
+import org.osgi.annotation.versioning.Version;
diff --git
a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/util/AnnotationUtil.java
b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/util/AnnotationUtil.java
index 9d7a062915..832650df0a 100644
---
a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/util/AnnotationUtil.java
+++
b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/util/AnnotationUtil.java
@@ -75,7 +75,8 @@ public final class AnnotationUtil {
final Stream.Builder<AnnotatedAnnotation<? extends Annotation, M>>
matched) {
for (final Annotation annotation : element.getAnnotations()) {
final Class<? extends Annotation> annotationType =
annotation.annotationType();
- if (annotationType.getPackageName().startsWith("java.lang.")) {
+ final String packageName = annotationType.getPackageName();
+ if (packageName.startsWith("java.lang.") ||
packageName.startsWith("org.apache.logging.log4j.lang.")) {
continue;
}
if (visitedAnnotations.add(annotationType)) {
@@ -124,7 +125,8 @@ public final class AnnotationUtil {
final Stream.Builder<A> matched) {
for (final Annotation annotation : element.getAnnotations()) {
final Class<? extends Annotation> annotationType =
annotation.annotationType();
- if (annotationType.getPackageName().startsWith("java.lang.")) {
+ final String packageName = annotationType.getPackageName();
+ if (packageName.startsWith("java.lang.") ||
packageName.startsWith("org.apache.logging.log4j.lang.")) {
continue;
}
if (annotationType == logicalAnnotation) {
diff --git a/src/changelog/.3.x.x/LOG4J2-1477_add_nullability_annotations.xml
b/src/changelog/.3.x.x/LOG4J2-1477_add_nullability_annotations.xml
new file mode 100644
index 0000000000..aec231bd14
--- /dev/null
+++ b/src/changelog/.3.x.x/LOG4J2-1477_add_nullability_annotations.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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.
+ -->
+<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns="http://logging.apache.org/log4j/changelog";
+ xsi:schemaLocation="http://logging.apache.org/log4j/changelog
https://logging.apache.org/log4j/changelog-0.1.2.xsd";
+ type="added">
+ <issue id="LOG4J2-1477"
link="https://issues.apache.org/jira/browse/LOG4J2-1477"/>
+ <author id="msicker"/>
+ <description format="asciidoc">Add annotations for nullability.</description>
+</entry>
