feature: support multi-rows loop filling and merge strategies

fesod-sheet/src/main/java/org/apache/fesod/sheet/enums/FillMergeStrategy.java

@@ -0,0 +1,44 @@
+/*
+ * 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.enums;
+
+/**
+ * Strategy for handling merged regions during loop filling.
+ */
+public enum FillMergeStrategy {
+
+    /**
+     * Merged regions in the fill template will NOT be handled.
+     */
+    NONE,
+
+    /**
+     * Automatically handling merged regions based on the fill template.
+     */
+    AUTO,
+
+    /**
+     * Automatically handling merged regions and unifying the style using anchor cells based on the fill template.
+     * <p />
+     * <b>Warning: Too many CellStyle instances may lead to performance issues and can exceed number of cell styles
+     * limits (64000 for .xlsx and 4000 for .xls).</b>
+     */
+    MERGE_CELL_STYLE
+}

fesod-sheet/src/main/java/org/apache/fesod/sheet/write/executor/ExcelWriteFillExecutor.java

@@ -21,8 +21,10 @@
 
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
+import java.util.IntSummaryStatistics;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
@@ -39,6 +41,7 @@
 import org.apache.fesod.common.util.StringUtils;
 import org.apache.fesod.sheet.context.WriteContext;
 import org.apache.fesod.sheet.enums.CellDataTypeEnum;
+import org.apache.fesod.sheet.enums.FillMergeStrategy;
 import org.apache.fesod.sheet.enums.WriteDirectionEnum;
 import org.apache.fesod.sheet.enums.WriteTemplateAnalysisCellTypeEnum;
 import org.apache.fesod.sheet.exception.ExcelGenerateException;
@@ -60,6 +63,7 @@
 import org.apache.poi.ss.usermodel.CellType;
 import org.apache.poi.ss.usermodel.Row;
 import org.apache.poi.ss.usermodel.Sheet;
