Introduce Armeria @Nullable to annotate type parameters (#3751)

Motivation:

After `ElementType.TYPE_USE` was applied to
`NonNullByDefault` #3558, we need to selectively mark `@Nullable` for
type parameters. Otherwise, Kotlin compiler will raise an error when a
null value is used with `-Xjsr305=strict`. #2793 (comment)

However, `javax.annotation.Nullable` can not be appliable to
`ElementType.TYPE_USE`. We need a brand new `Nullable`

Modifications:

- Add a new `c.l.a.common.annotation.Nullable` that uses JSR305 with
  `@TypeQualifierNickname` and `ElementType.TYPE_USE` is targeted.
- Migrate `javax.annotation.Nullable` to the new `Nullable`
- Apply `@Nullable` to type parameters where appliable.
- Change wildcard(`?`) types to `? extends @nullable Object` where `@Nullable` annotation is required.
- Disallow the legacy `javax.annotation.Nullable` using Checkstyle.

Result:

- Kotlin `jsr305=strict` option no longer raises a compile error
  when a null value is returned from where nulls are allowed.

benchmarks/src/jmh/java/com/linecorp/armeria/common/HttpHeadersBenchmark.java

@@ -16,11 +16,11 @@
 
 package com.linecorp.armeria.common;
 
-import javax.annotation.Nullable;
-
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.Fork;
 
+import com.linecorp.armeria.common.annotation.Nullable;
+
 /**
  * Microbenchmarks of {@link DefaultHttpHeaders} construction.
  */

benchmarks/src/jmh/java/com/linecorp/armeria/core/client/endpoint/WeightedRoundRobinStrategyBenchmark.java

@@ -20,8 +20,6 @@
 import java.util.List;
 import java.util.Random;
 
-import javax.annotation.Nullable;
-
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.Scope;
 import org.openjdk.jmh.annotations.Setup;
@@ -31,6 +29,7 @@
 import com.linecorp.armeria.client.endpoint.EndpointGroup;
 import com.linecorp.armeria.client.endpoint.EndpointSelectionStrategy;
 import com.linecorp.armeria.client.endpoint.EndpointSelector;
+import com.linecorp.armeria.common.annotation.Nullable;
 
 /**
  * Microbenchmarks of different {@link EndpointSelector} configurations.

benchmarks/src/jmh/java/com/linecorp/armeria/grpc/shared/SimpleBenchmarkBase.java

@@ -20,8 +20,6 @@
 
 import java.util.concurrent.TimeUnit;
 
-import javax.annotation.Nullable;
-
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.Param;
 import org.openjdk.jmh.annotations.Scope;
@@ -34,6 +32,7 @@
 import com.google.common.util.concurrent.MoreExecutors;
 import com.google.protobuf.Empty;
 
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.grpc.GithubApi.SearchResponse;
 import com.linecorp.armeria.grpc.GithubServiceGrpc;
 import com.linecorp.armeria.grpc.GithubServiceGrpc.GithubServiceBlockingStub;

benchmarks/src/jmh/java/com/linecorp/armeria/internal/server/annotation/MethodInvokerBenchmark.java

@@ -23,8 +23,6 @@
 import java.lang.reflect.Modifier;
 import java.util.concurrent.TimeUnit;
 
-import javax.annotation.Nullable;
-
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
 import org.openjdk.jmh.annotations.Level;
@@ -36,6 +34,8 @@
 import org.openjdk.jmh.annotations.Warmup;
 import org.openjdk.jmh.infra.Blackhole;
 
+import com.linecorp.armeria.common.annotation.Nullable;
+
 @State(Scope.Benchmark)
 @OutputTimeUnit(TimeUnit.NANOSECONDS)
 @BenchmarkMode(Mode.AverageTime)

brave/src/main/java/com/linecorp/armeria/client/brave/BraveClient.java

@@ -21,8 +21,6 @@
 import java.util.concurrent.TimeUnit;
 import java.util.function.Function;
 
-import javax.annotation.Nullable;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -33,6 +31,7 @@
 import com.linecorp.armeria.common.HttpRequest;
 import com.linecorp.armeria.common.HttpResponse;
 import com.linecorp.armeria.common.RequestHeadersBuilder;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.brave.RequestContextCurrentTraceContext;
 import com.linecorp.armeria.common.logging.ClientConnectionTimings;
 import com.linecorp.armeria.internal.common.brave.SpanTags;

brave/src/main/java/com/linecorp/armeria/client/brave/ClientRequestContextAdapter.java

@@ -16,13 +16,12 @@
 
 package com.linecorp.armeria.client.brave;
 
-import javax.annotation.Nullable;
-
 import com.linecorp.armeria.client.ClientRequestContext;
 import com.linecorp.armeria.common.HttpRequest;
 import com.linecorp.armeria.common.RequestHeadersBuilder;
 import com.linecorp.armeria.common.SerializationFormat;
 import com.linecorp.armeria.common.SessionProtocol;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.logging.RequestLog;
 import com.linecorp.armeria.common.logging.RequestLogAccess;
 import com.linecorp.armeria.common.logging.RequestLogProperty;

brave/src/main/java/com/linecorp/armeria/common/brave/RequestContextCurrentTraceContext.java

@@ -24,13 +24,12 @@
 import java.util.function.Supplier;
 import java.util.regex.Pattern;
 
-import javax.annotation.Nullable;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import com.linecorp.armeria.client.brave.BraveClient;
 import com.linecorp.armeria.common.RequestContext;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.internal.common.brave.TraceContextUtil;
 import com.linecorp.armeria.server.brave.BraveService;

brave/src/main/java/com/linecorp/armeria/internal/common/brave/TraceContextUtil.java

@@ -18,11 +18,10 @@
 
 import static java.util.Objects.requireNonNull;
 
-import javax.annotation.Nullable;
-
 import com.google.common.annotations.VisibleForTesting;
 
 import com.linecorp.armeria.common.RequestContext;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.brave.RequestContextCurrentTraceContext;
 
 import brave.Tracing;

brave/src/main/java/com/linecorp/armeria/server/brave/ServiceRequestContextAdapter.java

@@ -16,10 +16,9 @@
 
 package com.linecorp.armeria.server.brave;
 
-import javax.annotation.Nullable;
-
 import com.linecorp.armeria.common.RequestContext;
 import com.linecorp.armeria.common.SerializationFormat;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.logging.RequestLog;
 import com.linecorp.armeria.common.logging.RequestLogProperty;
 import com.linecorp.armeria.internal.common.brave.SpanContextUtil;

brave/src/test/java/com/linecorp/armeria/client/brave/BraveClientTest.java

@@ -28,8 +28,6 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
 
-import javax.annotation.Nullable;
-
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 
@@ -44,6 +42,7 @@
 import com.linecorp.armeria.common.ResponseHeaders;
 import com.linecorp.armeria.common.RpcRequest;
 import com.linecorp.armeria.common.RpcResponse;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.brave.HelloService;
 import com.linecorp.armeria.common.brave.RequestContextCurrentTraceContext;
 import com.linecorp.armeria.common.brave.SpanCollector;

brave/src/test/java/com/linecorp/armeria/server/brave/BraveServiceIntegrationTest.java

@@ -24,8 +24,6 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
-import javax.annotation.Nullable;
-
 import org.junit.After;
 import org.junit.AssumptionViolatedException;
 import org.junit.Test;
@@ -36,6 +34,7 @@
 import com.linecorp.armeria.common.HttpStatus;
 import com.linecorp.armeria.common.MediaType;
 import com.linecorp.armeria.common.SessionProtocol;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.brave.RequestContextCurrentTraceContext;
 import com.linecorp.armeria.common.util.SystemInfo;
 import com.linecorp.armeria.server.Server;

bucket4j/src/main/java/com/linecorp/armeria/server/throttling/bucket4j/TokenBucket.java

@@ -20,10 +20,9 @@
 
 import java.time.Duration;
 
-import javax.annotation.Nullable;
-
 import com.google.common.base.MoreObjects;
 
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 
 /**

bucket4j/src/main/java/com/linecorp/armeria/server/throttling/bucket4j/TokenBucketSpec.java

@@ -26,10 +26,10 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
-import javax.annotation.Nullable;
-
 import com.google.common.base.Splitter;
 
+import com.linecorp.armeria.common.annotation.Nullable;
+
 /**
  * A specification of a {@link TokenBucket} configuration represented by a string. The string syntax is
  * a series of comma-separated {@link BandwidthLimit} configurations and each values is semicolon-separated,

bucket4j/src/main/java/com/linecorp/armeria/server/throttling/bucket4j/TokenBucketThrottlingStrategy.java

@@ -21,10 +21,9 @@
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.TimeUnit;
 
-import javax.annotation.Nullable;
-
 import com.linecorp.armeria.common.HttpHeaderNames;
 import com.linecorp.armeria.common.Request;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.common.throttling.ThrottlingHeaders;
 import com.linecorp.armeria.server.ServiceRequestContext;

bucket4j/src/main/java/com/linecorp/armeria/server/throttling/bucket4j/TokenBucketThrottlingStrategyBuilder.java

@@ -21,9 +21,8 @@
 
 import java.time.Duration;
 
-import javax.annotation.Nullable;
-
 import com.linecorp.armeria.common.Request;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.common.throttling.ThrottlingHeaders;
 

consul/src/main/java/com/linecorp/armeria/client/consul/ConsulEndpointGroup.java

@@ -23,8 +23,6 @@
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
 
-import javax.annotation.Nullable;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -34,6 +32,7 @@
 import com.linecorp.armeria.client.endpoint.DynamicEndpointGroup;
 import com.linecorp.armeria.client.endpoint.EndpointGroup;
 import com.linecorp.armeria.client.endpoint.EndpointSelectionStrategy;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.internal.consul.ConsulClient;
 

consul/src/main/java/com/linecorp/armeria/client/consul/ConsulEndpointGroupBuilder.java

@@ -21,9 +21,8 @@
 import java.net.URI;
 import java.time.Duration;
 
-import javax.annotation.Nullable;
-
 import com.linecorp.armeria.client.endpoint.EndpointSelectionStrategy;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.common.consul.ConsulConfigSetters;
 import com.linecorp.armeria.internal.consul.ConsulClient;

consul/src/main/java/com/linecorp/armeria/internal/consul/AgentServiceClient.java

@@ -19,8 +19,6 @@
 
 import java.util.List;
 
-import javax.annotation.Nullable;
-
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
@@ -32,6 +30,7 @@
 import com.linecorp.armeria.client.WebClient;
 import com.linecorp.armeria.common.HttpData;
 import com.linecorp.armeria.common.HttpResponse;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.internal.common.PercentEncoder;
 
 /**

consul/src/main/java/com/linecorp/armeria/internal/consul/CatalogClient.java

@@ -24,8 +24,6 @@
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
-import javax.annotation.Nullable;
-
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -38,6 +36,7 @@
 import com.linecorp.armeria.client.Endpoint;
 import com.linecorp.armeria.client.WebClient;
 import com.linecorp.armeria.common.QueryParams;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.util.Exceptions;
 import com.linecorp.armeria.internal.common.PercentEncoder;
 

consul/src/main/java/com/linecorp/armeria/internal/consul/Check.java

@@ -17,14 +17,14 @@
 
 import java.util.Map;
 
-import javax.annotation.Nullable;
-
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.google.common.base.MoreObjects;
 
+import com.linecorp.armeria.common.annotation.Nullable;
+
 @JsonIgnoreProperties(ignoreUnknown = true)
 @JsonInclude(Include.NON_NULL)
 public final class Check {

consul/src/main/java/com/linecorp/armeria/internal/consul/ConsulClient.java

@@ -20,8 +20,6 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
 
-import javax.annotation.Nullable;
-
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import com.linecorp.armeria.client.Endpoint;
@@ -33,6 +31,7 @@
 import com.linecorp.armeria.client.retry.RetryingClient;
 import com.linecorp.armeria.common.HttpHeaderNames;
 import com.linecorp.armeria.common.HttpResponse;
+import com.linecorp.armeria.common.annotation.Nullable;
 
 /**
  * A client for accessing a Consul agent API server.

consul/src/main/java/com/linecorp/armeria/internal/consul/ConsulClientBuilder.java

@@ -22,8 +22,7 @@
 import java.net.URISyntaxException;
 import java.util.regex.Pattern;
 
-import javax.annotation.Nullable;
-
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.consul.ConsulConfigSetters;
 
 public final class ConsulClientBuilder implements ConsulConfigSetters {

consul/src/main/java/com/linecorp/armeria/internal/consul/ConsulClientUtil.java

@@ -15,10 +15,9 @@
  */
 package com.linecorp.armeria.internal.consul;
 
-import javax.annotation.Nullable;
-
 import com.linecorp.armeria.common.QueryParams;
 import com.linecorp.armeria.common.QueryParamsBuilder;
+import com.linecorp.armeria.common.annotation.Nullable;
 
 /**
  * Utility methods related to Consul clients.

consul/src/main/java/com/linecorp/armeria/internal/consul/HealthClient.java

@@ -25,8 +25,6 @@
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
-import javax.annotation.Nullable;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -42,6 +40,7 @@
 import com.linecorp.armeria.common.HttpStatus;
 import com.linecorp.armeria.common.QueryParams;
 import com.linecorp.armeria.common.QueryParamsBuilder;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.internal.common.PercentEncoder;
 
 /**

consul/src/main/java/com/linecorp/armeria/server/consul/ConsulUpdatingListener.java

@@ -22,14 +22,13 @@
 import java.util.List;
 import java.util.concurrent.ThreadLocalRandom;
 
-import javax.annotation.Nullable;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import com.linecorp.armeria.client.Endpoint;
 import com.linecorp.armeria.common.HttpMethod;
 import com.linecorp.armeria.common.HttpStatus;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.common.util.SystemInfo;
 import com.linecorp.armeria.internal.consul.Check;

consul/src/main/java/com/linecorp/armeria/server/consul/ConsulUpdatingListenerBuilder.java

@@ -21,12 +21,11 @@
 import java.net.URI;
 import java.time.Duration;
 
-import javax.annotation.Nullable;
-
 import com.google.common.collect.ImmutableSet;
 
 import com.linecorp.armeria.client.Endpoint;
 import com.linecorp.armeria.common.HttpMethod;
+import com.linecorp.armeria.common.annotation.Nullable;
 import com.linecorp.armeria.common.annotation.UnstableApi;
 import com.linecorp.armeria.common.consul.ConsulConfigSetters;
 import com.linecorp.armeria.internal.consul.ConsulClient;