mark all APIs nullable/non-nullable

JSpecify is de-facto standard annotations for marking nullability of variables, parameters, return values and fields. Supported by all IDEs.

1. By default, we mark everything as non-nullable (see @NullMarked in package-info.java)
2. When needed, we mark the nullable parameters/fields as @nullable.

Author: asolntsev

pom.xml

@@ -37,6 +37,8 @@
         <jbanking.version>4.3.0</jbanking.version>
         <junit.version>6.0.3</junit.version>
         <libphonenumber.version>9.0.24</libphonenumber.version>
+        <jspecify.version>1.0.0</jspecify.version>
+        <error_prone.version>2.42.0</error_prone.version>
         <maven.compiler.source>17</maven.compiler.source>
         <maven.compiler.target>17</maven.compiler.target>
         <maven-compiler-plugin.version>3.15.0</maven-compiler-plugin.version>
@@ -89,6 +91,20 @@
             <version>${libphonenumber.version}</version>
         </dependency>
 
+        <!-- Annotations for nullability etc. -->
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+            <version>${jspecify.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.google.errorprone</groupId>
+            <artifactId>error_prone_annotations</artifactId>
+            <version>${error_prone.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
         <!-- Test dependencies -->
         <dependency>
             <groupId>org.junit.jupiter</groupId>

src/main/java/net/datafaker/annotations/FakeResolver.java

@@ -8,6 +8,7 @@
 import net.datafaker.internal.helper.CopyOnWriteMap;
 import net.datafaker.transformations.JavaObjectTransformer;
 import net.datafaker.transformations.Schema;
+import org.jspecify.annotations.Nullable;
 
 import static java.util.Objects.requireNonNull;
 
@@ -24,19 +25,22 @@ private FakeResolver(Class<T> clazz) {
         this.clazz = clazz;
     }
 
+    @SuppressWarnings("unchecked")
     public static <T> FakeResolver<T> of(Class<T> clazz) {
         var fakeFactory = CLASS_2_FAKE_RESOLVER.computeIfAbsent(clazz, k -> new FakeResolver<>(clazz));
         return (FakeResolver<T>) fakeFactory;
     }
 
-    public T generate(Schema<Object, ?> schema) {
+    @SuppressWarnings("unchecked")
+    public T generate(@Nullable Schema<Object, ?> schema) {
         if (schema == null) {
             return generateFromDefaultSchema();
         }
 
         return (T) JAVA_OBJECT_TRANSFORMER.apply(clazz, schema);
     }
 
+    @SuppressWarnings("unchecked")
     private T generateFromDefaultSchema() {
         Schema<Object, ?> useSchema = DEFAULT_SCHEMA_CACHE.computeIfAbsent(clazz, (__) -> {
             FakeForSchema fakeForSchemaAnnotation = checkFakeAnnotation(clazz);
@@ -46,28 +50,27 @@ private T generateFromDefaultSchema() {
         return (T) JAVA_OBJECT_TRANSFORMER.apply(clazz, useSchema);
     }
 
+    @SuppressWarnings("unchecked")
     private Schema<Object, T> getSchema(String pathToSchema) {
-        if (pathToSchema != null) {
-            try {
-                // indexOf(<String>) is faster than indexOf(<char>) since it has jvm intrinsic
-                final int sharpIndex = pathToSchema.indexOf("#");
-                final Class<?> classToCall;
-                final String methodName;
-                if (sharpIndex >= 0) {
-                    classToCall = Class.forName(pathToSchema.substring(0, sharpIndex));
-                    methodName = pathToSchema.substring(sharpIndex + 1);
-                } else {
-                    classToCall = this.clazz.getEnclosingClass();
-                    methodName = pathToSchema;
-                }
-                Method myStaticMethod = classToCall.getMethod(methodName);
-                myStaticMethod.setAccessible(true);
-                return (Schema<Object, T>) myStaticMethod.invoke(null);
-            } catch (ClassNotFoundException | NoSuchMethodException | InvocationTargetException | IllegalAccessException e) {
-                throw new RuntimeException(e);
+        requireNonNull(pathToSchema, "The path to the schema is empty.");
+
+        try {
+            // indexOf(<String>) is faster than indexOf(<char>) since it has jvm intrinsic
+            final int sharpIndex = pathToSchema.indexOf("#");
+            final Class<?> classToCall;
+            final String methodName;
+            if (sharpIndex >= 0) {
+                classToCall = Class.forName(pathToSchema.substring(0, sharpIndex));
+                methodName = pathToSchema.substring(sharpIndex + 1);
+            } else {
+                classToCall = this.clazz.getEnclosingClass();
+                methodName = pathToSchema;
             }
-        } else {
-            throw new IllegalArgumentException("The path to the schema is empty.");
+            Method myStaticMethod = classToCall.getMethod(methodName);
+            myStaticMethod.setAccessible(true);
+            return (Schema<Object, T>) myStaticMethod.invoke(null);
+        } catch (ClassNotFoundException | NoSuchMethodException | InvocationTargetException | IllegalAccessException e) {
+            throw new RuntimeException(e);
         }
     }
 

src/main/java/net/datafaker/annotations/package-info.java

@@ -0,0 +1,7 @@
+@NullMarked
+@CheckReturnValue
+package net.datafaker.annotations;
+
+import com.google.errorprone.annotations.CheckReturnValue;
+
+import org.jspecify.annotations.NullMarked;

src/main/java/net/datafaker/idnumbers/EstonianIdNumber.java

@@ -13,7 +13,7 @@
 import static net.datafaker.idnumbers.Utils.randomGender;
 
 /**
- * Estonian personal identification number ("Isikukood" in estonian)
+ * Estonian personal identification number ("Isikukood" in Estonian)
  * <p>
  * The number is 11 digits, with modulus 11 checksum digit.
  * There is fixed list of valid first digits to signify gender and birth century

src/main/java/net/datafaker/idnumbers/HungarianIdNumber.java

@@ -64,12 +64,12 @@ private String basePart(BaseProviders faker, LocalDate birthday, PersonIdNumber.
 
     static int getCheckDigit(String basePart) {
         char[] numbers = basePart.toCharArray();
-        int summ = 0;
+        int sum = 0;
         for (int i = 0; i < numbers.length; i++) {
-            summ += getNumericValue(numbers[i]) * (i + 1);
+            sum += getNumericValue(numbers[i]) * (i + 1);
         }
 
-        return summ % 11;
+        return sum % 11;
     }
 
     static int firstDigit(int birthYear, PersonIdNumber.Gender gender) {

src/main/java/net/datafaker/idnumbers/IdNumberGenerator.java

@@ -27,7 +27,7 @@ default String generateValid(BaseProviders faker) {
     String generateInvalid(BaseProviders faker);
 
     /**
-     * Generates a valid ID number for given country corresponding to given criterias (age range, gender etc.)
+     * Generates a valid ID number for given country corresponding to given criteria (age range, gender etc.)
      *
      * @return PersonIdNumber containing a valid combination of ID, Birthday and Gender.
      * In countries where ID number doesn't contain gender and/or birthday, the latter values are just random.

src/main/java/net/datafaker/idnumbers/PolishIdNumber.java

@@ -4,6 +4,7 @@
 import net.datafaker.providers.base.IdNumber.GenderRequest;
 import net.datafaker.providers.base.IdNumber.IdNumberRequest;
 import net.datafaker.providers.base.PersonIdNumber;
+import org.jspecify.annotations.Nullable;
 
 import java.time.LocalDate;
 
@@ -52,7 +53,7 @@ public String get(BaseProviders faker, LocalDate birthDate, Gender requestedGend
         return get(faker, birthDate, gender);
     }
 
-    private static PersonIdNumber.Gender pickGender(BaseProviders faker, Gender requestedGender) {
+    private static PersonIdNumber.Gender pickGender(BaseProviders faker, @Nullable Gender requestedGender) {
         return requestedGender == null ? randomGender(faker) :
             switch (requestedGender) {
                 case ANY -> randomGender(faker);

src/main/java/net/datafaker/idnumbers/package-info.java

@@ -0,0 +1,6 @@
+@NullMarked
+@CheckReturnValue
+package net.datafaker.idnumbers;
+
+import com.google.errorprone.annotations.CheckReturnValue;
+import org.jspecify.annotations.NullMarked;

src/main/java/net/datafaker/idnumbers/pt/br/IdNumberGeneratorPtBrUtil.java

@@ -108,7 +108,7 @@ public static boolean isCNPJValid(final String cnpj) {
 
     /**
      * Return true if the CPF is valid
-     * A valid CPF is unique and have a algorithm to validate it
+     * A valid CPF is unique and have an algorithm to validate it
      * <p>
      * CPF generator could generate a valid or invalid because, sometimes, we need to test a
      * registration with invalid number

src/main/java/net/datafaker/idnumbers/pt/br/package-info.java

@@ -0,0 +1,6 @@
+@NullMarked
+@CheckReturnValue
+package net.datafaker.idnumbers.pt.br;
+
+import com.google.errorprone.annotations.CheckReturnValue;
+import org.jspecify.annotations.NullMarked;