Migrate from JSR 305 to JSpecify.

cthing · Oct 25, 2024 · 2068f05 · 2068f05
1 parent da19bd3
commit 2068f05
Show file tree

Hide file tree

Showing 17 changed files with 198 additions and 237 deletions.
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -28,7 +28,7 @@ plugins {
     alias(libs.plugins.versions)
 }
 
-version = ProjectVersion("1.0.1", BuildType.snapshot)
+version = ProjectVersion("2.0.0", BuildType.snapshot)
 group = "org.cthing"
 description = "A Java library for escaping strings for use in various languages (e.g. XML)."
 
@@ -39,9 +39,9 @@ java {
 }
 
 dependencies {
-    api(libs.jsr305)
+    api(libs.jspecify)
 
-    implementation(libs.cthingAnnots)
+    compileOnly(libs.cthingAnnots)
 
     testImplementation(libs.junitApi)
     testImplementation(libs.junitParams)

diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -13,8 +13,8 @@ versions = { id = "com.github.ben-manes.versions", version = "0.51.0" }
 
 [libraries]
 assertJ = "org.assertj:assertj-core:3.26.3"
-cthingAnnots = "org.cthing:cthing-annotations:1.0.0"
-jsr305 = "com.google.code.findbugs:jsr305:3.0.2"
+cthingAnnots = "org.cthing:cthing-annotations:2.0.0"
+jspecify = "org.jspecify:jspecify:1.0.0"
 junitApi = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit" }
 junitEngine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit" }
 junitLauncher = "org.junit.platform:junit-platform-launcher:1.11.2"

diff --git a/src/main/java/org/cthing/escapers/CsvEscaper.java b/src/main/java/org/cthing/escapers/CsvEscaper.java
@@ -10,9 +10,8 @@
 import java.io.UncheckedIOException;
 import java.io.Writer;
 
-import javax.annotation.WillNotClose;
-
 import org.cthing.annotations.NoCoverageGenerated;
+import org.jspecify.annotations.Nullable;
 
 
 /**
@@ -34,7 +33,8 @@ private CsvEscaper() {
      * @param charSequence String to escape
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final CharSequence charSequence) {
+    @Nullable
+    public static String escape(@Nullable final CharSequence charSequence) {
         return (charSequence == null)
                ? null : escape(index -> Character.codePointAt(charSequence, index), 0, charSequence.length());
     }
@@ -43,12 +43,11 @@ public static String escape(final CharSequence charSequence) {
      * Applies CSV escaping to the specified string and writes the result to the specified writer.
      *
      * @param charSequence String to escape
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final CharSequence charSequence, final Writer writer) throws IOException {
+    public static void escape(@Nullable final CharSequence charSequence, final Writer writer) throws IOException {
         if (charSequence != null) {
             escape(index -> Character.codePointAt(charSequence, index), 0, charSequence.length(), writer);
         }
@@ -60,7 +59,8 @@ public static void escape(final CharSequence charSequence, final Writer writer)
      * @param charArr Character array to escape
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final char[] charArr) {
+    @Nullable
+    public static String escape(final char @Nullable[] charArr) {
         return (charArr == null) ? null : escape(index -> Character.codePointAt(charArr, index), 0, charArr.length);
     }
 
@@ -72,20 +72,20 @@ public static String escape(final char[] charArr) {
      * @param length Number of characters in array
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final char[] charArr, final int offset, final int length) {
+    @Nullable
+    public static String escape(final char @Nullable[] charArr, final int offset, final int length) {
         return (charArr == null) ? null : escape(index -> Character.codePointAt(charArr, index), offset, length);
     }
 
     /**
      * Applies CSV escaping to the specified character array and writes the result to the specified writer.
      *
      * @param charArr Character array to escape
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final char[] charArr, final Writer writer) throws IOException {
+    public static void escape(final char @Nullable[] charArr, final Writer writer) throws IOException {
         if (charArr != null) {
             escape(index -> Character.codePointAt(charArr, index), 0, charArr.length, writer);
         }
@@ -97,12 +97,11 @@ public static void escape(final char[] charArr, final Writer writer) throws IOEx
      * @param charArr Character array to escape
      * @param offset Start index in array
      * @param length Number of characters in array
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final char[] charArr, final int offset, final int length, final Writer writer)
+    public static void escape(final char @Nullable[] charArr, final int offset, final int length, final Writer writer)
             throws IOException {
         if (charArr != null) {
             escape(index -> Character.codePointAt(charArr, index), offset, length, writer);
@@ -120,11 +119,7 @@ private static String escape(final CodePointProvider codePointProvider, final in
     }
 
     private static void escape(final CodePointProvider codePointProvider, final int offset, final int length,
-                               final Writer writer)
-            throws IOException {
-        if (writer == null) {
-            throw new IllegalArgumentException("writer must not be null");
-        }
+                               final Writer writer) throws IOException {
         if (length < 0) {
             throw new IndexOutOfBoundsException("length must be greater than or equal to 0");
         }

diff --git a/src/main/java/org/cthing/escapers/HtmlEscaper.java b/src/main/java/org/cthing/escapers/HtmlEscaper.java
@@ -12,9 +12,8 @@
 import java.util.Set;
 import java.util.function.Function;
 
-import javax.annotation.WillNotClose;
-
 import org.cthing.annotations.NoCoverageGenerated;
+import org.jspecify.annotations.Nullable;
 
 
 /**
@@ -207,7 +206,8 @@ private HtmlEscaper() {
      * @param options Escaping options
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final CharSequence charSequence, final Option... options) {
+    @Nullable
+    public static String escape(@Nullable final CharSequence charSequence, final Option... options) {
         return (charSequence == null)
                ? null
                : escape(index -> Character.codePointAt(charSequence, index), 0, charSequence.length(),
@@ -221,7 +221,8 @@ public static String escape(final CharSequence charSequence, final Option... opt
      * @param options Escaping options
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final CharSequence charSequence, final Set<Option> options) {
+    @Nullable
+    public static String escape(@Nullable final CharSequence charSequence, final Set<Option> options) {
         return (charSequence == null)
                ? null : escape(index -> Character.codePointAt(charSequence, index), 0, charSequence.length(), options);
     }
@@ -230,13 +231,12 @@ public static String escape(final CharSequence charSequence, final Set<Option> o
      * Applies HTML escaping to the specified string and writes the result to the specified writer.
      *
      * @param charSequence String to escape
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @param options Escaping options
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final CharSequence charSequence, final Writer writer, final Option... options)
+    public static void escape(@Nullable final CharSequence charSequence, final Writer writer, final Option... options)
             throws IOException {
         if (charSequence != null) {
             escape(index -> Character.codePointAt(charSequence, index), 0, charSequence.length(), writer,
@@ -248,13 +248,12 @@ public static void escape(final CharSequence charSequence, final Writer writer,
      * Applies HTML escaping to the specified string and writes the result to the specified writer.
      *
      * @param charSequence String to escape
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @param options Escaping options
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final CharSequence charSequence, final Writer writer, final Set<Option> options)
+    public static void escape(@Nullable final CharSequence charSequence, final Writer writer, final Set<Option> options)
             throws IOException {
         if (charSequence != null) {
             escape(index -> Character.codePointAt(charSequence, index), 0, charSequence.length(), writer, options);
@@ -268,7 +267,8 @@ public static void escape(final CharSequence charSequence, final Writer writer,
      * @param options Escaping options
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final char[] charArr, final Option... options) {
+    @Nullable
+    public static String escape(final char @Nullable[] charArr, final Option... options) {
         return (charArr == null)
                ? null
                : escape(index -> Character.codePointAt(charArr, index), 0, charArr.length,
@@ -284,7 +284,9 @@ public static String escape(final char[] charArr, final Option... options) {
      * @param options Escaping options
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final char[] charArr, final int offset, final int length, final Option... options) {
+    @Nullable
+    public static String escape(final char @Nullable[] charArr, final int offset, final int length,
+                                final Option... options) {
         return (charArr == null)
                ? null
                : escape(index -> Character.codePointAt(charArr, index), offset, length,
@@ -298,7 +300,8 @@ public static String escape(final char[] charArr, final int offset, final int le
      * @param options Escaping options
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final char[] charArr, final Set<Option> options) {
+    @Nullable
+    public static String escape(final char @Nullable[] charArr, final Set<Option> options) {
         return (charArr == null)
                ? null : escape(index -> Character.codePointAt(charArr, index), 0, charArr.length, options);
     }
@@ -312,7 +315,9 @@ public static String escape(final char[] charArr, final Set<Option> options) {
      * @param options Escaping options
      * @return Escaped string or {@code null} if {@code null} was passed in.
      */
-    public static String escape(final char[] charArr, final int offset, final int length, final Set<Option> options) {
+    @Nullable
+    public static String escape(final char @Nullable[] charArr, final int offset, final int length,
+                                final Set<Option> options) {
         return (charArr == null)
                ? null : escape(index -> Character.codePointAt(charArr, index), offset, length, options);
     }
@@ -321,13 +326,13 @@ public static String escape(final char[] charArr, final int offset, final int le
      * Applies HTML escaping to the specified character array and writes the result to the specified writer.
      *
      * @param charArr Character array to escape
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @param options Escaping options
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final char[] charArr, final Writer writer, final Option... options) throws IOException {
+    public static void escape(final char @Nullable[] charArr, final Writer writer, final Option... options)
+            throws IOException {
         if (charArr != null) {
             escape(index -> Character.codePointAt(charArr, index), 0, charArr.length, writer,
                    toEnumSet(HtmlEscaper.Option.class, options));
@@ -340,13 +345,12 @@ public static void escape(final char[] charArr, final Writer writer, final Optio
      * @param charArr Character array to escape
      * @param offset Start index in array
      * @param length Number of characters in array
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @param options Escaping options
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final char[] charArr, final int offset, final int length, final Writer writer,
+    public static void escape(final char @Nullable[] charArr, final int offset, final int length, final Writer writer,
                               final Option... options) throws IOException {
         if (charArr != null) {
             escape(index -> Character.codePointAt(charArr, index), offset, length, writer,
@@ -358,13 +362,13 @@ public static void escape(final char[] charArr, final int offset, final int leng
      * Applies HTML escaping to the specified character array and writes the result to the specified writer.
      *
      * @param charArr Character array to escape
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @param options Escaping options
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final char[] charArr, final Writer writer, final Set<Option> options) throws IOException {
+    public static void escape(final char @Nullable[] charArr, final Writer writer, final Set<Option> options)
+            throws IOException {
         if (charArr != null) {
             escape(index -> Character.codePointAt(charArr, index), 0, charArr.length, writer, options);
         }
@@ -376,13 +380,12 @@ public static void escape(final char[] charArr, final Writer writer, final Set<O
      * @param charArr Character array to escape
      * @param offset Start index in array
      * @param length Number of characters in array
-     * @param writer Writer to which the escaped string is written
+     * @param writer Writer to which the escaped string is written. Will not be closed by this method.
      * @param options Escaping options
      * @throws IOException if there was a problem writing the escaped string
      * @throws IllegalArgumentException if the writer is {@code null}
      */
-    @WillNotClose
-    public static void escape(final char[] charArr, final int offset, final int length, final Writer writer,
+    public static void escape(final char @Nullable[] charArr, final int offset, final int length, final Writer writer,
                               final Set<Option> options) throws IOException {
         if (charArr != null) {
             escape(index -> Character.codePointAt(charArr, index), offset, length, writer, options);
@@ -402,9 +405,6 @@ private static String escape(final CodePointProvider codePointProvider, final in
 
     private static void escape(final CodePointProvider codePointProvider, final int offset, final int length,
                                final Writer writer, final Set<Option> options) throws IOException {
-        if (writer == null) {
-            throw new IllegalArgumentException("writer must not be null");
-        }
         if (length < 0) {
             throw new IndexOutOfBoundsException("length must be greater than or equal to 0");
         }
@@ -415,7 +415,7 @@ private static void escape(final CodePointProvider codePointProvider, final int
         final boolean useLatin1 = options.contains(Option.USE_ISO_LATIN_1_ENTITIES);
         final boolean useExtended = options.contains(Option.USE_HTML4_EXTENDED_ENTITIES);
 
-        final Function<Integer, String> findEntity;
+        final Function<Integer, @Nullable String> findEntity;
         if (!useLatin1 && !useExtended) {
             findEntity = HtmlEntities.MARKUP_SIGNIFICANT::get;
         } else {