[improve][misc] Migrate from multiple nullness annotation libraries to JSpecify annotations (apache#24239)

(cherry picked from commit 9a11245)
(cherry picked from commit 62c505d)

Author: lhotari

buildtools/src/main/resources/pulsar/checkstyle.xml

@@ -140,6 +140,22 @@ page at http://checkstyle.sourceforge.net/config.html -->
                       value="autovalue.shaded, avro.shaded, bk-shade, com.google.api.client.repackaged, com.google.appengine.repackaged, org.apache.curator.shaded, org.testcontainers.shaded, org.junit" />
         </module>
 
+        <module name="IllegalImport">
+            <property name="illegalPkgs"
+                      value="org.jetbrains.annotations, org.checkerframework.checker.nullness.qual" />
+            <property name="illegalClasses"
+                      value="javax.annotation.Nullable, javax.annotation.Nonnull" />
+            <message key="import.illegal"
+                     value="{0}; Use org.jspecify.annotations.Nullable and org.jspecify.annotations.NonNull instead."/>
+        </module>
+
+        <module name="IllegalImport">
+            <property name="illegalClasses"
+                      value="javax.validation.constraints.Null, javax.validation.constraints.NotNull" />
+            <message key="import.illegal"
+                     value="{0}; Use org.jspecify.annotations.Nullable and org.jspecify.annotations.NonNull for nullness information. Check Jakarta Bean Validation API if you are looking for user input validation with annotations."/>
+        </module>
+
         <module name="RedundantModifier">
             <!-- Checks for redundant modifiers on various symbol definitions.
               See: http://checkstyle.sourceforge.net/config_modifier.html#RedundantModifier

distribution/server/src/assemble/LICENSE.bin.txt

@@ -539,6 +539,8 @@ The Apache Software License, Version 2.0
     - io.opentelemetry.semconv-opentelemetry-semconv-1.29.0-alpha.jar
   * Spotify completable-futures
     - com.spotify-completable-futures-0.3.6.jar
+  * JSpecify
+    - org.jspecify-jspecify-1.0.0.jar
 
 BSD 3-clause "New" or "Revised" License
  * Google auth library

distribution/shell/src/assemble/LICENSE.bin.txt

@@ -420,6 +420,7 @@ The Apache Software License, Version 2.0
  * Spotify completable-futures -- completable-futures-0.3.6.jar
  * RoaringBitmap -- RoaringBitmap-1.2.0.jar
  * Fastutil -- fastutil-8.5.14.jar
+ * JSpecify -- jspecify-1.0.0.jar
 
 BSD 3-clause "New" or "Revised" License
  * JSR305 -- jsr305-3.0.2.jar -- ../licenses/LICENSE-JSR305.txt

managed-ledger/src/main/java/org/apache/bookkeeper/mledger/impl/AckSetState.java

@@ -18,7 +18,7 @@
  */
 package org.apache.bookkeeper.mledger.impl;
 
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Interface to manage the ackSet state attached to a position.

managed-ledger/src/main/java/org/apache/bookkeeper/mledger/impl/ManagedCursorImpl.java

@@ -63,7 +63,6 @@
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
 import java.util.stream.LongStream;
-import javax.annotation.Nullable;
 import lombok.Getter;
 import org.apache.bookkeeper.client.AsyncCallback.CloseCallback;
 import org.apache.bookkeeper.client.AsyncCallback.OpenCallback;
@@ -113,6 +112,7 @@
 import org.apache.pulsar.common.util.collections.LongPairRangeSet.LongPairConsumer;
 import org.apache.pulsar.common.util.collections.LongPairRangeSet.RangeBoundConsumer;
 import org.apache.pulsar.metadata.api.Stat;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

managed-ledger/src/main/java/org/apache/bookkeeper/mledger/impl/ManagedLedgerImpl.java

@@ -68,7 +68,6 @@
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
-import javax.annotation.Nullable;
 import lombok.Getter;
 import org.apache.bookkeeper.client.AsyncCallback;
 import org.apache.bookkeeper.client.AsyncCallback.CreateCallback;
@@ -150,6 +149,7 @@
 import org.apache.pulsar.common.util.LazyLoadableValue;
 import org.apache.pulsar.common.util.collections.ConcurrentLongHashMap;
 import org.apache.pulsar.metadata.api.Stat;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

pom.xml

@@ -1639,6 +1639,11 @@ flexible messaging model and an intuitive client API.</description>
         <artifactId>checker-qual</artifactId>
         <version>${checkerframework.version}</version>
       </dependency>
+      <dependency>
+        <groupId>org.jspecify</groupId>
+        <artifactId>jspecify</artifactId>
+        <version>1.0.0</version>
+      </dependency>
 
       <dependency>
         <groupId>io.rest-assured</groupId>

pulsar-broker-auth-oidc/src/main/java/org/apache/pulsar/broker/authentication/oidc/OpenIDProviderMetadataCache.java

@@ -40,11 +40,11 @@
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
-import javax.annotation.Nonnull;
 import javax.naming.AuthenticationException;
 import org.apache.pulsar.broker.ServiceConfiguration;
 import org.apache.pulsar.broker.authentication.AuthenticationProvider;
 import org.asynchttpclient.AsyncHttpClient;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Class used to cache metadata responses from OpenID Providers.
@@ -94,7 +94,7 @@ class OpenIDProviderMetadataCache {
      * @return the {@link OpenIDProviderMetadata} for the given issuer. Fail the completable future with
      * AuthenticationException if any exceptions occur while retrieving the metadata.
      */
-    CompletableFuture<OpenIDProviderMetadata> getOpenIDProviderMetadataForIssuer(@Nonnull String issuer) {
+    CompletableFuture<OpenIDProviderMetadata> getOpenIDProviderMetadataForIssuer(@NonNull String issuer) {
         return cache.get(Optional.of(issuer));
     }
 
@@ -221,7 +221,7 @@ public void onDownloadProgress(long bytesRead, long contentLength, boolean done)
      * @param isK8s - whether the issuer is represented by the Kubernetes API server. This affects error reporting.
      * @throws AuthenticationException if the issuer does not exactly match the metadata issuer
      */
-    private void verifyIssuer(@Nonnull String issuer, OpenIDProviderMetadata metadata,
+    private void verifyIssuer(@NonNull String issuer, OpenIDProviderMetadata metadata,
                               boolean isK8s) throws AuthenticationException {
         if (!issuer.equals(metadata.getIssuer())) {
             if (isK8s) {

pulsar-broker/pom.xml

@@ -319,6 +319,10 @@
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+    </dependency>
 
     <dependency>
       <groupId>${project.groupId}</groupId>

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/NamespacesBase.java

@@ -43,7 +43,6 @@
 import java.util.function.Function;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
-import javax.annotation.Nonnull;
 import javax.ws.rs.WebApplicationException;
 import javax.ws.rs.container.AsyncResponse;
 import javax.ws.rs.core.Response;
@@ -118,6 +117,7 @@
 import org.apache.pulsar.metadata.api.MetadataStoreException.BadVersionException;
 import org.apache.pulsar.metadata.api.MetadataStoreException.NotFoundException;
 import org.apache.zookeeper.KeeperException;
+import org.jspecify.annotations.NonNull;
 
 @Slf4j
 public abstract class NamespacesBase extends AdminResource {
@@ -211,13 +211,13 @@ protected CompletableFuture<List<String>> internalGetNonPersistentTopics(Policie
      * Delete the namespace and retry to resolve some topics that were not created successfully(in metadata)
      * during the deletion.
      */
-    protected @Nonnull CompletableFuture<Void> internalDeleteNamespaceAsync(boolean force) {
+    protected @NonNull CompletableFuture<Void> internalDeleteNamespaceAsync(boolean force) {
         final CompletableFuture<Void> future = new CompletableFuture<>();
         internalRetryableDeleteNamespaceAsync0(force, 5, future);
         return future;
     }
     private void internalRetryableDeleteNamespaceAsync0(boolean force, int retryTimes,
-                                                        @Nonnull CompletableFuture<Void> callback) {
+                                                        @NonNull CompletableFuture<Void> callback) {
         precheckWhenDeleteNamespace(namespaceName, force)
                 .thenCompose(policies -> {
                     final CompletableFuture<List<String>> topicsFuture;

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/PersistentTopicsBase.java

@@ -49,7 +49,6 @@
 import java.util.function.BiConsumer;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
-import javax.annotation.Nonnull;
 import javax.ws.rs.WebApplicationException;
 import javax.ws.rs.container.AsyncResponse;
 import javax.ws.rs.core.Response;
@@ -151,6 +150,7 @@
 import org.apache.pulsar.compaction.Compactor;
 import org.apache.pulsar.metadata.api.MetadataStoreException;
 import org.apache.pulsar.transaction.coordinator.TransactionCoordinatorID;
+import org.jspecify.annotations.NonNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -357,7 +357,7 @@ protected CompletableFuture<Void> internalCreateNonPartitionedTopicAsync(boolean
      * @exception RestException Unprocessable entity, status code: 422. throw it when some pre-check failed.
      * @exception RestException Internal Server Error, status code: 500. throw it when get unknown Exception
      */
-    protected @Nonnull CompletableFuture<Void> internalUpdatePartitionedTopicAsync(int expectPartitions,
+    protected @NonNull CompletableFuture<Void> internalUpdatePartitionedTopicAsync(int expectPartitions,
                                                                                    boolean updateLocal,
                                                                                    boolean force) {
         PulsarService pulsarService = pulsar();

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v3/Transactions.java

@@ -56,7 +56,7 @@
 import org.apache.pulsar.common.policies.data.TransactionPendingAckStats;
 import org.apache.pulsar.common.stats.PositionInPendingAckStats;
 import org.apache.pulsar.common.util.FutureUtil;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 @Path("/transactions")
 @Produces(MediaType.APPLICATION_JSON)

pulsar-broker/src/main/java/org/apache/pulsar/broker/delayed/bucket/BookkeeperBucketSnapshotStorage.java

@@ -28,7 +28,6 @@
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
-import javax.validation.constraints.NotNull;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.bookkeeper.client.BKException;
 import org.apache.bookkeeper.client.BookKeeper;
@@ -41,6 +40,7 @@
 import org.apache.pulsar.broker.delayed.proto.SnapshotSegment;
 import org.apache.pulsar.common.allocator.PulsarByteBufAllocator;
 import org.apache.pulsar.common.util.FutureUtil;
+import org.jspecify.annotations.NonNull;
 
 @Slf4j
 public class BookkeeperBucketSnapshotStorage implements BucketSnapshotStorage {
@@ -165,7 +165,7 @@ private List<SnapshotSegment> parseSnapshotSegmentEntries(Enumeration<LedgerEntr
         return snapshotMetadataList;
     }
 
-    @NotNull
+    @NonNull
     private CompletableFuture<LedgerHandle> createLedger(String bucketKey, String topicName, String cursorName) {
         CompletableFuture<LedgerHandle> future = new CompletableFuture<>();
         Map<String, byte[]> metadata = LedgerMetadataUtils.buildMetadataForDelayedIndexBucket(bucketKey,

pulsar-broker/src/main/java/org/apache/pulsar/broker/namespace/NamespaceEphemeralData.java

@@ -21,10 +21,10 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
-import javax.validation.constraints.NotNull;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import org.apache.pulsar.policies.data.loadbalancer.AdvertisedListener;
+import org.jspecify.annotations.NonNull;
 
 @Data
 @NoArgsConstructor
@@ -55,7 +55,7 @@ public NamespaceEphemeralData(String brokerUrl, String brokerUrlTls, String http
         }
     }
 
-    @NotNull
+    @NonNull
     public Map<String, AdvertisedListener> getAdvertisedListeners() {
         if (this.advertisedListeners == null) {
             return Collections.emptyMap();

pulsar-broker/src/main/java/org/apache/pulsar/broker/namespace/NamespaceService.java

@@ -52,7 +52,6 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
-import javax.annotation.Nullable;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.collections4.ListUtils;
@@ -114,6 +113,7 @@
 import org.apache.pulsar.opentelemetry.annotations.PulsarDeprecatedMetric;
 import org.apache.pulsar.policies.data.loadbalancer.AdvertisedListener;
 import org.apache.pulsar.policies.data.loadbalancer.LocalBrokerData;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

pulsar-broker/src/main/java/org/apache/pulsar/broker/service/AbstractBaseDispatcher.java

@@ -53,7 +53,7 @@
 import org.apache.pulsar.common.protocol.Commands;
 import org.apache.pulsar.common.protocol.Markers;
 import org.apache.pulsar.compaction.Compactor;
-import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jspecify.annotations.Nullable;
 
 @Slf4j
 public abstract class AbstractBaseDispatcher extends EntryFilterSupport implements Dispatcher {

pulsar-broker/src/main/java/org/apache/pulsar/broker/service/AbstractTopic.java

@@ -46,7 +46,6 @@
 import java.util.concurrent.atomic.LongAdder;
 import java.util.concurrent.locks.ReentrantReadWriteLock;
 import java.util.function.ToLongFunction;
-import javax.annotation.Nonnull;
 import lombok.Getter;
 import lombok.Setter;
 import org.apache.bookkeeper.mledger.util.StatsBuckets;
@@ -88,6 +87,7 @@
 import org.apache.pulsar.common.protocol.schema.SchemaData;
 import org.apache.pulsar.common.protocol.schema.SchemaVersion;
 import org.apache.pulsar.common.util.FutureUtil;
+import org.jspecify.annotations.NonNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -1168,7 +1168,7 @@ public void updateResourceGroupLimiter(Optional<Policies> optPolicies) {
         updateResourceGroupLimiter(policies);
     }
 
-    public void updateResourceGroupLimiter(@Nonnull Policies namespacePolicies) {
+    public void updateResourceGroupLimiter(@NonNull Policies namespacePolicies) {
         requireNonNull(namespacePolicies);
         // attach the resource-group level rate limiters, if set
         String rgName = namespacePolicies.resource_group_name;

pulsar-broker/src/main/java/org/apache/pulsar/broker/service/BrokerService.java

@@ -80,8 +80,6 @@
 import java.util.concurrent.locks.ReentrantReadWriteLock;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
@@ -196,6 +194,8 @@
 import org.apache.pulsar.opentelemetry.annotations.PulsarDeprecatedMetric;
 import org.apache.pulsar.policies.data.loadbalancer.NamespaceBundleStats;
 import org.apache.pulsar.transaction.coordinator.TransactionMetadataStore;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -1202,7 +1202,7 @@ public CompletableFuture<Optional<Topic>> getTopic(final TopicName topicName, bo
         }
     }
 
-    private CompletableFuture<Optional<TopicPolicies>> getTopicPoliciesBypassSystemTopic(@Nonnull TopicName topicName) {
+    private CompletableFuture<Optional<TopicPolicies>> getTopicPoliciesBypassSystemTopic(@NonNull TopicName topicName) {
         if (ExtensibleLoadManagerImpl.isInternalTopic(topicName.toString())) {
             return CompletableFuture.completedFuture(Optional.empty());
         }
@@ -1935,14 +1935,14 @@ private CompletableFuture<Void> checkTopicAlreadyMigrated(TopicName topicName) {
         return result;
     }
 
-    public CompletableFuture<ManagedLedgerConfig> getManagedLedgerConfig(@Nonnull TopicName topicName) {
+    public CompletableFuture<ManagedLedgerConfig> getManagedLedgerConfig(@NonNull TopicName topicName) {
         final CompletableFuture<Optional<TopicPolicies>> topicPoliciesFuture =
                 getTopicPoliciesBypassSystemTopic(topicName);
         return topicPoliciesFuture.thenCompose(optionalTopicPolicies ->
                 getManagedLedgerConfig(topicName, optionalTopicPolicies.orElse(null)));
     }
 
-    private CompletableFuture<ManagedLedgerConfig> getManagedLedgerConfig(@Nonnull TopicName topicName,
+    private CompletableFuture<ManagedLedgerConfig> getManagedLedgerConfig(@NonNull TopicName topicName,
                                                                           @Nullable TopicPolicies topicPolicies) {
         requireNonNull(topicName);
         NamespaceName namespace = topicName.getNamespaceObject();
@@ -3598,7 +3598,7 @@ private AutoTopicCreationOverride getAutoTopicCreationOverride(final TopicName t
         return null;
     }
 
-    public @Nonnull CompletableFuture<Boolean> isAllowAutoSubscriptionCreationAsync(@Nonnull TopicName tpName) {
+    public @NonNull CompletableFuture<Boolean> isAllowAutoSubscriptionCreationAsync(@NonNull TopicName tpName) {
         requireNonNull(tpName);
         // Policies priority: topic level -> namespace level -> broker level
         if (ExtensibleLoadManagerImpl.isInternalTopic(tpName.toString())) {

pulsar-broker/src/main/java/org/apache/pulsar/broker/service/ConsumerHashAssignmentsSnapshot.java

@@ -32,7 +32,7 @@
 import lombok.ToString;
 import org.apache.commons.lang3.tuple.Pair;
 import org.apache.pulsar.client.api.Range;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Represents the hash ranges assigned to each consumer in a {@link StickyKeyConsumerSelector} at a point in time.
@@ -86,7 +86,7 @@ public synchronized Map<Consumer, List<Range>> getRangesByConsumer() {
         return cachedRangesByConsumer;
     }
 
-    private @NotNull Map<Consumer, List<Range>> internalGetRangesByConsumer() {
+    private @NonNull Map<Consumer, List<Range>> internalGetRangesByConsumer() {
         Map<Consumer, SortedSet<Range>> rangesByConsumer = new IdentityHashMap<>();
         hashRangeAssignments.forEach(entry -> {
             Range range = entry.range();

pulsar-broker/src/main/java/org/apache/pulsar/broker/service/EntryAndMetadata.java

@@ -21,12 +21,12 @@
 import com.google.common.annotations.VisibleForTesting;
 import io.netty.buffer.ByteBuf;
 import java.util.function.ToIntFunction;
-import javax.annotation.Nullable;
 import lombok.Getter;
 import org.apache.bookkeeper.mledger.Entry;
 import org.apache.bookkeeper.mledger.Position;
 import org.apache.pulsar.common.api.proto.MessageMetadata;
 import org.apache.pulsar.common.protocol.Commands;
+import org.jspecify.annotations.Nullable;
 
 public class EntryAndMetadata implements Entry {
     private static final int STICKY_KEY_HASH_NOT_INITIALIZED = -1;