refactor(core): replace jakarta annotation with jspecify for nullability

- Replace jakarta.annotation.Nonnull with org.jspecify.annotations.NonNull
- Replace jakarta.annotation.Nullable with org.jspecify.annotations.Nullable
- Update build.gradle.kts to use jspecify dependency instead of jakarta.annotation.api
- Update libs.versions.toml to reference jspecify version 1.0.0
- Apply jspecify annotations consistently across all affected classes
- Remove deprecated jakarta annotation imports from all files

Author: Ahoo-Wang

cosid-core/build.gradle.kts

@@ -12,6 +12,6 @@
  */
 
 dependencies {
-    api(libs.jakarta.annotation.api)
+    api(libs.jspecify)
     testImplementation(project(":cosid-test"))
 }

cosid-core/src/main/java/me/ahoo/cosid/Decorator.java

@@ -1,7 +1,7 @@
 package me.ahoo.cosid;
 
 import com.google.errorprone.annotations.ThreadSafe;
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Decorator pattern interface for wrapping and enhancing ID generators.
@@ -36,7 +36,7 @@ public interface Decorator<D> {
      *
      * @return The actual object being decorated
      */
-    @Nonnull
+    @NonNull
     D getActual();
 
     /**

cosid-core/src/main/java/me/ahoo/cosid/IdConverter.java

@@ -17,7 +17,7 @@
 import me.ahoo.cosid.stat.Statistical;
 
 import com.google.errorprone.annotations.ThreadSafe;
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * ID converter for transforming between numeric and string representations of IDs.
@@ -52,7 +52,7 @@ public interface IdConverter extends Statistical {
      * @param id The {@code long} type ID to convert
      * @return The {@link String} representation of the ID
      */
-    @Nonnull
+    @NonNull
     String asString(long id);
 
     /**
@@ -66,7 +66,7 @@ public interface IdConverter extends Statistical {
      * @param idString The {@link String} type ID to convert
      * @return The {@code long} representation of the ID
      */
-    long asLong(@Nonnull String idString);
+    long asLong(@NonNull String idString);
 
     /**
      * Get statistical information about this converter.

cosid-core/src/main/java/me/ahoo/cosid/IdGenerator.java

@@ -18,7 +18,7 @@
 import me.ahoo.cosid.stat.generator.IdGeneratorStat;
 
 import com.google.errorprone.annotations.ThreadSafe;
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Id Generator.
@@ -51,7 +51,7 @@ public interface IdGenerator extends StringIdGenerator, Statistical {
      *
      * @return ID converter for transforming numeric IDs to string format
      */
-    @Nonnull
+    @NonNull
     default IdConverter idConverter() {
         return Radix62IdConverter.PAD_START;
     }
@@ -76,9 +76,8 @@ default IdConverter idConverter() {
      *
      * @return A unique distributed ID as a string value
      */
-    @Nonnull
     @Override
-    default String generateAsString() {
+    default @NonNull String generateAsString() {
         return idConverter().asString(generate());
     }
 

cosid-core/src/main/java/me/ahoo/cosid/IdGeneratorDecorator.java

@@ -3,7 +3,7 @@
 import me.ahoo.cosid.stat.generator.IdGeneratorStat;
 
 import com.google.errorprone.annotations.ThreadSafe;
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * IdGenerator decorator for enhancing ID generator functionality.
@@ -38,7 +38,7 @@ public interface IdGeneratorDecorator extends IdGenerator, Decorator<IdGenerator
      *
      * @return The actual ID generator being decorated
      */
-    @Nonnull
+    @NonNull
     IdGenerator getActual();
 
     /**

cosid-core/src/main/java/me/ahoo/cosid/IntegerIdGenerator.java

@@ -14,7 +14,7 @@
 package me.ahoo.cosid;
 
 import com.google.errorprone.annotations.ThreadSafe;
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Integer ID generator that adapts a long-based ID generator to produce integer IDs.
@@ -91,9 +91,8 @@ public int generate() throws IdOverflowException {
      * @return A unique distributed ID as a string value
      * @throws IdOverflowException if the generated long ID exceeds the integer range
      */
-    @Nonnull
     @Override
-    public String generateAsString() throws IdOverflowException {
+    public @NonNull String generateAsString() throws IdOverflowException {
         long id = actual.generate();
         ensureInteger(id);
         return actual.idConverter().asString(id);

cosid-core/src/main/java/me/ahoo/cosid/StringIdGenerator.java

@@ -15,7 +15,7 @@
 
 
 import com.google.errorprone.annotations.ThreadSafe;
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * String type ID generator.
@@ -40,6 +40,6 @@ public interface StringIdGenerator {
      *
      * @return A unique distributed ID as a string value
      */
-    @Nonnull
+    @NonNull
     String generateAsString();
 }

cosid-core/src/main/java/me/ahoo/cosid/StringIdGeneratorDecorator.java

@@ -13,7 +13,7 @@
 
 package me.ahoo.cosid;
 
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * String ID generator decorator for customizing string ID generation.
@@ -72,9 +72,8 @@ public StringIdGeneratorDecorator(IdGenerator actual, IdConverter idConverter) {
      *
      * @return The custom ID converter
      */
-    @Nonnull
     @Override
-    public IdConverter idConverter() {
+    public @NonNull IdConverter idConverter() {
         return idConverter;
     }
 
@@ -86,7 +85,7 @@ public IdConverter idConverter() {
      *
      * @return The actual ID generator being decorated
      */
-    @Nonnull
+    @NonNull
     @Override
     public IdGenerator getActual() {
         return actual;

cosid-core/src/main/java/me/ahoo/cosid/converter/DatePrefixIdConverter.java

@@ -18,7 +18,7 @@
 import me.ahoo.cosid.stat.Stat;
 import me.ahoo.cosid.stat.converter.DatePrefixConverterStat;
 
-import jakarta.annotation.Nonnull;
+import org.jspecify.annotations.NonNull;
 
 import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
@@ -37,22 +37,20 @@ public DatePrefixIdConverter(String pattern, String delimiter, IdConverter actua
     }
 
 
-    @Nonnull
     @Override
-    public String asString(long id) {
+    public @NonNull String asString(long id) {
         return LocalDateTime.now().format(formatter) + delimiter + actual.asString(id);
     }
 
     @Override
-    public long asLong(@Nonnull String idString) {
+    public long asLong(@NonNull String idString) {
         int appendedLength = pattern.length() + delimiter.length();
         String idStr = idString.substring(appendedLength);
         return actual.asLong(idStr);
     }
 
-    @Nonnull
     @Override
-    public IdConverter getActual() {
+    public @NonNull IdConverter getActual() {
         return actual;
     }
 

cosid-core/src/main/java/me/ahoo/cosid/converter/GroupedPrefixIdConverter.java

@@ -19,8 +19,8 @@
 import me.ahoo.cosid.stat.Stat;
 import me.ahoo.cosid.stat.converter.GroupedPrefixConverterStat;
 
-import jakarta.annotation.Nonnull;
 import com.google.common.base.Preconditions;
+import org.jspecify.annotations.NonNull;
 
 public class GroupedPrefixIdConverter implements IdConverter, Decorator<IdConverter> {
     public static final String DEFAULT_DELIMITER = "-";
@@ -33,19 +33,17 @@ public GroupedPrefixIdConverter(String delimiter, IdConverter actual) {
         this.actual = actual;
     }
 
-    @Nonnull
     @Override
-    public IdConverter getActual() {
+    public @NonNull IdConverter getActual() {
         return actual;
     }
 
     public String getDelimiter() {
         return delimiter;
     }
 
-    @Nonnull
     @Override
-    public String asString(long id) {
+    public @NonNull String asString(long id) {
         String idStr = actual.asString(id);
         String groupKey = GroupedAccessor.requiredGet().getKey();
         if (delimiter.isEmpty()) {
@@ -55,7 +53,7 @@ public String asString(long id) {
     }
 
     @Override
-    public long asLong(@Nonnull String idString) {
+    public long asLong(@NonNull String idString) {
         throw new UnsupportedOperationException("GroupedPrefixIdConverter does not support converting String to Long!");
     }