+import org.apache.poi.ss.util.CellRangeAddress;
 
 /**
  * Fill the data into excel
@@ -137,18 +141,124 @@ public void fill(Object data, FillConfig fillConfig) {
                 return;
             }
             Iterator<?> iterator = collectionData.iterator();
+            int rowSpan = calculateRowSpan(analysisCellList);
             if (WriteDirectionEnum.VERTICAL.equals(fillConfig.getDirection()) && fillConfig.getForceNewRow()) {
-                shiftRows(collectionData.size(), analysisCellList);
+                shiftRows(collectionData.size(), rowSpan, analysisCellList);
             }
             while (iterator.hasNext()) {
-                doFill(analysisCellList, iterator.next(), fillConfig, getRelativeRowIndex());
+                doFill(analysisCellList, iterator.next(), fillConfig, getRelativeRowIndex(), rowSpan);
             }
         } else {
-            doFill(readTemplateData(templateAnalysisCache), realData, fillConfig, null);
+            doFill(readTemplateData(templateAnalysisCache), realData, fillConfig, null, 0);
         }
     }
 
-    private void shiftRows(int size, List<AnalysisCell> analysisCellList) {
+    private void addMergedRegionIfNecessary(List<AnalysisCell> analysisCellList, FillConfig fillConfig) {
+        FillMergeStrategy mergeStrategy = fillConfig.getMergeStrategy();
+        if (FillMergeStrategy.NONE.equals(mergeStrategy)) {
+            return;
+        }
+
+        Set<CellRangeAddress> dataRowMergeRegions = determineMergedRegionsForRow(analysisCellList, fillConfig);
+        if (CollectionUtils.isEmpty(dataRowMergeRegions)) {
+            return;
+        }
+
+        Sheet sheet = writeContext.writeSheetHolder().getSheet();
+
+        // Unify the style using anchor cells
+        if (FillMergeStrategy.MERGE_CELL_STYLE.equals(mergeStrategy)) {
+            Sheet cachedSheet = writeContext.writeSheetHolder().getCachedSheet();
+            Map<CellCoordinate, Set<CellCoordinate>> cellCoordinateMap = indexMergedRegionsMap(dataRowMergeRegions);
+
+            for (Map.Entry<CellCoordinate, Set<CellCoordinate>> entry : cellCoordinateMap.entrySet()) {
+                CellCoordinate anchor = entry.getKey();
+                CellStyle anchorStyle =
+                        anchor.getOrCreateCell(sheet, cachedSheet).getCellStyle();
+
+                for (CellCoordinate mergedCell : entry.getValue()) {
+                    Cell cell = mergedCell.getOrCreateCell(sheet, cachedSheet);
+                    cell.setCellStyle(anchorStyle);
+                }
+            }
+        }
+
+        // Merge cells
+        for (CellRangeAddress range : dataRowMergeRegions) {
+            sheet.addMergedRegionUnsafe(range.copy());
+        }
+    }
+
+    private Set<CellRangeAddress> determineMergedRegionsForRow(List<AnalysisCell> cells, FillConfig fillConfig) {
+        if (CollectionUtils.isEmpty(cells)
+                || !WriteDirectionEnum.VERTICAL.equals(fillConfig.getDirection())
+                || FillMergeStrategy.NONE.equals(fillConfig.getMergeStrategy())) {
+            return Collections.emptySet();
+        }
+
+        Sheet sheet = writeContext.writeSheetHolder().getSheet();
+        if (sheet.getNumMergedRegions() == 0) {
+            return Collections.emptySet();
+        }
+
+        Set<CellRangeAddress> absoluteRegions = new HashSet<>();
+        Map<AnalysisCell, Integer> collectionLastIndexMap = collectionLastIndexCache.get(currentUniqueDataFlag);
+        if (collectionLastIndexMap == null || collectionLastIndexMap.isEmpty()) {
+            return Collections.emptySet();
+        }
+
+        for (AnalysisCell cell : cells) {
+            Integer firstRow = collectionLastIndexMap.get(cell);
+            if (firstRow == null) {
+                // No recorded last index for this cell; skip to avoid NPE.
+                continue;
+            }
+
+            for (CellRangeAddress range : sheet.getMergedRegions()) {
+                if (range.isInRange(cell.getRowIndex(), cell.getColumnIndex())) {
+                    int lastRow = firstRow + (range.getLastRow() - range.getFirstRow());
+                    absoluteRegions.add(
+                            new CellRangeAddress(firstRow, lastRow, range.getFirstColumn(), range.getLastColumn()));
+                }
+            }
+        }
+        return Collections.unmodifiableSet(absoluteRegions);
+    }
+
+    private Map<CellCoordinate, Set<CellCoordinate>> indexMergedRegionsMap(Set<CellRangeAddress> mergedRegions) {
+        Map<CellCoordinate, Set<CellCoordinate>> result = new HashMap<>();
+        for (CellRangeAddress range : mergedRegions) {
+            int firstRow = range.getFirstRow();
+            int firstCol = range.getFirstColumn();
+
+            // Anchor cell -> In merged cells
+            Set<CellCoordinate> cells =
+                    result.computeIfAbsent(new CellCoordinate(firstRow, firstCol), key -> new HashSet<>());
+
+            for (int row = range.getFirstRow(); row <= range.getLastRow(); row++) {
+                for (int col = firstCol; col <= range.getLastColumn(); col++) {
+                    // Skip anchor cell
+                    if (row == firstRow && col == firstCol) {
+                        continue;
+                    }
+                    cells.add(new CellCoordinate(row, col));
+                }
+            }
+        }
+
+        return result;
+    }
+
+    private int calculateRowSpan(List<AnalysisCell> analysisCellList) {
+        if (CollectionUtils.isEmpty(analysisCellList)) {
+            return 0;
+        }
+        IntSummaryStatistics stats =
+                analysisCellList.stream().mapToInt(AnalysisCell::getRowIndex).summaryStatistics();
+        return stats.getMax() - stats.getMin() + 1;
+    }
+
+    private void shiftRows(int size, int rowSpan, List<AnalysisCell> analysisCellList) {
         if (CollectionUtils.isEmpty(analysisCellList)) {
             return;
         }
@@ -174,9 +284,9 @@ private void shiftRows(int size, List<AnalysisCell> analysisCellList) {
             return;
         }
         Sheet sheet = writeContext.writeSheetHolder().getCachedSheet();
-        int number = size;
+        int number = size * rowSpan;
         if (collectionLastIndexMap == null) {
-            number--;
+            number -= rowSpan;
         }
         if (number <= 0) {
             return;
@@ -205,7 +315,11 @@ private void increaseRowIndex(
     }
 
     private void doFill(
-            List<AnalysisCell> analysisCellList, Object oneRowData, FillConfig fillConfig, Integer relativeRowIndex) {
+            List<AnalysisCell> analysisCellList,
+            Object oneRowData,
+            FillConfig fillConfig,
+            Integer relativeRowIndex,
+            Integer rowSpan) {
         if (CollectionUtils.isEmpty(analysisCellList) || oneRowData == null) {
             return;
         }
@@ -247,7 +361,7 @@ private void doFill(
                         writeContext.currentWriteHolder());
                 cellWriteHandlerContext.setExcelContentProperty(excelContentProperty);
 
-                createCell(analysisCell, fillConfig, cellWriteHandlerContext, rowWriteHandlerContext);
+                createCell(analysisCell, fillConfig, cellWriteHandlerContext, rowWriteHandlerContext, rowSpan);
                 cellWriteHandlerContext.setOriginalValue(value);
                 cellWriteHandlerContext.setOriginalFieldClass(FieldUtils.getFieldClass(dataMap, variable, value));
 
@@ -268,7 +382,7 @@ private void doFill(
                 cellWriteHandlerContext.setExcelContentProperty(ExcelContentProperty.EMPTY);
                 cellWriteHandlerContext.setIgnoreFillStyle(Boolean.TRUE);
 
-                createCell(analysisCell, fillConfig, cellWriteHandlerContext, rowWriteHandlerContext);
+                createCell(analysisCell, fillConfig, cellWriteHandlerContext, rowWriteHandlerContext, rowSpan);
                 Cell cell = cellWriteHandlerContext.getCell();
 
                 for (String variable : analysisCell.getVariableList()) {
@@ -327,6 +441,9 @@ private void doFill(
             WriteHandlerUtils.afterCellDispose(cellWriteHandlerContext);
         }
 
+        // Handle multi-rows merge strategies
+        addMergedRegionIfNecessary(analysisCellList, fillConfig);
+
         // In the case of the fill line may be called many times
         if (rowWriteHandlerContext.getRow() != null) {
             WriteHandlerUtils.afterRowDispose(rowWriteHandlerContext);
@@ -348,7 +465,8 @@ private void createCell(
             AnalysisCell analysisCell,
             FillConfig fillConfig,
             CellWriteHandlerContext cellWriteHandlerContext,
-            RowWriteHandlerContext rowWriteHandlerContext) {
+            RowWriteHandlerContext rowWriteHandlerContext,
+            Integer rowSpan) {
         Sheet cachedSheet = writeContext.writeSheetHolder().getCachedSheet();
         if (WriteTemplateAnalysisCellTypeEnum.COMMON.equals(analysisCell.getCellType())) {
             Row row = cachedSheet.getRow(analysisCell.getRowIndex());
@@ -375,7 +493,8 @@ private void createCell(
                     collectionLastIndexMap.put(analysisCell, lastRowIndex);
                     isOriginalCell = true;
                 } else {
-                    collectionLastIndexMap.put(analysisCell, ++lastRowIndex);
+                    lastRowIndex += rowSpan;
+                    collectionLastIndexMap.put(analysisCell, lastRowIndex);
                 }
                 lastColumnIndex = analysisCell.getColumnIndex();
                 break;
@@ -673,4 +792,34 @@ public static class UniqueDataFlagKey {
         private String sheetName;
         private String wrapperName;
     }
+
+    @Getter
+    @AllArgsConstructor
+    @EqualsAndHashCode
+    public static class CellCoordinate {
+        private final Integer rownum;
+        private final Integer column;
+
+        public Cell getOrCreateCell(Sheet sheet, Sheet cachedSheet) {
+            Row row = sheet.getRow(rownum);
+            if (null == row) {
+                // The last row of the middle disk inside empty rows, resulting in cachedSheet can not get inside.
+                // Will throw Attempting to write a row[" + rownum + "] " + "in the range [0," + this._sh
+                // .getLastRowNum() + "] that is already written to disk.
+                row = cachedSheet.getRow(rownum);
+                if (null == row) {
+                    try {
+                        row = sheet.createRow(rownum);
+                    } catch (IllegalArgumentException ignore) {
+                        row = cachedSheet.createRow(rownum);
+                    }
+                }
+            }
+            Cell cell = row.getCell(column);
+            if (null == cell) {
+                return row.createCell(column);
+            }
+            return cell;
+        }
+    }
 }

fesod-sheet/src/main/java/org/apache/fesod/sheet/write/metadata/fill/FillConfig.java

@@ -25,6 +25,7 @@
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
+import org.apache.fesod.sheet.enums.FillMergeStrategy;
 import org.apache.fesod.sheet.enums.WriteDirectionEnum;
 
 /**
@@ -55,6 +56,20 @@ public class FillConfig {
      */
     private Boolean autoStyle;
 
