Support and declare nullability

context-propagation-api/src/main/java/io/micrometer/context/DefaultContextSnapshot.java

@@ -29,26 +29,27 @@
  */
 final class DefaultContextSnapshot implements ContextSnapshot {
 
-    private final Map<Object, Object> savedValues;
+    private final Map<Object, Object> values;
 
     private final ContextRegistry accessorRegistry;
 
 
-    DefaultContextSnapshot(Map<Object, Object> savedValues, ContextRegistry accessorRegistry) {
-        this.savedValues = savedValues;
+    DefaultContextSnapshot(Map<Object, Object> values, ContextRegistry accessorRegistry) {
+        this.values = values;
         this.accessorRegistry = accessorRegistry;
     }
 
+
     @Override
     public <C> C updateContext(C context) {
-        return updateContextInternal(context, this.savedValues);
+        return updateContextInternal(context, this.values);
     }
 
     @Override
     public <C> C updateContext(C context, Predicate<Object> keyPredicate) {
-        if (!this.savedValues.isEmpty()) {
+        if (!this.values.isEmpty()) {
             Map<Object, Object> valuesToWrite = new HashMap<>();
-            this.savedValues.forEach((key, value) -> {
+            this.values.forEach((key, value) -> {
                 if (keyPredicate.test(key)) {
                     valuesToWrite.put(key, value);
                 }
@@ -60,7 +61,7 @@ public <C> C updateContext(C context, Predicate<Object> keyPredicate) {
 
     @SuppressWarnings("unchecked")
     private <C> C updateContextInternal(C context, Map<Object, Object> valueContainer) {
-        if (!this.savedValues.isEmpty()) {
+        if (!this.values.isEmpty()) {
             ContextAccessor<?, ?> accessor = this.accessorRegistry.getContextAccessorForWrite(context);
             context = ((ContextAccessor<?, C>) accessor).writeValues(valueContainer, context);
         }
@@ -78,7 +79,7 @@ public Scope setThreadLocalValues(Predicate<Object> keyPredicate) {
         Map<Object, Object> previousValues = null;
         for (ThreadLocalAccessor<?> accessor : this.accessorRegistry.getThreadLocalAccessors()) {
             Object key = accessor.key();
-            if (this.savedValues.containsKey(key)) {
+            if (this.values.containsKey(key)) {
                 keys = (keys != null ? keys : new HashSet<>());
                 keys.add(key);
 
@@ -94,12 +95,12 @@ public Scope setThreadLocalValues(Predicate<Object> keyPredicate) {
 
     @SuppressWarnings("unchecked")
     private <V> void setThreadLocalValue(Object key, ThreadLocalAccessor<?> accessor) {
-        ((ThreadLocalAccessor<V>) accessor).setValue((V) this.savedValues.get(key));
+        ((ThreadLocalAccessor<V>) accessor).setValue((V) this.values.get(key));
     }
 
     @Override
     public String toString() {
-        return "DefaultContextSnapshot" + this.savedValues;
+        return "DefaultContextSnapshot" + this.values;
     }
 
 
@@ -128,7 +129,7 @@ public void close() {
         }
 
         @SuppressWarnings("unchecked")
-        private <V> void resetThreadLocalValue(ThreadLocalAccessor<?> accessor, V previousValue) {
+        private <V> void resetThreadLocalValue(ThreadLocalAccessor<?> accessor, @Nullable V previousValue) {
             if (previousValue != null) {
                 ((ThreadLocalAccessor<V>) accessor).setValue(previousValue);
             }

context-propagation-api/src/main/java/io/micrometer/context/DefaultContextSnapshotBuilder.java

@@ -38,8 +38,10 @@ final class DefaultContextSnapshotBuilder implements ContextSnapshot.Builder {
 
     private final ContextRegistry accessorRegistry;
 
+    @Nullable
     private List<Object> keys;
 
+    @Nullable
     private Predicate<Object> keyPredicate;
 
 

context-propagation-api/src/main/java/io/micrometer/context/NonNullApi.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2002-2022 the original author or 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
+ *
+ *      https://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 io.micrometer.context;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierDefault;
+
+/**
+ * Declares all method parameters and return values within a package as
+ * non-nullable via JSR-305 meta-annotations to indicate nullability in Java.
+ *
+ * @author Rossen Stoyanchev
+ * @since 1.0.0
+ */
+@Target(ElementType.PACKAGE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull
+@TypeQualifierDefault({ElementType.METHOD, ElementType.PARAMETER})
+@interface NonNullApi {
+}

context-propagation-api/src/main/java/io/micrometer/context/NonNullFields.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2002-2022 the original author or 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
+ *
+ *      https://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 io.micrometer.context;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierDefault;
+
+/**
+ * Declares all fields within a package as non-nullable via JSR-305
+ * meta-annotations to indicate nullability in Java.
+ *
+ * @author Rossen Stoyanchev
+ * @since 1.0.0
+ */
+@Target(ElementType.PACKAGE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull
+@TypeQualifierDefault(ElementType.FIELD)
+@interface NonNullFields {
+}

context-propagation-api/src/main/java/io/micrometer/context/Nullable.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2022 the original author or 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
+ *
+ *      https://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 io.micrometer.context;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+
+/**
+ * Annotation to declare that a method parameter, return value, or field can be
+ * {@code null} under some circumstance. Uses JSR-305 meta-annotations to
+ * indicate nullability. Overridden methods override should redeclare the
+ * annotation unless they behave differently.
+ *
+ * @author Rossen Stoyanchev
+ * @since 1.0.0
+ * @see NonNullApi
+ * @see NonNullFields
+ */
+@Target({ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull(when = When.MAYBE)
+@TypeQualifierNickname
+@interface Nullable {
+}

context-propagation-api/src/main/java/io/micrometer/context/reactor/ReactorContextAccessor.java → context-propagation-api/src/main/java/io/micrometer/context/ReactorContextAccessor.java

@@ -13,12 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.micrometer.context.reactor;
+package io.micrometer.context;
 
 import java.util.Map;
 import java.util.function.Predicate;
 
-import io.micrometer.context.ContextAccessor;
 import reactor.util.context.Context;
 import reactor.util.context.ContextView;
 

context-propagation-api/src/main/java/io/micrometer/context/ThreadLocalAccessor.java

@@ -35,6 +35,7 @@ public interface ThreadLocalAccessor<V> {
     /**
      * Return the {@link ThreadLocal} value, or {@code null} if not set.
      */
+    @Nullable
     V getValue();
 
     /**

context-propagation-api/src/main/java/io/micrometer/context/package-info.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2002-2022 the original author or 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
+ *
+ *      https://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.
+ */
+
+/**
+ * This package contains abstractions and implementations for context propagation.
+ * <ul>
+ * <li>{@link io.micrometer.context.ThreadLocalAccessor} and {@link io.micrometer.context.ContextAccessor}
+ * allow applications and frameworks to plug in support for
+ * {@link java.lang.ThreadLocal} and other Map-like types of context such as the
+ * Project Reactor Contexts.
+ * <li>{@link io.micrometer.context.ContextRegistry} provides a static instance
+ * with global access to all known accessors that should be registered on
+ * startup.
+ * <li>{@link io.micrometer.context.ContextSnapshot} uses the {@code ContextRegistry}
+ * and is used to capture context values, and then propagate them from one type
+ * of context to another or from one thread to another.
+ * </ul>
+ */
+@NonNullApi
+@NonNullFields
+package io.micrometer.context;
+