feat: add java.sql.Clob converter

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/DefaultConverterLoader.java

@@ -45,6 +45,7 @@
 import org.apache.fesod.sheet.converters.byteconverter.ByteNumberConverter;
 import org.apache.fesod.sheet.converters.byteconverter.ByteStringConverter;
 import org.apache.fesod.sheet.converters.charconverter.CharacterStringConverter;
+import org.apache.fesod.sheet.converters.clob.ClobStringConverter;
 import org.apache.fesod.sheet.converters.date.DateDateConverter;
 import org.apache.fesod.sheet.converters.date.DateNumberConverter;
 import org.apache.fesod.sheet.converters.date.DateStringConverter;
@@ -120,6 +121,7 @@ private static void initAllConverter() {
         putAllConverter(new ByteStringConverter());
 
         putAllConverter(new CharacterStringConverter());
+        putAllConverter(new ClobStringConverter());
 
         putAllConverter(new DateNumberConverter());
         putAllConverter(new DateStringConverter());
@@ -186,6 +188,7 @@ private static void initDefaultWriteConverter() {
         putWriteConverter(new ShortNumberConverter());
         putWriteConverter(new StringStringConverter());
         putWriteConverter(new YearStringConverter());
+        putWriteConverter(new ClobStringConverter());
         putWriteConverter(new FileImageConverter());
         putWriteConverter(new InputStreamImageConverter());
         putWriteConverter(new ByteArrayImageConverter());
@@ -211,6 +214,7 @@ private static void initDefaultWriteConverter() {
         putWriteStringConverter(new ShortStringConverter());
         putWriteStringConverter(new StringStringConverter());
         putWriteStringConverter(new YearStringConverter());
+        putWriteStringConverter(new ClobStringConverter());
         defaultWriteConverter = Collections.unmodifiableMap(defaultWriteConverter);
     }
 

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/clob/ClobStringConverter.java

@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fesod.sheet.converters.clob;
+
+import java.io.Reader;
+import java.sql.Clob;
+import javax.sql.rowset.serial.SerialClob;
+import org.apache.fesod.sheet.converters.Converter;
+import org.apache.fesod.sheet.enums.CellDataTypeEnum;
+import org.apache.fesod.sheet.metadata.GlobalConfiguration;
+import org.apache.fesod.sheet.metadata.data.ReadCellData;
+import org.apache.fesod.sheet.metadata.data.WriteCellData;
+import org.apache.fesod.sheet.metadata.property.ExcelContentProperty;
+
+/**
+ * Clob and string converter. Clob data is represented as a string cell; reads return a
+ * {@link SerialClob} so callers receive a usable, detached JDBC Clob value.
+ */
+public class ClobStringConverter implements Converter<Clob> {
+    @Override
+    public Class<?> supportJavaTypeKey() {
+        return Clob.class;
+    }
+
+    @Override
+    public CellDataTypeEnum supportExcelTypeKey() {
+        return CellDataTypeEnum.STRING;
+    }
+
+    @Override
+    public Clob convertToJavaData(
+            ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)
+            throws Exception {
+        if (cellData.getStringValue() == null) {
+            return null;
+        }
+        // Materialize cell text into a detached JDBC Clob, avoiding a database-specific Clob implementation.
+        return new SerialClob(cellData.getStringValue().toCharArray());
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            Clob value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)
+            throws Exception {
+        StringBuilder text = new StringBuilder();
+        char[] buffer = new char[4096];
+        try (Reader reader = value.getCharacterStream()) {
+            int count;
+            while ((count = reader.read(buffer)) != -1) {
+                text.append(buffer, 0, count);
+            }
+        }
+        return new WriteCellData<>(text.toString());
+    }
+}

fesod-sheet/src/test/java/org/apache/fesod/sheet/converters/DefaultConverterLoaderTest.java

@@ -19,10 +19,12 @@
 
 package org.apache.fesod.sheet.converters;
 
+import java.sql.Clob;
 import java.sql.Time;
 import java.time.LocalTime;
 import java.util.Map;
 import org.apache.fesod.sheet.converters.ConverterKeyBuild.ConverterKey;
+import org.apache.fesod.sheet.converters.clob.ClobStringConverter;
 import org.apache.fesod.sheet.converters.localtime.LocalTimeDateConverter;
 import org.apache.fesod.sheet.converters.localtime.LocalTimeNumberConverter;
 import org.apache.fesod.sheet.converters.localtime.LocalTimeStringConverter;
@@ -88,6 +90,21 @@ void loadConvertersRegistersSqlTimeFamily() {
                 writeConverter.get(ConverterKeyBuild.buildKey(Time.class, CellDataTypeEnum.STRING)));
     }
 
+    @Test
+    void loadConvertersRegistersClobStringConverter() {
+        Map<ConverterKey, Converter<?>> allConverter = DefaultConverterLoader.loadAllConverter();
+        Assertions.assertInstanceOf(
+                ClobStringConverter.class,
+                allConverter.get(ConverterKeyBuild.buildKey(Clob.class, CellDataTypeEnum.STRING)));
+
+        Map<ConverterKey, Converter<?>> writeConverter = DefaultConverterLoader.loadDefaultWriteConverter();
+        Assertions.assertInstanceOf(
+                ClobStringConverter.class, writeConverter.get(ConverterKeyBuild.buildKey(Clob.class)));
+        Assertions.assertInstanceOf(
+                ClobStringConverter.class,
+                writeConverter.get(ConverterKeyBuild.buildKey(Clob.class, CellDataTypeEnum.STRING)));
+    }
+
     private static void assertLoadIsImmutableAndCopyIsMutable(
             Map<ConverterKey, Converter<?>> loaded, Map<ConverterKey, Converter<?>> copy) {
         Map.Entry<ConverterKey, Converter<?>> entry =

fesod-sheet/src/test/java/org/apache/fesod/sheet/converters/clob/ClobFieldRoundTripTest.java

@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fesod.sheet.converters.clob;
+
+import java.io.File;
+import java.sql.Clob;
+import java.util.ArrayList;
+import java.util.List;
+import javax.sql.rowset.serial.SerialClob;
+import lombok.Getter;
+import lombok.Setter;
+import org.apache.fesod.sheet.annotation.ExcelProperty;
+import org.apache.fesod.sheet.testkit.Tags;
+import org.apache.fesod.sheet.testkit.base.AbstractExcelTest;
+import org.apache.fesod.sheet.testkit.enums.ExcelFormat;
+import org.apache.fesod.sheet.testkit.helpers.RoundTripHelper;
+import org.apache.fesod.sheet.testkit.params.ExcelFormatSource;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.params.ParameterizedTest;
+
+/**
+ * Field-level round trips for Clob converter across every supported format.
+ */
+@Tag(Tags.ROUND_TRIP)
+public class ClobFieldRoundTripTest extends AbstractExcelTest {
+
+    @ParameterizedTest
+    @ExcelFormatSource
+    void clobFieldRoundTrip(ExcelFormat format) throws Exception {
+        File file = createTempFile(format);
+        List<ClobFieldData> data = new ArrayList<>();
+        ClobFieldData row = new ClobFieldData();
+        row.setClob(new SerialClob("Large text 字符".toCharArray()));
+        data.add(row);
+
+        List<ClobFieldData> result = RoundTripHelper.writeAndRead(file, ClobFieldData.class, data);
+
+        Assertions.assertEquals(1, result.size());
+        Clob actual = result.get(0).getClob();
+        Assertions.assertNotNull(actual);
+        Assertions.assertEquals("Large text 字符", actual.getSubString(1, (int) actual.length()));
+    }
+
+    @Getter
+    @Setter
+    public static class ClobFieldData {
+
+        @ExcelProperty("clob")
+        private Clob clob;
+    }
+}

fesod-sheet/src/test/java/org/apache/fesod/sheet/converters/clob/ClobStringConverterTest.java

@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fesod.sheet.converters.clob;
+
+import java.sql.Clob;
+import javax.sql.rowset.serial.SerialClob;
+import org.apache.fesod.sheet.enums.CellDataTypeEnum;
+import org.apache.fesod.sheet.metadata.GlobalConfiguration;
+import org.apache.fesod.sheet.metadata.data.ReadCellData;
+import org.apache.fesod.sheet.metadata.data.WriteCellData;
+import org.apache.fesod.sheet.testkit.Tags;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+@Tag(Tags.UNIT)
+class ClobStringConverterTest {
+    private static final GlobalConfiguration GLOBAL_CONFIGURATION = new GlobalConfiguration();
+    private final ClobStringConverter converter = new ClobStringConverter();
+
+    @Test
+    void supportKeys() {
+        Assertions.assertEquals(Clob.class, converter.supportJavaTypeKey());
+        Assertions.assertEquals(CellDataTypeEnum.STRING, converter.supportExcelTypeKey());
+    }
+
+    @Test
+    void convertsCellStringToDetachedClob() throws Exception {
+        Clob actual = converter.convertToJavaData(new ReadCellData<>("Large text 字符"), null, GLOBAL_CONFIGURATION);
+
+        Assertions.assertEquals("Large text 字符", actual.getSubString(1, (int) actual.length()));
+    }
+
+    @Test
+    void convertsClobCharacterStreamToCellString() throws Exception {
+        Clob value = new SerialClob("Large text 字符".toCharArray());
+
+        WriteCellData<?> written = converter.convertToExcelData(value, null, GLOBAL_CONFIGURATION);
+
+        Assertions.assertEquals(CellDataTypeEnum.STRING, written.getType());
+        Assertions.assertEquals("Large text 字符", written.getStringValue());
+    }
+
+    @Test
+    void convertsClobAtCellTextLimitToCellString() throws Exception {
+        StringBuilder expected = new StringBuilder();
+        for (int i = 0; i < 32767; i++) {
+            expected.append((char) ('a' + i % 26));
+        }
+        Clob value = new SerialClob(expected.toString().toCharArray());
+
+        WriteCellData<?> written = converter.convertToExcelData(value, null, GLOBAL_CONFIGURATION);
+
+        Assertions.assertEquals(expected.toString(), written.getStringValue());
+    }
+
+    @Test
+    void convertToJavaDataReturnsNullForNullString() throws Exception {
+        Clob actual = converter.convertToJavaData(new ReadCellData<>(), null, GLOBAL_CONFIGURATION);
+        Assertions.assertNull(actual);
+    }
+}