+    /**
+     * Strategy for handle merged regions during loop filling.
+     * <p>
+     * This strategy applies <b>ONLY</b> when using {@link WriteDirectionEnum#VERTICAL} fill direction with
+     * collection-based data.
+     * </p>
+     * <p>
+     * If used with {@link WriteDirectionEnum#HORIZONTAL}, these strategies (except {@link FillMergeStrategy#NONE})
+     * will throw an exception.
+     * </p>
+     * Defaults {@link FillMergeStrategy#NONE}.
+     */
+    private FillMergeStrategy mergeStrategy;
+
     private boolean hasInit;
 
     public void init() {
@@ -70,6 +85,18 @@ public void init() {
         if (autoStyle == null) {
             autoStyle = Boolean.TRUE;
         }
+        if (mergeStrategy == null) {
+            mergeStrategy = FillMergeStrategy.NONE;
+        }
+
+        validateConfigConstraint();
         hasInit = true;
     }
+
+    private void validateConfigConstraint() {
+        if (direction == WriteDirectionEnum.HORIZONTAL && mergeStrategy != FillMergeStrategy.NONE) {
+            throw new IllegalArgumentException("Conflict detected: Multi-row merge strategy (" + mergeStrategy + ") "
+                    + "is NOT supported when fill direction is HORIZONTAL.");
+        }
+    }
 }