Copilot commented on code in PR #882: URL: https://github.com/apache/fesod/pull/882#discussion_r2909204412
########## website/docs/sheet/advanced/large-file.md: ########## @@ -0,0 +1,82 @@ +--- +id: 'large-file' +title: 'Large File Writing' +--- + +<!-- +- 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. +--> + +# Large File Writing + +This chapter introduces how to write very large Excel files (100,000+ rows) with memory optimization. + +## Overview + +When exporting large datasets (e.g., database dumps, log analysis), loading all rows at once would exhaust memory. Fesod uses Apache POI's streaming API (SXSSF) internally, but temporary XML files can consume significant disk space. Enabling compression reduces disk usage at the cost of slightly more CPU. + +## Batch Writing with Compressed Temp Files + +### Code Example + +```java +@Test +public void largeFileWrite() { + String fileName = "largeFile" + System.currentTimeMillis() + ".xlsx"; + + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new WorkbookWriteHandler() { + @Override + public void afterWorkbookCreate(WorkbookWriteHandlerContext context) { + Workbook workbook = context.getWriteWorkbookHolder().getWorkbook(); + if (workbook instanceof SXSSFWorkbook) { + ((SXSSFWorkbook) workbook).setCompressTempFiles(true); + } + } + }) + .build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Template").build(); + // Write 100,000 rows in batches of 100 + for (int i = 0; i < 1000; i++) { + excelWriter.write(data(), writeSheet); + } Review Comment: The sample’s comments state “Write 100,000 rows in batches of 100”, but the code calls `excelWriter.write(data(), ...)` in a loop without showing that `data()` returns 100 rows. As written, the row counts in the comment aren’t verifiable/copy‑pastable; either include a `data()` implementation that returns the batch size you describe, or adjust the comments to avoid claiming specific row totals/batch sizes. ########## website/docs/sheet/read/format.md: ########## @@ -0,0 +1,100 @@ +--- +id: 'format' +title: 'Format' +--- + +<!-- +- 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. +--> + +# Formatting + +This chapter introduces data formatting when reading data. + +## Custom Format Reading + +### Overview + +When reading Excel files, date and number cells can be automatically converted to formatted `String` values using annotations. This is useful when you want to control the exact text representation of dates and numbers. + +### POJO Class + +```java +@Getter +@Setter +@EqualsAndHashCode +public class ConverterData { + @ExcelProperty(value = "String Title", converter = CustomStringStringConverter.class) + private String string; + + @DateTimeFormat("yyyy-MM-dd HH:mm:ss") + @ExcelProperty("Date Title") + private String date; + + @NumberFormat("#.##%") + @ExcelProperty("Number Title") + private String doubleData; +} +``` + +### Conversion Behavior + +| Excel Cell Value | Annotation | Java Field Value | +|:---|:---|:---| +| `Hello` | `@ExcelProperty(converter = CustomStringStringConverter.class)` | `"Custom：Hello"` | Review Comment: In the conversion table, the example output uses a fullwidth colon (`"Custom：Hello"`). This is inconsistent with the converter examples (which use `Custom:`) and reads like a typo; please change it to a normal ASCII colon (`"Custom: Hello"`). ```suggestion | `Hello` | `@ExcelProperty(converter = CustomStringStringConverter.class)` | `"Custom: Hello"` | ``` ########## website/docs/sheet/advanced/password.md: ########## @@ -0,0 +1,72 @@ +--- +id: 'password' +title: 'Password Protection' +--- + +<!-- +- 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. +--> + +# Password Protection + +This chapter introduces how to read and write password-protected Excel files. + +## Overview + +Fesod supports Excel's built-in password encryption for both reading and writing. Use `.password("xxx")` on the builder to encrypt output files or decrypt input files. The encryption uses Excel's native AES encryption for `.xlsx` files, compatible with all Excel versions. Review Comment: The overview currently claims password protection uses AES and is "compatible with all Excel versions", but Fesod’s writer-side `.password(...)` has important caveats (it’s implemented via POI encryption for XLSX and is documented in code as memory-intensive, and XLS behaves differently). Please adjust this section to avoid over-claiming compatibility and document the memory/format limitations (e.g., XLSX encryption + high memory usage; XLS is write-protect behavior). ```suggestion Fesod supports Excel's built-in password protection for both reading and writing. Use `.password("xxx")` on the builder to encrypt/decrypt files. For `.xlsx` output, Fesod uses Apache POI's encryption (AES-based) which can be memory‑intensive for large workbooks. For legacy `.xls` files, password protection behaves as write‑protection rather than full content encryption, so behavior and security guarantees differ from `.xlsx`. ``` ########## website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md: ########## @@ -0,0 +1,55 @@ +--- +id: 'password' +title: '密码保护' +--- + +# 密码保护 + +本章节介绍如何读取和写入受密码保护的 Excel 文件。 + +## 概述 + +Fesod 支持 Excel 内置的密码加密功能，适用于读取和写入操作。在构建器上使用 `.password("xxx")` 即可加密输出文件或解密输入文件。加密使用 Excel 原生的 AES 加密方式（适用于 `.xlsx` 文件），兼容所有 Excel 版本。 + +## 带密码写入 Review Comment: 中文文档的概述段落同样写到“Excel 原生 AES 加密方式…兼容所有 Excel 版本”，且未提示 `.password(...)` 写入端加密会非常耗内存/并且不同格式（XLS/XLSX）行为不同。建议在这里补充格式限制与内存开销说明，并避免“兼容所有版本”的绝对表述。 ########## website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/large-file.md: ########## @@ -0,0 +1,65 @@ +--- +id: 'large-file' +title: '大文件写入' +--- + +# 大文件写入 + +本章节介绍如何通过内存优化写入超大 Excel 文件（10 万行以上）。 + +## 概述 + +导出大型数据集（如数据库转储、日志分析）时，一次性加载所有行会耗尽内存。Fesod 内部使用 Apache POI 的流式 API（SXSSF），但临时 XML 文件可能会占用大量磁盘空间。启用压缩可以减少磁盘占用，但会略微增加 CPU 消耗。 + +## 批量写入与压缩临时文件 + +### 代码示例 + +```java +@Test +public void largeFileWrite() { + String fileName = "largeFile" + System.currentTimeMillis() + ".xlsx"; + + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new WorkbookWriteHandler() { + @Override + public void afterWorkbookCreate(WorkbookWriteHandlerContext context) { + Workbook workbook = context.getWriteWorkbookHolder().getWorkbook(); + if (workbook instanceof SXSSFWorkbook) { + ((SXSSFWorkbook) workbook).setCompressTempFiles(true); + } + } + }) + .build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("模板").build(); + // 分批写入 100,000 行，每批 100 行 + for (int i = 0; i < 1000; i++) { + excelWriter.write(data(), writeSheet); + } Review Comment: 代码注释写到“分批写入 100,000 行，每批 100 行”，但示例里循环调用 `excelWriter.write(data(), ...)`，并未给出 `data()` 每批返回 100 行的实现（对读者来说无法验证/直接复制）。建议补充 `data()` 的批次数据构造（明确 100 行），或把注释改为不依赖具体行数的描述。 ########## website/docs/sheet/write/merge.md: ########## @@ -0,0 +1,147 @@ +--- +id: 'merge' +title: 'Merge' +--- + +<!-- +- 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. +--> + +# Cell Merging + +This chapter introduces cell merging strategies when writing Excel files. + +## Overview + +When generating Excel reports, you may need to merge cells — for example, merging repeated category names in a column, or creating summary rows. Fesod supports two approaches: annotation-based and strategy-based merging. + +## Annotation-Based Merging + +### Overview + +Annotate a field with `@ContentLoopMerge(eachRow = N)` to automatically merge every N rows in that column. + +### POJO Class + +```java +@Getter +@Setter +@EqualsAndHashCode +public class DemoMergeData { + @ContentLoopMerge(eachRow = 2) + @ExcelProperty("String Title") + private String string; + + @ExcelProperty("Date Title") + private Date date; + + @ExcelProperty("Number Title") + private Double doubleData; +} +``` + +### Code Example + +```java +@Test +public void annotationMergeWrite() { + String fileName = "annotationMergeWrite" + System.currentTimeMillis() + ".xlsx"; + FesodSheet.write(fileName, DemoMergeData.class) + .sheet() + .doWrite(data()); +} +``` + +### Result + +``` +| String Title | Date Title | Number Title | +|--------------|---------------------|--------------| +| String0 | 2025-01-01 00:00:00 | 0.56 | +| (merged) | 2025-01-01 00:00:00 | 0.56 | +| String1 | 2025-01-01 00:00:00 | 0.56 | +| (merged) | 2025-01-01 00:00:00 | 0.56 | +``` + +--- + +## Strategy-Based Merging + +### Overview + +Register a `LoopMergeStrategy(eachRow, columnIndex)` as a write handler. More flexible — can be configured at runtime and applied to any column. + +### Code Example + +```java +@Test +public void strategyMergeWrite() { + String fileName = "strategyMergeWrite" + System.currentTimeMillis() + ".xlsx"; + + // Merge every 2 rows in column 0 + LoopMergeStrategy strategy = new LoopMergeStrategy(2, 0); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(strategy) + .sheet() + .doWrite(data()); +} +``` + +--- + +## Custom Merge Strategy + +### Overview + +For complex merging logic (e.g., merge based on data content), implement the `AbstractMergeStrategy` class. + +### Code Example + +```java +public class CustomMergeStrategy extends AbstractMergeStrategy { + @Override + protected void merge(Sheet sheet, Cell cell, Head head, Integer relativeRowIndex) { + if (relativeRowIndex != null && relativeRowIndex % 2 == 0 && head.getColumnIndex() == 0) { + int startRow = relativeRowIndex + 1; + int endRow = startRow + 1; + sheet.addMergedRegion(new CellRangeAddress(startRow, endRow, 0, 0)); + } Review Comment: In `CustomMergeStrategy`, computing `startRow` as `relativeRowIndex + 1` implicitly assumes exactly one header row. Since `relativeRowIndex` is already “data-row relative” (and header rows are skipped), this example can produce wrong row indexes when `headRowNumber` is not 1 (multi-row headers) or when writing starts at an offset. Consider using `cell.getRowIndex()` (actual sheet row) or documenting/deriving the header-row offset explicitly to make the sample copy/paste safe. ########## website/docs/sheet/write/converter.md: ########## @@ -0,0 +1,124 @@ +--- +id: 'converter' +title: 'Converter' +--- + +<!-- +- 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. +--> + +# Converter + +This chapter introduces how to use custom converters when writing data. + +## Overview + +Fesod supports custom data converters for write operations. You can transform Java field values before they are written to Excel cells, enabling custom formatting, encryption, or any data transformation logic. + +## Per-Field Converter + +### Overview + +Apply a converter to a specific field using the `@ExcelProperty(converter = ...)` annotation. + +### Converter + +```java +public class CustomStringStringConverter implements Converter<String> { + @Override + public Class<?> supportJavaTypeKey() { + return String.class; + } + + @Override + public CellDataTypeEnum supportExcelTypeKey() { + return CellDataTypeEnum.STRING; + } + + @Override + public String convertToJavaData(ReadConverterContext<?> context) { + return "Custom: " + context.getReadCellData().getStringValue(); + } + + @Override + public WriteCellData<?> convertToExcelData(WriteConverterContext<String> context) { + return new WriteCellData<>("Custom: " + context.getValue()); + } +} +``` + +### POJO Class + +```java +@Getter +@Setter +@EqualsAndHashCode +public class ConverterData { + @ExcelProperty(value = "String Title", converter = CustomStringStringConverter.class) + private String string; + + @DateTimeFormat("yyyy年MM月dd日HH时mm分ss秒") + @ExcelProperty("Date Title") + private Date date; Review Comment: This English doc uses a Chinese-locale date pattern (`yyyy年MM月dd日HH时mm分ss秒`) in `@DateTimeFormat`. That’s likely confusing for the English docs; consider switching to a locale-neutral pattern like `yyyy-MM-dd HH:mm:ss` (or explicitly note that the pattern is arbitrary) so readers can copy/paste safely. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
