refactor: introduce Nullable annotation

osiegmar · osiegmar · commit bba1412be9c2 · 2025-06-14T14:40:47.000+02:00
diff --git a/docs/src/content/docs/architecture/goals.md b/docs/src/content/docs/architecture/goals.md
@@ -61,7 +61,10 @@ provides detailed information on how to use the library.
 FastCSV is designed to be maintainable to ensure its longevity, continued development and support.
 Checkout our [FAQ](/faq/) for more information on how to get help and how to contribute.
 
-[Spotbugs](https://spotbugs.github.io), [PMD](https://pmd.github.io) and
+[Spotbugs](https://spotbugs.github.io),
+[PMD](https://pmd.github.io),
+[Error Prone](https://errorprone.info),
+[NullAway](https://github.com/uber/NullAway) and
 [Checkstyle](https://checkstyle.sourceforge.io) are used to ensure the quality of the code.
 
 ## Non-Goals
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -6,6 +6,7 @@ gummy-bears = { module = "com.toasttab.android:gummy-bears-api-34", version = "0
 spotbugs = { module = "com.github.spotbugs.snom:spotbugs-gradle-plugin", version = "6.1.11" }
 jackson-dataformat-yaml = { module = "com.fasterxml.jackson.dataformat:jackson-dataformat-yaml", version = "2.18.3" }
 errorprone = { module = "com.google.errorprone:error_prone_core", version = "2.38.0" }
+nullaway = { module = "com.uber.nullaway:nullaway", version = "0.12.7" }
 
 [plugins]
 jmh = { id = "me.champeau.jmh", version = "0.7.3" }
diff --git a/lib/build.gradle.kts b/lib/build.gradle.kts
@@ -1,5 +1,6 @@
 @file:Suppress("StringLiteralDuplication")
 import net.ltgt.gradle.errorprone.errorprone
+import org.gradle.kotlin.dsl.errorprone
 
 plugins {
     id("fastcsv.java-conventions")
@@ -27,12 +28,19 @@ java {
 tasks.withType<JavaCompile>().configureEach {
     if (name == "compileJmhJava") {
         options.errorprone.isEnabled.set(false)
+    } else if (name == "compileTestJava" || name == "compileIntTestJava") {
+        options.errorprone.disable("NullAway")
+    } else {
+        options.errorprone {
+            option("NullAway:AnnotatedPackages", "de.siegmar.fastcsv")
+        }
     }
 }
 
 tasks.compileJava {
     options.release.set(17)
     options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror"))
+    options.errorprone.error("NullAway")
 }
 
 // enable parameter names for tests with @ParameterizedTest
@@ -68,6 +76,7 @@ configurations[intTest.runtimeOnlyConfigurationName].extendsFrom(configurations.
 
 dependencies {
     errorprone(libs.errorprone)
+    errorprone(libs.nullaway)
 
     commonImplementation(libs.assertj.core)
 
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/AbstractBaseCsvCallbackHandler.java b/lib/src/main/java/de/siegmar/fastcsv/reader/AbstractBaseCsvCallbackHandler.java
@@ -8,7 +8,7 @@
 public abstract class AbstractBaseCsvCallbackHandler<T> extends CsvCallbackHandler<T> {
 
     private long startingLineNumber;
-    private RecordType recordType;
+    private RecordType recordType = RecordType.DATA;
     private int fieldCount;
 
     /// Constructs a new instance.
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/AbstractInternalCsvCallbackHandler.java b/lib/src/main/java/de/siegmar/fastcsv/reader/AbstractInternalCsvCallbackHandler.java
@@ -39,7 +39,7 @@ public abstract sealed class AbstractInternalCsvCallbackHandler<T> extends CsvCa
     protected int fieldIdx;
 
     /// The type of the current record.
-    protected RecordType recordType;
+    protected RecordType recordType = RecordType.DATA;
 
     /// Constructs a new instance with the given configuration.
     ///
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/BomInputStreamReader.java b/lib/src/main/java/de/siegmar/fastcsv/reader/BomInputStreamReader.java
@@ -6,11 +6,15 @@
 import java.io.Reader;
 import java.nio.charset.Charset;
 
+import de.siegmar.fastcsv.util.Nullable;
+
 /// InputStreamReader that is capable of detecting and handling BOM headers.
 final class BomInputStreamReader extends Reader {
 
     private final InputStream inputStream;
     private final Charset defaultCharset;
+
+    @Nullable
     private Reader reader;
 
     BomInputStreamReader(final InputStream inputStream, final Charset defaultCharset) {
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/CsvCallbackHandler.java b/lib/src/main/java/de/siegmar/fastcsv/reader/CsvCallbackHandler.java
@@ -1,5 +1,7 @@
 package de.siegmar.fastcsv.reader;
 
+import de.siegmar.fastcsv.util.Nullable;
+
 /// This class defines the methods that are called during the CSV reading process.
 ///
 /// Implementations highly affect the behavior of the [CsvReader]. With great power comes great responsibility.
@@ -91,6 +93,7 @@ protected CsvCallbackHandler() {
     /// Called at the end of each CSV record to build the actual record representation.
     ///
     /// @return the record or `null` if the record should be ignored/skipped as it is consumed by the callback handler.
+    @Nullable
     protected abstract T buildRecord();
 
     /// Called at the end of the CSV reading process.
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/CsvParser.java b/lib/src/main/java/de/siegmar/fastcsv/reader/CsvParser.java
@@ -3,6 +3,8 @@
 import java.io.Closeable;
 import java.io.IOException;
 
+import de.siegmar.fastcsv.util.Nullable;
+
 sealed interface CsvParser extends Closeable permits StrictCsvParser, RelaxedCsvParser {
 
     /// Parses the next record from the stream and passes it to the callback handler.
@@ -11,6 +13,7 @@ sealed interface CsvParser extends Closeable permits StrictCsvParser, RelaxedCsv
     boolean parse() throws IOException;
 
     /// {@return the next line from the stream without consuming it.}
+    @Nullable
     String peekLine() throws IOException;
 
     /// Skips a line in the stream after skipping the specified number of characters.
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/CsvReader.java b/lib/src/main/java/de/siegmar/fastcsv/reader/CsvReader.java
@@ -19,6 +19,7 @@
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
+import de.siegmar.fastcsv.util.Nullable;
 import de.siegmar.fastcsv.util.Preconditions;
 
 /// This is the main class for reading CSV data.
@@ -210,6 +211,7 @@ public Stream<T> stream() {
             });
     }
 
+    @Nullable
     private T fetchRecord() throws IOException {
         while (csvParser.parse()) {
             final T csvRecord = processRecord();
@@ -224,6 +226,7 @@ private T fetchRecord() throws IOException {
         return null;
     }
 
+    @Nullable
     @SuppressWarnings("checkstyle:ReturnCount")
     private T processRecord() {
         final T csvRecord = callbackHandler.buildRecord();
@@ -275,6 +278,7 @@ public String toString() {
             .toString();
     }
 
+    @Nullable
     @SuppressWarnings({"checkstyle:IllegalCatch", "PMD.AvoidCatchingThrowable"})
     private T fetch() {
         try {
@@ -304,6 +308,7 @@ public boolean tryAdvance(final Consumer<? super T> action) {
             return false;
         }
 
+        @Nullable
         @Override
         public Spliterator<T> trySplit() {
             return null;
@@ -323,7 +328,9 @@ public int characteristics() {
 
     private class CsvRecordIterator implements CloseableIterator<T> {
 
+        @Nullable
         private T fetchedRecord;
+
         private boolean fetched;
 
         @Override
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/IndexedCsvReader.java b/lib/src/main/java/de/siegmar/fastcsv/reader/IndexedCsvReader.java
@@ -18,6 +18,7 @@
 import java.util.concurrent.locks.Lock;
 import java.util.concurrent.locks.ReentrantLock;
 
+import de.siegmar.fastcsv.util.Nullable;
 import de.siegmar.fastcsv.util.Preconditions;
 import de.siegmar.fastcsv.util.Util;
 
@@ -64,7 +65,8 @@ public final class IndexedCsvReader<T> implements Closeable {
                      final boolean allowExtraCharsAfterClosingQuote,
                      final int maxBufferSize,
                      final int pageSize,
-                     final CsvCallbackHandler<T> csvRecordHandler, final CsvIndex csvIndex,
+                     final CsvCallbackHandler<T> csvRecordHandler,
+                     @Nullable final CsvIndex csvIndex,
                      final StatusListener statusListener)
         throws IOException {
 
@@ -278,9 +280,15 @@ public static final class IndexedCsvReaderBuilder {
         private CommentStrategy commentStrategy = CommentStrategy.NONE;
         private char commentCharacter = '#';
         private boolean allowExtraCharsAfterClosingQuote;
+
+        @Nullable
         private StatusListener statusListener;
+
         private int pageSize = DEFAULT_PAGE_SIZE;
+
+        @Nullable
         private CsvIndex csvIndex;
+
         private int maxBufferSize = DEFAULT_MAX_BUFFER_SIZE;
 
         private IndexedCsvReaderBuilder() {
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/NamedCsvRecordHandler.java b/lib/src/main/java/de/siegmar/fastcsv/reader/NamedCsvRecordHandler.java
@@ -6,6 +6,8 @@
 import java.util.Objects;
 import java.util.function.Consumer;
 
+import de.siegmar.fastcsv.util.Nullable;
+
 /// A callback handler that returns a [NamedCsvRecord] for each record.
 ///
 /// Example:
@@ -21,11 +23,14 @@ public final class NamedCsvRecordHandler extends AbstractInternalCsvCallbackHand
 
     private static final String[] EMPTY_HEADER = new String[0];
     private final boolean allowDuplicateHeaderFields;
+
+    @Nullable
     private String[] header;
 
     private NamedCsvRecordHandler(final int maxFields, final int maxFieldSize, final int maxRecordSize,
                                   final FieldModifier fieldModifier,
-                                  final boolean allowDuplicateHeaderFields, final List<String> header) {
+                                  final boolean allowDuplicateHeaderFields,
+                                  @Nullable final List<String> header) {
         super(maxFields, maxFieldSize, maxRecordSize, fieldModifier);
         this.allowDuplicateHeaderFields = allowDuplicateHeaderFields;
         if (header != null) {
@@ -95,6 +100,7 @@ private static void checkForDuplicates(final String[] header) {
         }
     }
 
+    @Nullable
     @Override
     protected NamedCsvRecord buildRecord() {
         if (recordType == RecordType.COMMENT) {
@@ -115,6 +121,8 @@ public static final class NamedCsvRecordHandlerBuilder
         extends AbstractInternalCsvCallbackHandlerBuilder<NamedCsvRecordHandlerBuilder> {
 
         private boolean allowDuplicateHeaderFields;
+
+        @Nullable
         private List<String> header;
 
         private NamedCsvRecordHandlerBuilder() {
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/RelaxedCsvParser.java b/lib/src/main/java/de/siegmar/fastcsv/reader/RelaxedCsvParser.java
@@ -8,6 +8,7 @@
 import java.io.Reader;
 import java.io.StringReader;
 
+import de.siegmar.fastcsv.util.Nullable;
 import de.siegmar.fastcsv.util.Preconditions;
 import de.siegmar.fastcsv.util.Util;
 
@@ -26,7 +27,10 @@ final class RelaxedCsvParser implements CsvParser {
     private static final int DEFAULT_BUFFER_SIZE = 8192;
 
     private final char fsep;
+
+    @Nullable
     private final char[] fsepRemainder;
+
     private final char qChar;
     private final CommentStrategy cStrat;
     private final char cChar;
@@ -91,6 +95,7 @@ private void assertFields(final String fieldSeparator, final char quoteCharacter
             fieldSeparator.charAt(0), quoteCharacter, commentCharacter));
     }
 
+    @Nullable
     @SuppressWarnings({"PMD.AvoidLiteralsInIfCondition", "PMD.ReturnEmptyCollectionRatherThanNull"})
     private static char[] extractFsepRemainder(final String fsep) {
         if (fsep.length() <= 1) {
@@ -267,6 +272,7 @@ private void materializeField(final boolean quoted) {
         currentFieldIndex = 0;
     }
 
+    @Nullable
     @Override
     public String peekLine() throws IOException {
         return reader.peekLine();
@@ -355,6 +361,7 @@ boolean consumeIf(final char[] chars) throws IOException {
             return true;
         }
 
+        @Nullable
         String peekLine() throws IOException {
             ensureBuffered(buffer.length);
             if (start >= len) {
diff --git a/lib/src/main/java/de/siegmar/fastcsv/reader/StrictCsvParser.java b/lib/src/main/java/de/siegmar/fastcsv/reader/StrictCsvParser.java
@@ -7,6 +7,7 @@
 import java.io.IOException;
 import java.io.Reader;
 
+import de.siegmar.fastcsv.util.Nullable;
 import de.siegmar.fastcsv.util.Preconditions;
 import de.siegmar.fastcsv.util.Util;
 
@@ -341,6 +342,7 @@ public void close() throws IOException {
         csvBuffer.close();
     }
 
+    @Nullable
     @Override
     public String peekLine() throws IOException {
         if (csvBuffer.pos == csvBuffer.len && !csvBuffer.fetchData()) {
@@ -399,7 +401,9 @@ private static class CsvBuffer implements Closeable {
         int begin;
         int pos;
 
+        @Nullable
         private final Reader reader;
+
         private final int maxBufferSize;
         private final int readSize;
 
diff --git a/lib/src/main/java/de/siegmar/fastcsv/util/Nullable.java b/lib/src/main/java/de/siegmar/fastcsv/util/Nullable.java
@@ -0,0 +1,12 @@
+package de.siegmar.fastcsv.util;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Annotation to indicate that a method parameter, return value, or field can be null.
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
+public @interface Nullable {
+}
