refactor!: remove the RecordWrapper

Author: osiegmar

docs/src/content/docs/guides/upgrading.md

@@ -57,3 +57,11 @@ The `CsvIndex` and `CsvPage` classes have been changed to Java records. With thi
 - firstPage.getStartingLineNumber();
 + firstPage.startingLineNumber();
 ```
+
+## Record wrapper removal
+
+The `RecordWrapper` class has been removed. It was a wrapper around the `CsvRecord` class that was used to provide parsing context information to the reading process.
+
+If you implemented a custom callback handler by extending `AbstractBaseCsvCallbackHandler`, all you need to do is to return the `CsvRecord` instance directly instead of wrapping it in a `RecordWrapper`.
+
+If you implemented a custom callback handler by implementing the `CsvCallbackHandler` interface, you also have to implement three additional methods: `isComment`, `isEmptyLine` and `getFieldCount`. Those methods simply have to return the information that was previously provided by the `RecordWrapper` instance.

example/src/main/java/example/ExampleCsvReaderWithCustomCallbackHandler.java

@@ -15,7 +15,6 @@
 import de.siegmar.fastcsv.reader.AbstractBaseCsvCallbackHandler;
 import de.siegmar.fastcsv.reader.CsvReader;
 import de.siegmar.fastcsv.reader.NamedCsvRecord;
-import de.siegmar.fastcsv.reader.RecordWrapper;
 import de.siegmar.fastcsv.writer.CsvWriter;
 
 /// Example for implementing a custom callback handler.
@@ -202,7 +201,7 @@ private long materializeId(final char[] buf, final int offset, final int len) {
         }
 
         @Override
-        protected RecordWrapper<Measurement> buildRecord() {
+        protected Measurement buildRecord() {
             if (recordCount++ == 0) {
                 // Skip header
                 return null;
@@ -213,7 +212,7 @@ protected RecordWrapper<Measurement> buildRecord() {
                     .formatted(getFieldCount(), getStartingLineNumber()));
             }
 
-            return wrapRecord(new Measurement(id, timestamp, latitude, longitude, temperature));
+            return new Measurement(id, timestamp, latitude, longitude, temperature);
         }
 
     }

example/src/main/java/example/ExampleCsvReaderWithSpecialQuotedFieldHandling.java

@@ -5,7 +5,6 @@
 
 import de.siegmar.fastcsv.reader.AbstractBaseCsvCallbackHandler;
 import de.siegmar.fastcsv.reader.CsvReader;
-import de.siegmar.fastcsv.reader.RecordWrapper;
 
 /// Example for reading CSV data with custom handling of quoted fields.
 public class ExampleCsvReaderWithSpecialQuotedFieldHandling {
@@ -39,8 +38,8 @@ protected void handleBegin(final long startingLineNumber) {
         }
 
         @Override
-        protected RecordWrapper<List<QuotableField>> buildRecord() {
-            return wrapRecord(List.copyOf(fields));
+        protected List<QuotableField> buildRecord() {
+            return List.copyOf(fields);
         }
 
     }

lib/src/intTest/java/blackbox/reader/SkipRecordsTest.java

@@ -13,7 +13,6 @@
 import de.siegmar.fastcsv.reader.CsvReader;
 import de.siegmar.fastcsv.reader.CsvRecordHandler;
 import de.siegmar.fastcsv.reader.FieldModifiers;
-import de.siegmar.fastcsv.reader.RecordWrapper;
 import testutil.CsvRecordAssert;
 
 class SkipRecordsTest {
@@ -64,8 +63,8 @@ protected void handleField(final int fieldIdx, final char[] buf,
             }
 
             @Override
-            protected RecordWrapper<String[]> buildRecord() {
-                return wrapRecord(fields.toArray(new String[0]));
+            protected String[] buildRecord() {
+                return fields.toArray(new String[0]);
             }
         };
         assertThat(crb.build(cbh, input).stream()).hasSize(2);

lib/src/main/java/de/siegmar/fastcsv/reader/AbstractBaseCsvCallbackHandler.java

@@ -1,7 +1,5 @@
 package de.siegmar.fastcsv.reader;
 
-import java.util.Objects;
-
 /// Base class for [CsvCallbackHandler] implementations that handles their own field storage and record building.
 ///
 /// This implementation is stateful and must not be reused.
@@ -28,16 +26,19 @@ protected long getStartingLineNumber() {
     }
 
     /// {@return whether the current record is a comment.}
+    @Override
     protected boolean isComment() {
         return comment;
     }
 
     /// {@return whether the current record is an empty line.}
+    @Override
     protected boolean isEmptyLine() {
         return emptyLine;
     }
 
     /// {@return the number of fields in the current record.}
+    @Override
     protected int getFieldCount() {
         return fieldCount;
     }
@@ -112,15 +113,4 @@ protected final void setComment(final char[] buf, final int offset, final int le
     protected void handleComment(final char[] buf, final int offset, final int len) {
     }
 
-    /// Builds a wrapper for the record that contains information necessary for the [CsvReader] in order to
-    /// determine how to process the record.
-    ///
-    /// @param record the actual record to be returned by the [CsvReader], must not be `null`
-    /// @return the wrapper for the actual record
-    /// @throws NullPointerException if `null` is passed for `record`
-    protected RecordWrapper<T> wrapRecord(final T record) {
-        return new RecordWrapper<>(comment, emptyLine, fieldCount,
-            Objects.requireNonNull(record, "record must not be null"));
-    }
-
 }

lib/src/main/java/de/siegmar/fastcsv/reader/AbstractInternalCsvCallbackHandler.java

@@ -92,6 +92,21 @@ protected AbstractInternalCsvCallbackHandler(final int maxFields,
         fields = new String[Math.min(DEFAULT_INITIAL_FIELDS_SIZE, maxFields)];
     }
 
+    @Override
+    protected boolean isComment() {
+        return comment;
+    }
+
+    @Override
+    protected boolean isEmptyLine() {
+        return emptyLine;
+    }
+
+    @Override
+    protected int getFieldCount() {
+        return fieldIdx;
+    }
+
     /// {@inheritDoc}
     /// Resets the internal state of this handler.
     @SuppressWarnings("checkstyle:HiddenField")
@@ -204,15 +219,6 @@ protected String[] compactFields() {
         return ret;
     }
 
-    /// Builds a record wrapper for the given record.
-    ///
-    /// @param rec the record, must not be `null`
-    /// @return the record wrapper
-    /// @throws NullPointerException if `rec` is `null`
-    protected RecordWrapper<T> buildWrapper(final T rec) {
-        return new RecordWrapper<>(comment, emptyLine, fieldIdx, rec);
-    }
-
     /// Abstract builder for [AbstractInternalCsvCallbackHandler] subclasses.
     ///
     /// This class is for **internal use only** and should not be used directly. It will be sealed in a future release.

lib/src/main/java/de/siegmar/fastcsv/reader/CsvCallbackHandler.java

@@ -16,6 +16,29 @@ public abstract class CsvCallbackHandler<T> {
     protected CsvCallbackHandler() {
     }
 
+    /// {@return whether the record denotes a comment}
+    ///
+    /// If this method returns `true`, the record is a comment and cannot be a regular record.
+    /// The [CsvReader] will skip the record if
+    /// [de.siegmar.fastcsv.reader.CsvReader.CsvReaderBuilder#commentStrategy(CommentStrategy)]
+    /// is set to [CommentStrategy#SKIP].
+    protected abstract boolean isComment();
+
+    /// {@return whether the line is empty}
+    ///
+    /// If this method returns `true`, the line is empty.
+    /// The [CsvReader] will skip the record if
+    /// [de.siegmar.fastcsv.reader.CsvReader.CsvReaderBuilder#skipEmptyLines(boolean)]
+    /// is set to `true`.
+    protected abstract boolean isEmptyLine();
+
+    /// {@return the number of fields in the record}
+    ///
+    /// The [CsvReader] will check the number of fields in the record against the number of fields in other records if
+    /// [de.siegmar.fastcsv.reader.CsvReader.CsvReaderBuilder#ignoreDifferentFieldCount(boolean)]
+    /// is set to `false`.
+    protected abstract int getFieldCount();
+
     /// Called at the beginning of each record.
     ///
     /// The `startingLineNumber` is the line number where the record starts (starting with 1).
@@ -64,12 +87,10 @@ protected CsvCallbackHandler() {
     /// @param len    the length of the field value
     protected abstract void setComment(char[] buf, int offset, int len);
 
-    /// Called at the end of each CSV record to build an object representation of the record.
-    ///
-    /// The returned wrapper is used by the [CsvReader] in order to determine how to process the record.
+    /// Called at the end of each CSV record to build the actual record representation.
     ///
-    /// @return the record wrapper or `null` if the record should be ignored/skipped
-    protected abstract RecordWrapper<T> buildRecord();
+    /// @return the record or `null` if the record should be ignored/skipped as it is consumed by the callback handler.
+    protected abstract T buildRecord();
 
     /// Called at the end of the CSV reading process.
     protected void terminate() {

lib/src/main/java/de/siegmar/fastcsv/reader/CsvReader.java

@@ -223,29 +223,29 @@ private T fetchRecord() throws IOException {
 
     @SuppressWarnings("checkstyle:ReturnCount")
     private T processRecord() {
-        final RecordWrapper<T> recordWrapper = callbackHandler.buildRecord();
+        final T csvRecord = callbackHandler.buildRecord();
 
         // handle consumed records (e.g., header for named records)
-        if (recordWrapper == null) {
+        if (csvRecord == null) {
             return null;
         }
 
         // handle comment lines
-        if (recordWrapper.isComment()) {
-            return commentStrategy == CommentStrategy.SKIP ? null : recordWrapper.getWrappedRecord();
+        if (callbackHandler.isComment()) {
+            return commentStrategy == CommentStrategy.SKIP ? null : csvRecord;
         }
 
         // handle empty lines
-        if (recordWrapper.isEmptyLine()) {
-            return skipEmptyLines ? null : recordWrapper.getWrappedRecord();
+        if (callbackHandler.isEmptyLine()) {
+            return skipEmptyLines ? null : csvRecord;
         }
 
         // check field count consistency
         if (!ignoreDifferentFieldCount) {
-            checkFieldCountConsistency(recordWrapper.getFieldCount());
+            checkFieldCountConsistency(callbackHandler.getFieldCount());
         }
 
-        return recordWrapper.getWrappedRecord();
+        return csvRecord;
     }
 
     private void checkFieldCountConsistency(final int fieldCount) {

lib/src/main/java/de/siegmar/fastcsv/reader/CsvRecordHandler.java

@@ -73,8 +73,8 @@ public static CsvRecordHandler of(final Consumer<CsvRecordHandlerBuilder> config
     }
 
     @Override
-    protected RecordWrapper<CsvRecord> buildRecord() {
-        return buildWrapper(new CsvRecord(startingLineNumber, compactFields(), comment));
+    protected CsvRecord buildRecord() {
+        return new CsvRecord(startingLineNumber, compactFields(), comment);
     }
 
     /// A builder for [CsvRecordHandler].

lib/src/main/java/de/siegmar/fastcsv/reader/IndexedCsvReader.java

@@ -213,9 +213,9 @@ private List<T> readPage(final CsvIndex.CsvPage page) throws IOException {
             csvParser.reset(page.startingLineNumber() - 1);
 
             for (int i = 0; i < pageSize && csvParser.parse(); i++) {
-                final RecordWrapper<T> rec = csvRecordHandler.buildRecord();
+                final T rec = csvRecordHandler.buildRecord();
                 if (rec != null) {
-                    ret.add(rec.getWrappedRecord());
+                    ret.add(rec);
                 }
             }
         } catch (final IOException e) {