doc: Add JavaDoc for read cases (#301)

Author: tmlx1990

fastexcel-test/src/test/java/cn/idev/excel/test/demo/read/ConverterData.java

@@ -8,29 +8,29 @@
 import lombok.Setter;
 
 /**
- * 基础数据类.这里的排序和excel里面的排序一致
+ * Basic data class. The order here is consistent with the order in the Excel file.
  *
  * @author Jiaju Zhuang
  **/
 @Getter
 @Setter
 @EqualsAndHashCode
 public class ConverterData {
-    
+
     /**
-     * 我自定义 转换器，不管数据库传过来什么 。我给他加上“自定义：”
+     * I use a custom converter. No matter what is passed from the database, I prepend "Custom:".
      */
     @ExcelProperty(converter = CustomStringStringConverter.class)
     private String string;
-    
+
     /**
-     * 这里用string 去接日期才能格式化。我想接收年月日格式
+     * I use a string to receive the date so that it can be formatted. I want to receive the date in the format of yyyy-MM-dd HH:mm:ss.
      */
-    @DateTimeFormat("yyyy年MM月dd日HH时mm分ss秒")
+    @DateTimeFormat("yyyy-MM-dd HH:mm:ss")
     private String date;
-    
+
     /**
-     * 我想接收百分比的数字
+     * I want to receive a number in percentage format.
      */
     @NumberFormat("#.##%")
     private String doubleData;

fastexcel-test/src/test/java/cn/idev/excel/test/demo/read/ConverterDataListener.java

@@ -9,41 +9,42 @@
 import java.util.List;
 
 /**
- * 模板的读取类
+ * Template data reading class
  *
  * @author Jiaju Zhuang
  */
 @Slf4j
 public class ConverterDataListener implements ReadListener<ConverterData> {
-    
+
     /**
-     * 每隔5条存储数据库，实际使用中可以100条，然后清理list ，方便内存回收
+     * Save to the database every 5 records. In actual use, you might use 100 records,
+     * then clear the list to facilitate memory recycling.
      */
     private static final int BATCH_COUNT = 5;
-    
+
     private List<ConverterData> cachedDataList = ListUtils.newArrayListWithExpectedSize(BATCH_COUNT);
-    
+
     @Override
     public void invoke(ConverterData data, AnalysisContext context) {
-        log.info("解析到一条数据:{}", JSON.toJSONString(data));
+        log.info("Parsed a piece of data: {}", JSON.toJSONString(data));
         cachedDataList.add(data);
         if (cachedDataList.size() >= BATCH_COUNT) {
             saveData();
             cachedDataList = ListUtils.newArrayListWithExpectedSize(BATCH_COUNT);
         }
     }
-    
+
     @Override
     public void doAfterAllAnalysed(AnalysisContext context) {
         saveData();
-        log.info("所有数据解析完成！");
+        log.info("All data has been parsed and processed!");
     }
-    
+
     /**
-     * 加上存储数据库
+     * Simulate saving data to the database
      */
     private void saveData() {
-        log.info("{}条数据，开始存储数据库！", cachedDataList.size());
-        log.info("存储数据库成功！");
+        log.info("Saving {} records to the database!", cachedDataList.size());
+        log.info("Data saved to the database successfully!");
     }
 }

fastexcel-test/src/test/java/cn/idev/excel/test/demo/read/CustomStringStringConverter.java

@@ -12,36 +12,38 @@
  * @author Jiaju Zhuang
  */
 public class CustomStringStringConverter implements Converter<String> {
-    
+
     @Override
     public Class<?> supportJavaTypeKey() {
         return String.class;
     }
-    
+
     @Override
     public CellDataTypeEnum supportExcelTypeKey() {
         return CellDataTypeEnum.STRING;
     }
-    
+
     /**
-     * 这里读的时候会调用
+     * This method is called when reading data from Excel.
      *
-     * @param context
-     * @return
+     * @param context The context containing the cell data read from Excel.
+     * @return The converted Java data.
      */
     @Override
     public String convertToJavaData(ReadConverterContext<?> context) {
-        return "自定义：" + context.getReadCellData().getStringValue();
+        return "Custom：" + context.getReadCellData().getStringValue();
     }
-    
+
     /**
-     * 这里是写的时候会调用 不用管
+     * This method is called when writing data to Excel.
+     * (This is not relevant in this context and can be ignored.)
      *
-     * @return
+     * @param context The context containing the Java data to be written.
+     * @return The converted Excel data.
      */
     @Override
     public WriteCellData<?> convertToExcelData(WriteConverterContext<String> context) {
         return new WriteCellData<>(context.getValue());
     }
-    
+
 }

fastexcel-test/src/test/java/cn/idev/excel/test/demo/read/DemoExceptionListener.java

@@ -12,70 +12,70 @@
 import java.util.Map;
 
 /**
- * 读取转换异常
+ * Read and convert exceptions.
  *
  * @author Jiaju Zhuang
  */
 @Slf4j
 public class DemoExceptionListener implements ReadListener<ExceptionDemoData> {
-    
+
     /**
-     * 每隔5条存储数据库，实际使用中可以100条，然后清理list ，方便内存回收
+     * Save to the database every 5 records. In actual use, it can be set to 100 records, and then clear the list to facilitate memory recycling.
      */
     private static final int BATCH_COUNT = 5;
-    
+
     private List<ExceptionDemoData> cachedDataList = ListUtils.newArrayListWithExpectedSize(BATCH_COUNT);
-    
+
     /**
-     * 在转换异常 获取其他异常下会调用本接口。抛出异常则停止读取。如果这里不抛出异常则 继续读取下一行。
+     * This interface will be called in case of conversion exceptions or other exceptions. If an exception is thrown here, reading will be stopped. If no exception is thrown, the next line will continue to be read.
      *
-     * @param exception
-     * @param context
-     * @throws Exception
+     * @param exception The exception that occurred.
+     * @param context The analysis context.
+     * @throws Exception If an exception needs to be propagated.
      */
     @Override
     public void onException(Exception exception, AnalysisContext context) {
-        log.error("解析失败，但是继续解析下一行:{}", exception.getMessage());
-        // 如果是某一个单元格的转换异常 能获取到具体行号
-        // 如果要获取头的信息 配合invokeHeadMap使用
+        log.error("Parsing failed, but continue parsing the next line: {}", exception.getMessage());
+        // If it is a cell conversion exception, the specific row number can be obtained.
+        // If the header information is needed, use it in conjunction with invokeHeadMap.
         if (exception instanceof ExcelDataConvertException) {
             ExcelDataConvertException excelDataConvertException = (ExcelDataConvertException) exception;
-            log.error("第{}行，第{}列解析异常，数据为:{}", excelDataConvertException.getRowIndex(),
+            log.error("Parsing exception in row {}, column {}, data: {}", excelDataConvertException.getRowIndex(),
                     excelDataConvertException.getColumnIndex(), excelDataConvertException.getCellData());
         }
     }
-    
+
     /**
-     * 这里会一行行的返回头
+     * This method will return the header row line by line.
      *
-     * @param headMap
-     * @param context
+     * @param headMap The header map containing column index and cell data.
+     * @param context The analysis context.
      */
     @Override
     public void invokeHead(Map<Integer, ReadCellData<?>> headMap, AnalysisContext context) {
-        log.info("解析到一条头数据:{}", JSON.toJSONString(headMap));
+        log.info("Parsed a header row: {}", JSON.toJSONString(headMap));
     }
-    
+
     @Override
     public void invoke(ExceptionDemoData data, AnalysisContext context) {
-        log.info("解析到一条数据:{}", JSON.toJSONString(data));
+        log.info("Parsed a data row: {}", JSON.toJSONString(data));
         if (cachedDataList.size() >= BATCH_COUNT) {
             saveData();
             cachedDataList = ListUtils.newArrayListWithExpectedSize(BATCH_COUNT);
         }
     }
-    
+
     @Override
     public void doAfterAllAnalysed(AnalysisContext context) {
         saveData();
-        log.info("所有数据解析完成！");
+        log.info("All data parsing completed!");
     }
-    
+
     /**
-     * 加上存储数据库
+     * Save data to the database.
      */
     private void saveData() {
-        log.info("{}条数据，开始存储数据库！", cachedDataList.size());
-        log.info("存储数据库成功！");
+        log.info("{} records, starting to save to the database!", cachedDataList.size());
+        log.info("Data saved to the database successfully!");
     }
 }

fastexcel-test/src/test/java/cn/idev/excel/test/demo/read/DemoExtraListener.java

@@ -8,47 +8,47 @@
 import org.junit.jupiter.api.Assertions;
 
 /**
- * 读取单元格的批注
+ * Listener to read cell comments, hyperlinks, and merged cells.
  *
  * @author Jiaju Zhuang
  **/
 @Slf4j
 public class DemoExtraListener implements ReadListener<DemoExtraData> {
-    
+
     @Override
     public void invoke(DemoExtraData data, AnalysisContext context) {
     }
-    
+
     @Override
     public void doAfterAllAnalysed(AnalysisContext context) {
     }
-    
+
     @Override
     public void extra(CellExtra extra, AnalysisContext context) {
-        log.info("读取到了一条额外信息:{}", JSON.toJSONString(extra));
+        log.info("Read an extra piece of information: {}", JSON.toJSONString(extra));
         switch (extra.getType()) {
             case COMMENT:
-                log.info("额外信息是批注,在rowIndex:{},columnIndex;{},内容是:{}", extra.getRowIndex(),
+                log.info("The extra information is a comment, at rowIndex:{}, columnIndex:{}, content:{}", extra.getRowIndex(),
                         extra.getColumnIndex(), extra.getText());
                 break;
             case HYPERLINK:
                 if ("Sheet1!A1".equals(extra.getText())) {
-                    log.info("额外信息是超链接,在rowIndex:{},columnIndex;{},内容是:{}", extra.getRowIndex(),
+                    log.info("The extra information is a hyperlink, at rowIndex:{}, columnIndex:{}, content:{}", extra.getRowIndex(),
                             extra.getColumnIndex(), extra.getText());
                 } else if ("Sheet2!A1".equals(extra.getText())) {
-                    log.info(
-                            "额外信息是超链接,而且覆盖了一个区间,在firstRowIndex:{},firstColumnIndex;{},lastRowIndex:{},lastColumnIndex:{},"
-                                    + "内容是:{}", extra.getFirstRowIndex(), extra.getFirstColumnIndex(),
+                    log.info("The extra information is a hyperlink, covering a range, firstRowIndex:{}, firstColumnIndex:{}, " +
+                            "lastRowIndex:{}, lastColumnIndex:{}, content:{}",  extra.getFirstRowIndex(), extra.getFirstColumnIndex(),
                             extra.getLastRowIndex(), extra.getLastColumnIndex(), extra.getText());
                 } else {
                     Assertions.fail("Unknown hyperlink!");
                 }
                 break;
             case MERGE:
                 log.info(
-                        "额外信息是合并单元格,而且覆盖了一个区间,在firstRowIndex:{},firstColumnIndex;{},lastRowIndex:{},lastColumnIndex:{}",
-                        extra.getFirstRowIndex(), extra.getFirstColumnIndex(), extra.getLastRowIndex(),
-                        extra.getLastColumnIndex());
+                    "The extra information is a merged cell, covering a range, firstRowIndex:{}, firstColumnIndex:{}, " +
+                    "lastRowIndex:{}, lastColumnIndex:{}",
+                    extra.getFirstRowIndex(), extra.getFirstColumnIndex(),
+                    extra.getLastRowIndex(), extra.getLastColumnIndex());
                 break;
             default:
         }