From 1f06f42687c03d976b342a2a22ee24775ee719ca Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Wed, 11 Mar 2026 11:05:32 +0900 Subject: [PATCH] =?UTF-8?q?260311=5F01=5FENH:=20=EC=97=91=EC=85=80=20?= =?UTF-8?q?=EB=A7=A4=ED=8D=BC=EC=97=90=20=EB=8B=A4=EC=A4=91=20=EC=8B=9C?= =?UTF-8?q?=ED=8A=B8,=20=EC=8B=9C=ED=8A=B8=20=EC=A7=80=EC=A0=95=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 5 +- .../com/kri/common/excel/ExcelMapper.java | 1118 +++++++++++++---- 2 files changed, 869 insertions(+), 254 deletions(-) diff --git a/.gitignore b/.gitignore index 1fac4d5..f07a72c 100644 --- a/.gitignore +++ b/.gitignore @@ -6,10 +6,7 @@ build/ .kotlin ### IntelliJ IDEA ### -.idea/modules.xml -.idea/jarRepositories.xml -.idea/compiler.xml -.idea/libraries/ +.idea/ *.iws *.iml *.ipr diff --git a/src/main/java/com/kri/common/excel/ExcelMapper.java b/src/main/java/com/kri/common/excel/ExcelMapper.java index 8d3ed37..c5eecff 100644 --- a/src/main/java/com/kri/common/excel/ExcelMapper.java +++ b/src/main/java/com/kri/common/excel/ExcelMapper.java @@ -15,6 +15,7 @@ import java.util.LinkedHashMap; import java.util.LinkedHashSet; import java.util.List; import java.util.Map; +import java.util.Objects; import java.util.Set; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.ss.usermodel.Cell; @@ -24,6 +25,7 @@ import org.apache.poi.ss.usermodel.Sheet; import org.apache.poi.ss.usermodel.Workbook; import org.apache.poi.ss.util.CellReference; import org.apache.poi.xssf.eventusermodel.XSSFReader; +import org.apache.poi.xssf.eventusermodel.XSSFReader.SheetIterator; import org.apache.poi.xssf.model.SharedStringsTable; import org.apache.poi.xssf.streaming.SXSSFWorkbook; import org.apache.poi.xssf.usermodel.XSSFWorkbook; @@ -36,11 +38,16 @@ import org.xml.sax.helpers.XMLReaderFactory; /** * Excel <-> 객체/맵 변환 유틸리티 *

- * 전제: - DTO 필드는 @ExcelColumn(header = "헤더명", order = 0) 형태로 어노테이션을 단다. - 셀 값 파싱은 - * ExcelUtil.getStringCell(Cell) 사용. + * 전제: + * - DTO 필드는 @ExcelColumn(header = "헤더명", order = 0) 형태로 어노테이션을 단다. + * - 셀 값 파싱은 ExcelUtil.getStringCell(Cell) 사용. */ public final class ExcelMapper { + private static final String DEFAULT_SHEET_NAME = "Sheet1"; + private static final int DEFAULT_SHEET_INDEX = 0; + private static final int DEFAULT_HEADER_ROW_INDEX = 1; + private ExcelMapper() { // 유틸 클래스 - 인스턴스 생성 방지 } @@ -50,65 +57,81 @@ public final class ExcelMapper { * ========================================================= */ public static Workbook writeToWorkbook(List data, Class clazz) { - return writeToWorkbook(data, clazz, 1); + return writeToWorkbook(data, clazz, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); } public static Workbook writeToWorkbook(List data, Class clazz, int headerRowIndex) { - validateHeaderRowIndex(headerRowIndex); + return writeToWorkbook(data, clazz, DEFAULT_SHEET_NAME, headerRowIndex); + } + public static Workbook writeToWorkbook(List data, Class clazz, String sheetName) { + return writeToWorkbook(data, clazz, sheetName, DEFAULT_HEADER_ROW_INDEX); + } + + public static Workbook writeToWorkbook( + List data, + Class clazz, + String sheetName, + int headerRowIndex + ) { Workbook workbook = new XSSFWorkbook(); - Sheet sheet = workbook.createSheet("Sheet1"); - - // 1) @ExcelColumn 기반 메타 수집 - List fields = getExcelFields(clazz); - - // 2) 헤더 작성 - int headerRowNum = toPoiRowIndex(headerRowIndex); - Row headerRow = sheet.createRow(headerRowNum); - for (ExcelFieldMeta meta : fields) { - Cell cell = headerRow.createCell(meta.order()); - cell.setCellValue(meta.header()); - } - - // 3) 데이터 작성 - int rowIndex = headerRowNum + 1; - if (data != null) { - for (T item : data) { - Row row = sheet.createRow(rowIndex++); - for (ExcelFieldMeta meta : fields) { - Cell cell = row.createCell(meta.order()); - Object value = meta.getValue(item); - cell.setCellValue(value != null ? value.toString() : ""); - } - } - } - - // 4) 자동 너비 조정 - for (ExcelFieldMeta meta : fields) { - if (meta.width() > 0) { - sheet.setColumnWidth(meta.order(), meta.width() * 256); - } else { - sheet.autoSizeColumn(meta.order()); - } - } - + appendSheetToWorkbook(workbook, data, clazz, sheetName, headerRowIndex); return workbook; } + public static Workbook writeToWorkbook( + List data, + Class clazz, + int headerRowIndex, + String sheetName + ) { + return writeToWorkbook(data, clazz, sheetName, headerRowIndex); + } + + public static void appendSheetToWorkbook( + Workbook workbook, + List data, + Class clazz, + String sheetName, + int headerRowIndex + ) { + Sheet sheet = createSheetOrThrow(workbook, sheetName); + writeDtoSheet(sheet, data, clazz, headerRowIndex, true); + } + /* ========================================================= * 2. Workbook -> List (in-memory 읽기) * ========================================================= */ public static List readFromWorkbook(Workbook workbook, Class clazz) { - return readFromWorkbook(workbook, clazz, 1); + return readFromWorkbook(workbook, clazz, DEFAULT_SHEET_INDEX, DEFAULT_HEADER_ROW_INDEX); } public static List readFromWorkbook(Workbook workbook, Class clazz, int headerRowIndex) { + return readFromWorkbook(workbook, clazz, DEFAULT_SHEET_INDEX, headerRowIndex); + } + + public static List readFromWorkbook( + Workbook workbook, + Class clazz, + String sheetName, + int headerRowIndex + ) { + return readFromSheet(getSheetByNameOrThrow(workbook, sheetName), clazz, headerRowIndex); + } + + public static List readFromWorkbook( + Workbook workbook, + Class clazz, + int sheetIndex, + int headerRowIndex + ) { + return readFromSheet(getSheetByIndexOrThrow(workbook, sheetIndex), clazz, headerRowIndex); + } + + private static List readFromSheet(Sheet sheet, Class clazz, int headerRowIndex) { validateHeaderRowIndex(headerRowIndex); - Sheet sheet = workbook.getSheetAt(0); - - // 1) 헤더 행 int headerRowNum = toPoiRowIndex(headerRowIndex); Row headerRow = sheet.getRow(headerRowNum); if (headerRow == null) { @@ -127,10 +150,7 @@ public final class ExcelMapper { } } - // 2) DTO 필드 메타 List fields = getExcelFields(clazz); - - // 3) 데이터 행 -> DTO List result = new ArrayList<>(); int lastRowNum = sheet.getLastRowNum(); @@ -151,7 +171,6 @@ public final class ExcelMapper { Cell cell = row.getCell(colIdx); String cellValue = ExcelUtil.getStringCell(cell); - if (cellValue != null) { setFieldValue(instance, meta.field(), cellValue); } @@ -171,13 +190,31 @@ public final class ExcelMapper { * ========================================================= */ public static List> readAsMapList(Workbook workbook) { - return readAsMapList(workbook, 1); + return readAsMapList(workbook, DEFAULT_SHEET_INDEX, DEFAULT_HEADER_ROW_INDEX); } public static List> readAsMapList(Workbook workbook, int headerRowIndex) { - validateHeaderRowIndex(headerRowIndex); + return readAsMapList(workbook, DEFAULT_SHEET_INDEX, headerRowIndex); + } - Sheet sheet = workbook.getSheetAt(0); + public static List> readAsMapList( + Workbook workbook, + String sheetName, + int headerRowIndex + ) { + return readAsMapListFromSheet(getSheetByNameOrThrow(workbook, sheetName), headerRowIndex); + } + + public static List> readAsMapList( + Workbook workbook, + int sheetIndex, + int headerRowIndex + ) { + return readAsMapListFromSheet(getSheetByIndexOrThrow(workbook, sheetIndex), headerRowIndex); + } + + private static List> readAsMapListFromSheet(Sheet sheet, int headerRowIndex) { + validateHeaderRowIndex(headerRowIndex); int headerRowNum = toPoiRowIndex(headerRowIndex); Row headerRow = sheet.getRow(headerRowNum); @@ -231,73 +268,54 @@ public final class ExcelMapper { * ========================================================= */ public static Workbook writeFromMapList(List> rows) { - return writeFromMapList(rows, 1); + return writeFromMapList(rows, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); } public static Workbook writeFromMapList(List> rows, int headerRowIndex) { - validateHeaderRowIndex(headerRowIndex); + return writeFromMapList(rows, DEFAULT_SHEET_NAME, headerRowIndex); + } + public static Workbook writeFromMapList(List> rows, String sheetName) { + return writeFromMapList(rows, sheetName, DEFAULT_HEADER_ROW_INDEX); + } + + public static Workbook writeFromMapList( + List> rows, + String sheetName, + int headerRowIndex + ) { Workbook workbook = new XSSFWorkbook(); - Sheet sheet = workbook.createSheet("Sheet1"); - - if (rows == null || rows.isEmpty()) { - return workbook; - } - - // 전체 헤더 집합 (순서 유지) - Set headerSet = new LinkedHashSet<>(); - for (Map row : rows) { - if (row != null) { - headerSet.addAll(row.keySet()); - } - } - - List headers = new ArrayList<>(headerSet); - - // 헤더 - int headerRowNum = toPoiRowIndex(headerRowIndex); - Row headerRow = sheet.createRow(headerRowNum); - for (int c = 0; c < headers.size(); c++) { - Cell cell = headerRow.createCell(c); - cell.setCellValue(headers.get(c)); - } - - // 데이터 - int rowIndex = headerRowNum + 1; - for (Map rowMap : rows) { - Row row = sheet.createRow(rowIndex++); - if (rowMap == null) { - continue; - } - - for (int c = 0; c < headers.size(); c++) { - String key = headers.get(c); - Object value = rowMap.get(key); - if (value != null) { - row.createCell(c).setCellValue(value.toString()); - } - } - } - - // 자동 컬럼 너비 - for (int c = 0; c < headers.size(); c++) { - sheet.autoSizeColumn(c); - } - + appendMapSheetToWorkbook(workbook, rows, sheetName, headerRowIndex); return workbook; } + public static Workbook writeFromMapList( + List> rows, + int headerRowIndex, + String sheetName + ) { + return writeFromMapList(rows, sheetName, headerRowIndex); + } + + public static void appendMapSheetToWorkbook( + Workbook workbook, + List> rows, + String sheetName, + int headerRowIndex + ) { + Sheet sheet = createSheetOrThrow(workbook, sheetName); + writeMapSheet(sheet, rows, headerRowIndex, true); + } + /* ========================================================= - * 5. Streaming Write (SXSSFWorkbook) - DTO 기반 + * 5. Streaming Write (SXSSFWorkbook) - 즉시 생성/저장 * ========================================================= */ - /** - * 대용량 쓰기를 위한 스트리밍 버전. - * - * @param data 엑셀에 쓸 DTO 리스트 (이미 메모리에 있음) - * @param clazz DTO 타입 - * @param rowAccessWindowSize SXSSFWorkbook row window (예: 100, 500 등) - */ + public static SXSSFWorkbook createStreamingWorkbook(int rowAccessWindowSize) { + SXSSFWorkbook workbook = new SXSSFWorkbook(rowAccessWindowSize); + workbook.setCompressTempFiles(true); + return workbook; + } public static void writeStreaming( Path path, @@ -305,7 +323,7 @@ public final class ExcelMapper { Class clazz, int rowAccessWindowSize ) { - writeStreaming(path, data, clazz, rowAccessWindowSize, 1); + writeStreaming(path, data, clazz, rowAccessWindowSize, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); } public static void writeStreaming( @@ -315,9 +333,18 @@ public final class ExcelMapper { int rowAccessWindowSize, int headerRowIndex ) { - validateHeaderRowIndex(headerRowIndex); + writeStreaming(path, data, clazz, rowAccessWindowSize, DEFAULT_SHEET_NAME, headerRowIndex); + } - try (SXSSFWorkbook workbook = writeStreaming(data, clazz, rowAccessWindowSize, headerRowIndex); + public static void writeStreaming( + Path path, + List data, + Class clazz, + int rowAccessWindowSize, + String sheetName, + int headerRowIndex + ) { + try (SXSSFWorkbook workbook = writeStreaming(data, clazz, rowAccessWindowSize, sheetName, headerRowIndex); OutputStream out = Files.newOutputStream(path)) { workbook.write(out); out.flush(); @@ -326,12 +353,73 @@ public final class ExcelMapper { } } + public static void writeStreaming( + Path path, + List data, + Class clazz, + int rowAccessWindowSize, + int headerRowIndex, + String sheetName + ) { + writeStreaming(path, data, clazz, rowAccessWindowSize, sheetName, headerRowIndex); + } + + public static SXSSFWorkbook writeStreaming( + List data, + Class clazz, + int rowAccessWindowSize + ) { + return writeStreaming(data, clazz, rowAccessWindowSize, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); + } + + public static SXSSFWorkbook writeStreaming( + List data, + Class clazz, + int rowAccessWindowSize, + int headerRowIndex + ) { + return writeStreaming(data, clazz, rowAccessWindowSize, DEFAULT_SHEET_NAME, headerRowIndex); + } + + public static SXSSFWorkbook writeStreaming( + List data, + Class clazz, + int rowAccessWindowSize, + String sheetName, + int headerRowIndex + ) { + SXSSFWorkbook workbook = createStreamingWorkbook(rowAccessWindowSize); + appendStreamingSheet(workbook, data, clazz, sheetName, headerRowIndex); + return workbook; + } + + public static SXSSFWorkbook writeStreaming( + List data, + Class clazz, + int rowAccessWindowSize, + int headerRowIndex, + String sheetName + ) { + return writeStreaming(data, clazz, rowAccessWindowSize, sheetName, headerRowIndex); + } + + public static void appendStreamingSheet( + SXSSFWorkbook workbook, + List data, + Class clazz, + String sheetName, + int headerRowIndex + ) { + Sheet sheet = createSheetOrThrow(workbook, sheetName); + writeDtoSheet(sheet, data, clazz, headerRowIndex, false); + } + public static void writeStreamingFromMap( Path path, List> rows, int rowAccessWindowSize ) { - writeStreamingFromMap(path, rows, rowAccessWindowSize, 1); + writeStreamingFromMap(path, rows, rowAccessWindowSize, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); } public static void writeStreamingFromMap( @@ -340,9 +428,17 @@ public final class ExcelMapper { int rowAccessWindowSize, int headerRowIndex ) { - validateHeaderRowIndex(headerRowIndex); + writeStreamingFromMap(path, rows, rowAccessWindowSize, DEFAULT_SHEET_NAME, headerRowIndex); + } - try (SXSSFWorkbook workbook = writeStreamingFromMap(rows, rowAccessWindowSize, headerRowIndex); + public static void writeStreamingFromMap( + Path path, + List> rows, + int rowAccessWindowSize, + String sheetName, + int headerRowIndex + ) { + try (SXSSFWorkbook workbook = writeStreamingFromMap(rows, rowAccessWindowSize, sheetName, headerRowIndex); OutputStream out = Files.newOutputStream(path)) { workbook.write(out); out.flush(); @@ -351,78 +447,111 @@ public final class ExcelMapper { } } - public static SXSSFWorkbook writeStreaming(List data, - Class clazz, - int rowAccessWindowSize) { - return writeStreaming(data, clazz, rowAccessWindowSize, 1); + public static void writeStreamingFromMap( + Path path, + List> rows, + int rowAccessWindowSize, + int headerRowIndex, + String sheetName + ) { + writeStreamingFromMap(path, rows, rowAccessWindowSize, sheetName, headerRowIndex); } - public static SXSSFWorkbook writeStreaming(List data, - Class clazz, + public static SXSSFWorkbook writeStreamingFromMap( + List> rows, + int rowAccessWindowSize + ) { + return writeStreamingFromMap(rows, rowAccessWindowSize, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); + } + + public static SXSSFWorkbook writeStreamingFromMap( + List> rows, int rowAccessWindowSize, - int headerRowIndex) { - validateHeaderRowIndex(headerRowIndex); - - SXSSFWorkbook workbook = new SXSSFWorkbook(rowAccessWindowSize); - Sheet sheet = workbook.createSheet("Sheet1"); - - // 1) 메타 수집 - List fields = getExcelFields(clazz); - - // 2) 헤더 - int headerRowNum = toPoiRowIndex(headerRowIndex); - Row headerRow = sheet.createRow(headerRowNum); - for (ExcelFieldMeta meta : fields) { - Cell cell = headerRow.createCell(meta.order()); - cell.setCellValue(meta.header()); - } - - // 3) 데이터 - int rowIndex = headerRowNum + 1; - if (data != null) { - for (T item : data) { - Row row = sheet.createRow(rowIndex++); - - for (ExcelFieldMeta meta : fields) { - Cell cell = row.createCell(meta.order()); - Object value = meta.getValue(item); - if (value != null) { - cell.setCellValue(value.toString()); - } else { - cell.setBlank(); - } - } - } - } + int headerRowIndex + ) { + return writeStreamingFromMap(rows, rowAccessWindowSize, DEFAULT_SHEET_NAME, headerRowIndex); + } + public static SXSSFWorkbook writeStreamingFromMap( + List> rows, + int rowAccessWindowSize, + String sheetName, + int headerRowIndex + ) { + SXSSFWorkbook workbook = createStreamingWorkbook(rowAccessWindowSize); + appendStreamingMapSheet(workbook, rows, sheetName, headerRowIndex); return workbook; } + public static SXSSFWorkbook writeStreamingFromMap( + List> rows, + int rowAccessWindowSize, + int headerRowIndex, + String sheetName + ) { + return writeStreamingFromMap(rows, rowAccessWindowSize, sheetName, headerRowIndex); + } + + public static void appendStreamingMapSheet( + SXSSFWorkbook workbook, + List> rows, + String sheetName, + int headerRowIndex + ) { + Sheet sheet = createSheetOrThrow(workbook, sheetName); + writeMapSheet(sheet, rows, headerRowIndex, false); + } /* ========================================================= - * 5-1. Streaming Append Writer (SXSSFWorkbook) - DTO 기반 (chunk 지원) + * 5-1. Streaming Append Writer (SXSSFWorkbook) - chunk append * ========================================================= */ - public static StreamingWriter openStreamingWriter(Class clazz, - int rowAccessWindowSize) { - return openStreamingWriter(clazz, rowAccessWindowSize, 1); + public static StreamingWriter openStreamingWriter( + Class clazz, + int rowAccessWindowSize + ) { + return openStreamingWriter(clazz, rowAccessWindowSize, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); } - public static StreamingWriter openStreamingWriter(Class clazz, + public static StreamingWriter openStreamingWriter( + Class clazz, int rowAccessWindowSize, - int headerRowIndex) { + int headerRowIndex + ) { + return openStreamingWriter(clazz, rowAccessWindowSize, DEFAULT_SHEET_NAME, headerRowIndex); + } + + public static StreamingWriter openStreamingWriter( + Class clazz, + int rowAccessWindowSize, + String sheetName, + int headerRowIndex + ) { + SXSSFWorkbook workbook = createStreamingWorkbook(rowAccessWindowSize); + return openStreamingWriter(workbook, clazz, sheetName, headerRowIndex, true); + } + + public static StreamingWriter openStreamingWriter( + SXSSFWorkbook workbook, + Class clazz, + String sheetName, + int headerRowIndex + ) { + return openStreamingWriter(workbook, clazz, sheetName, headerRowIndex, false); + } + + private static StreamingWriter openStreamingWriter( + SXSSFWorkbook workbook, + Class clazz, + String sheetName, + int headerRowIndex, + boolean closeWorkbookOnClose + ) { validateHeaderRowIndex(headerRowIndex); - SXSSFWorkbook workbook = new SXSSFWorkbook(rowAccessWindowSize); - Sheet sheet = workbook.createSheet("Sheet1"); - - // temp 파일 압축 저장 - 디스크 사용량 감소 - workbook.setCompressTempFiles(true); - - // 1) 메타 수집 + Sheet sheet = createSheetOrThrow(workbook, sheetName); List fields = getExcelFields(clazz); - // 2) 헤더 작성 int headerRowNum = toPoiRowIndex(headerRowIndex); Row headerRow = sheet.createRow(headerRowNum); for (ExcelFieldMeta meta : fields) { @@ -430,127 +559,284 @@ public final class ExcelMapper { cell.setCellValue(meta.header()); } - return new StreamingWriter<>(workbook, sheet, fields, headerRowNum + 1); + return new StreamingWriter<>(workbook, sheet, fields, headerRowNum + 1, closeWorkbookOnClose); } - public static SXSSFWorkbook writeStreamingFromMap(List> rows, - int rowAccessWindowSize) { - return writeStreamingFromMap(rows, rowAccessWindowSize, 1); + public static StreamingMapWriter openStreamingMapWriter( + List headers, + int rowAccessWindowSize + ) { + return openStreamingMapWriter(headers, rowAccessWindowSize, DEFAULT_SHEET_NAME, DEFAULT_HEADER_ROW_INDEX); } - public static SXSSFWorkbook writeStreamingFromMap(List> rows, + public static StreamingMapWriter openStreamingMapWriter( + List headers, int rowAccessWindowSize, - int headerRowIndex) { + int headerRowIndex + ) { + return openStreamingMapWriter(headers, rowAccessWindowSize, DEFAULT_SHEET_NAME, headerRowIndex); + } + + public static StreamingMapWriter openStreamingMapWriter( + List headers, + int rowAccessWindowSize, + String sheetName, + int headerRowIndex + ) { + SXSSFWorkbook workbook = createStreamingWorkbook(rowAccessWindowSize); + return openStreamingMapWriter(workbook, headers, sheetName, headerRowIndex, true); + } + + public static StreamingMapWriter openStreamingMapWriter( + SXSSFWorkbook workbook, + List headers, + String sheetName, + int headerRowIndex + ) { + return openStreamingMapWriter(workbook, headers, sheetName, headerRowIndex, false); + } + + private static StreamingMapWriter openStreamingMapWriter( + SXSSFWorkbook workbook, + List headers, + String sheetName, + int headerRowIndex, + boolean closeWorkbookOnClose + ) { validateHeaderRowIndex(headerRowIndex); - SXSSFWorkbook workbook = new SXSSFWorkbook(rowAccessWindowSize); - Sheet sheet = workbook.createSheet("Sheet1"); + List normalizedHeaders = normalizeHeaders(headers); + Sheet sheet = createSheetOrThrow(workbook, sheetName); - if (rows == null || rows.isEmpty()) { - return workbook; - } - - // 전체 헤더 집합 - Set headerSet = new LinkedHashSet<>(); - for (Map row : rows) { - if (row != null) { - headerSet.addAll(row.keySet()); - } - } - List headers = new ArrayList<>(headerSet); - - // 헤더 int headerRowNum = toPoiRowIndex(headerRowIndex); Row headerRow = sheet.createRow(headerRowNum); - for (int c = 0; c < headers.size(); c++) { - headerRow.createCell(c).setCellValue(headers.get(c)); + for (int c = 0; c < normalizedHeaders.size(); c++) { + headerRow.createCell(c).setCellValue(normalizedHeaders.get(c)); } - // 데이터 - int rowIndex = headerRowNum + 1; - for (Map rowMap : rows) { - Row row = sheet.createRow(rowIndex++); - if (rowMap == null) { - continue; - } - - for (int c = 0; c < headers.size(); c++) { - String key = headers.get(c); - Object value = rowMap.get(key); - if (value != null) { - row.createCell(c).setCellValue(value.toString()); - } - } - } - - return workbook; + return new StreamingMapWriter(workbook, sheet, normalizedHeaders, headerRowNum + 1, closeWorkbookOnClose); } - /* ========================================================= * 6. Streaming Read (XSSFReader + SAX) -> RowMapHandler * ========================================================= */ - /** - * XSSFReader + SAX 기반 스트리밍 읽기. - * - 첫 번째 시트만 읽음. - * - headerRowIndex 행을 헤더로 간주하고, 그 다음 행부터 데이터를 읽음. - */ public static void readStreaming(Path path, RowMapHandler handler) { - readStreaming(path, 1, handler); + readStreaming(path, DEFAULT_SHEET_INDEX, DEFAULT_HEADER_ROW_INDEX, handler); } public static void readStreaming(Path path, int headerRowIndex, RowMapHandler handler) { + readStreaming(path, DEFAULT_SHEET_INDEX, headerRowIndex, handler); + } + + public static void readStreaming(Path path, String sheetName, int headerRowIndex, RowMapHandler handler) { + validateHeaderRowIndex(headerRowIndex); + try (OPCPackage pkg = OPCPackage.open(path.toFile())) { - XSSFReader reader = new XSSFReader(pkg); - SharedStringsTable sst = (SharedStringsTable) reader.getSharedStringsTable(); + readStreaming(pkg, sheetName, null, headerRowIndex, handler); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 읽기 중 오류", e); + } + } - XMLReader parser = XMLReaderFactory.createXMLReader(); - SheetToMapHandler sheetHandler = new SheetToMapHandler(sst, handler, headerRowIndex); - parser.setContentHandler(sheetHandler); + public static void readStreaming(Path path, int sheetIndex, int headerRowIndex, RowMapHandler handler) { + validateHeaderRowIndex(headerRowIndex); - Iterator sheets = reader.getSheetsData(); - if (sheets.hasNext()) { - try (InputStream sheetIS = sheets.next()) { - parser.parse(new InputSource(sheetIS)); - } - } + try (OPCPackage pkg = OPCPackage.open(path.toFile())) { + readStreaming(pkg, null, sheetIndex, headerRowIndex, handler); } catch (Exception e) { throw new RuntimeException("Streaming 엑셀 읽기 중 오류", e); } } public static void readStreaming(InputStream inputStream, RowMapHandler handler) { - readStreaming(inputStream, 1, handler); + readStreaming(inputStream, DEFAULT_SHEET_INDEX, DEFAULT_HEADER_ROW_INDEX, handler); + } + + public static void readStreaming(InputStream inputStream, int headerRowIndex, RowMapHandler handler) { + readStreaming(inputStream, DEFAULT_SHEET_INDEX, headerRowIndex, handler); } public static void readStreaming( InputStream inputStream, + String sheetName, int headerRowIndex, RowMapHandler handler ) { validateHeaderRowIndex(headerRowIndex); try (OPCPackage pkg = OPCPackage.open(inputStream)) { + readStreaming(pkg, sheetName, null, headerRowIndex, handler); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 읽기 중 오류", e); + } + } + + public static void readStreaming( + InputStream inputStream, + int sheetIndex, + int headerRowIndex, + RowMapHandler handler + ) { + validateHeaderRowIndex(headerRowIndex); + + try (OPCPackage pkg = OPCPackage.open(inputStream)) { + readStreaming(pkg, null, sheetIndex, headerRowIndex, handler); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 읽기 중 오류", e); + } + } + + private static void readStreaming( + OPCPackage pkg, + String sheetName, + Integer sheetIndex, + int headerRowIndex, + RowMapHandler handler + ) throws Exception { + XSSFReader reader = new XSSFReader(pkg); + SharedStringsTable sst = (SharedStringsTable) reader.getSharedStringsTable(); + + XMLReader parser = XMLReaderFactory.createXMLReader(); + SheetToMapHandler sheetHandler = new SheetToMapHandler(sst, handler, headerRowIndex); + parser.setContentHandler(sheetHandler); + + try (InputStream sheetIS = openTargetSheet(reader, sheetName, sheetIndex)) { + parser.parse(new InputSource(sheetIS)); + } + } + + /* ========================================================= + * 6-1. Streaming Read Header Only (XSSFReader + SAX) + * ========================================================= */ + + public static List readHeaderStreaming(Path path) { + return readHeaderStreaming(path, DEFAULT_SHEET_INDEX, DEFAULT_HEADER_ROW_INDEX); + } + + public static List readHeaderStreaming(Path path, int headerRowIndex) { + return readHeaderStreaming(path, DEFAULT_SHEET_INDEX, headerRowIndex); + } + + public static List readHeaderStreaming(Path path, int sheetIndex, int headerRowIndex) { + validateHeaderRowIndex(headerRowIndex); + + try (OPCPackage pkg = OPCPackage.open(path.toFile())) { + return readHeaderStreaming(pkg, null, sheetIndex, headerRowIndex); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 헤더 읽기 중 오류", e); + } + } + + public static List readHeaderStreaming(Path path, String sheetName, int headerRowIndex) { + validateHeaderRowIndex(headerRowIndex); + + try (OPCPackage pkg = OPCPackage.open(path.toFile())) { + return readHeaderStreaming(pkg, sheetName, null, headerRowIndex); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 헤더 읽기 중 오류", e); + } + } + + public static List readHeaderStreaming(InputStream inputStream) { + return readHeaderStreaming(inputStream, DEFAULT_SHEET_INDEX, DEFAULT_HEADER_ROW_INDEX); + } + + public static List readHeaderStreaming(InputStream inputStream, int headerRowIndex) { + return readHeaderStreaming(inputStream, DEFAULT_SHEET_INDEX, headerRowIndex); + } + + public static List readHeaderStreaming( + InputStream inputStream, + int sheetIndex, + int headerRowIndex + ) { + validateHeaderRowIndex(headerRowIndex); + + try (OPCPackage pkg = OPCPackage.open(inputStream)) { + return readHeaderStreaming(pkg, null, sheetIndex, headerRowIndex); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 헤더 읽기 중 오류", e); + } + } + + public static List readHeaderStreaming( + InputStream inputStream, + String sheetName, + int headerRowIndex + ) { + validateHeaderRowIndex(headerRowIndex); + + try (OPCPackage pkg = OPCPackage.open(inputStream)) { + return readHeaderStreaming(pkg, sheetName, null, headerRowIndex); + } catch (Exception e) { + throw new RuntimeException("Streaming 엑셀 헤더 읽기 중 오류", e); + } + } + + private static List readHeaderStreaming( + OPCPackage pkg, + String sheetName, + Integer sheetIndex, + int headerRowIndex + ) { + try { XSSFReader reader = new XSSFReader(pkg); SharedStringsTable sst = (SharedStringsTable) reader.getSharedStringsTable(); XMLReader parser = XMLReaderFactory.createXMLReader(); - SheetToMapHandler sheetHandler = new SheetToMapHandler(sst, handler, headerRowIndex); - parser.setContentHandler(sheetHandler); + HeaderOnlyHandler headerHandler = new HeaderOnlyHandler(sst, headerRowIndex); + parser.setContentHandler(headerHandler); - Iterator sheets = reader.getSheetsData(); - if (sheets.hasNext()) { - try (InputStream sheetIS = sheets.next()) { - InputSource sheetSource = new InputSource(sheetIS); - parser.parse(sheetSource); + try (InputStream sheetIS = openTargetSheet(reader, sheetName, sheetIndex)) { + try { + parser.parse(new InputSource(sheetIS)); + } catch (StopParsingException ignored) { + // 헤더를 찾은 즉시 정상 종료 } } + + return headerHandler.getHeaders(); } catch (Exception e) { - throw new RuntimeException("Streaming 엑셀 읽기 중 오류", e); + throw new RuntimeException("Streaming 엑셀 헤더 읽기 중 오류", e); } } + private static InputStream openTargetSheet( + XSSFReader reader, + String sheetName, + Integer sheetIndex + ) throws Exception { + Iterator iterator = reader.getSheetsData(); + if (!(iterator instanceof SheetIterator sheetIterator)) { + throw new IllegalStateException("SheetIterator를 사용할 수 없습니다."); + } + + String normalizedSheetName = sheetName == null ? null : normalizeSheetName(sheetName); + int currentIndex = 0; + + while (sheetIterator.hasNext()) { + InputStream sheetIS = sheetIterator.next(); + String currentSheetName = sheetIterator.getSheetName(); + + boolean matched = sheetIndex != null + ? currentIndex == sheetIndex + : Objects.equals(currentSheetName, normalizedSheetName); + + if (matched) { + return sheetIS; + } + + sheetIS.close(); + currentIndex++; + } + + if (sheetIndex != null) { + throw new IllegalArgumentException("시트를 찾을 수 없습니다. sheetIndex=" + sheetIndex); + } + throw new IllegalArgumentException("시트를 찾을 수 없습니다. sheetName=" + normalizedSheetName); + } + private static List getExcelFields(Class clazz) { List result = new ArrayList<>(); @@ -574,13 +860,10 @@ public final class ExcelMapper { throws IllegalAccessException { Class type = field.getType(); - // 1) null 또는 공백 처리 if (value == null || value.isBlank()) { - // primitive 타입이면 기본값 유지 (0, false 등) → 그냥 리턴 if (type.isPrimitive()) { return; } - // 래퍼 타입(String, Integer, Long, Boolean, ...)이면 null 세팅 field.set(target, null); return; } @@ -605,9 +888,9 @@ public final class ExcelMapper { } } catch (NumberFormatException e) { throw new RuntimeException( - "엑셀 값 파싱 실패: field=" + field.getName() + - ", type=" + type.getSimpleName() + - ", value='" + value + "'", + "엑셀 값 파싱 실패: field=" + field.getName() + + ", type=" + type.getSimpleName() + + ", value='" + value + "'", e ); } @@ -623,6 +906,160 @@ public final class ExcelMapper { return headerRowIndex - 1; } + private static String normalizeSheetName(String sheetName) { + if (sheetName == null || sheetName.isBlank()) { + return DEFAULT_SHEET_NAME; + } + return sheetName.trim(); + } + + private static Sheet getSheetByIndexOrThrow(Workbook workbook, int sheetIndex) { + if (sheetIndex < 0 || sheetIndex >= workbook.getNumberOfSheets()) { + throw new IllegalArgumentException("유효하지 않은 sheetIndex 입니다. index=" + sheetIndex); + } + return workbook.getSheetAt(sheetIndex); + } + + private static Sheet getSheetByNameOrThrow(Workbook workbook, String sheetName) { + String normalized = normalizeSheetName(sheetName); + Sheet sheet = workbook.getSheet(normalized); + if (sheet == null) { + throw new IllegalArgumentException("시트를 찾을 수 없습니다. sheetName=" + normalized); + } + return sheet; + } + + private static Sheet createSheetOrThrow(Workbook workbook, String sheetName) { + String normalized = normalizeSheetName(sheetName); + if (workbook.getSheet(normalized) != null) { + throw new IllegalArgumentException("이미 존재하는 시트명입니다. sheetName=" + normalized); + } + return workbook.createSheet(normalized); + } + + private static void writeDtoSheet( + Sheet sheet, + List data, + Class clazz, + int headerRowIndex, + boolean autoSize + ) { + validateHeaderRowIndex(headerRowIndex); + + List fields = getExcelFields(clazz); + + int headerRowNum = toPoiRowIndex(headerRowIndex); + Row headerRow = sheet.createRow(headerRowNum); + for (ExcelFieldMeta meta : fields) { + Cell cell = headerRow.createCell(meta.order()); + cell.setCellValue(meta.header()); + } + + int rowIndex = headerRowNum + 1; + if (data != null) { + for (T item : data) { + Row row = sheet.createRow(rowIndex++); + for (ExcelFieldMeta meta : fields) { + Cell cell = row.createCell(meta.order()); + Object value = meta.getValue(item); + if (value != null) { + cell.setCellValue(value.toString()); + } else { + cell.setBlank(); + } + } + } + } + + if (autoSize) { + for (ExcelFieldMeta meta : fields) { + if (meta.width() > 0) { + sheet.setColumnWidth(meta.order(), meta.width() * 256); + } else { + sheet.autoSizeColumn(meta.order()); + } + } + } + } + + private static void writeMapSheet( + Sheet sheet, + List> rows, + int headerRowIndex, + boolean autoSize + ) { + validateHeaderRowIndex(headerRowIndex); + + List headers = normalizeHeadersFromRows(rows); + if (headers.isEmpty()) { + return; + } + + int headerRowNum = toPoiRowIndex(headerRowIndex); + Row headerRow = sheet.createRow(headerRowNum); + for (int c = 0; c < headers.size(); c++) { + headerRow.createCell(c).setCellValue(headers.get(c)); + } + + int rowIndex = headerRowNum + 1; + if (rows != null) { + for (Map rowMap : rows) { + Row row = sheet.createRow(rowIndex++); + if (rowMap == null) { + continue; + } + + for (int c = 0; c < headers.size(); c++) { + String key = headers.get(c); + Object value = rowMap.get(key); + if (value != null) { + row.createCell(c).setCellValue(value.toString()); + } + } + } + } + + if (autoSize) { + for (int c = 0; c < headers.size(); c++) { + sheet.autoSizeColumn(c); + } + } + } + + private static List normalizeHeadersFromRows(List> rows) { + if (rows == null || rows.isEmpty()) { + return List.of(); + } + + Set headerSet = new LinkedHashSet<>(); + for (Map row : rows) { + if (row != null) { + headerSet.addAll(row.keySet()); + } + } + return normalizeHeaders(new ArrayList<>(headerSet)); + } + + private static List normalizeHeaders(List headers) { + if (headers == null || headers.isEmpty()) { + return List.of(); + } + + List result = new ArrayList<>(headers.size()); + Set duplicateCheck = new LinkedHashSet<>(); + for (int i = 0; i < headers.size(); i++) { + String header = headers.get(i); + if (header == null || header.isBlank()) { + header = "COL_" + i; + } + if (!duplicateCheck.add(header)) { + throw new IllegalArgumentException("헤더명이 중복됩니다. header=" + header); + } + result.add(header); + } + return result; + } + @FunctionalInterface public interface RowMapHandler { @@ -634,22 +1071,30 @@ public final class ExcelMapper { } /** - * chunk 단위로 append 가능한 SXSSF Writer - rowAccessWindowSize 만큼만 메모리에 유지하고 나머지는 temp file로 flush - - * 마지막에 writeTo(OutputStream) 한 번 호출로 XLSX 완성 + * chunk 단위로 append 가능한 SXSSF Writer + * - rowAccessWindowSize 만큼만 메모리에 유지하고 나머지는 temp file로 flush + * - 마지막에 writeTo(OutputStream) 한 번 호출로 XLSX 완성 */ public static final class StreamingWriter implements AutoCloseable { private final SXSSFWorkbook workbook; private final Sheet sheet; private final List fields; + private final boolean closeWorkbookOnClose; private int rowIndex; - private StreamingWriter(SXSSFWorkbook workbook, Sheet sheet, List fields, - int rowIndex) { + private StreamingWriter( + SXSSFWorkbook workbook, + Sheet sheet, + List fields, + int rowIndex, + boolean closeWorkbookOnClose + ) { this.workbook = workbook; this.sheet = sheet; this.fields = fields; this.rowIndex = rowIndex; + this.closeWorkbookOnClose = closeWorkbookOnClose; } public void append(T item) { @@ -678,9 +1123,6 @@ public final class ExcelMapper { } } - /** - * XLSX는 마지막에 한 번 write 해야 파일이 완성됩니다. - */ public void writeTo(OutputStream out) throws IOException { workbook.write(out); out.flush(); @@ -694,8 +1136,81 @@ public final class ExcelMapper { @Override public void close() throws IOException { - workbook.dispose(); - workbook.close(); + if (closeWorkbookOnClose) { + workbook.dispose(); + workbook.close(); + } + } + } + + public static final class StreamingMapWriter implements AutoCloseable { + + private final SXSSFWorkbook workbook; + private final Sheet sheet; + private final List headers; + private final boolean closeWorkbookOnClose; + private int rowIndex; + + private StreamingMapWriter( + SXSSFWorkbook workbook, + Sheet sheet, + List headers, + int rowIndex, + boolean closeWorkbookOnClose + ) { + this.workbook = workbook; + this.sheet = sheet; + this.headers = headers; + this.rowIndex = rowIndex; + this.closeWorkbookOnClose = closeWorkbookOnClose; + } + + public void append(Map rowMap) { + Row row = sheet.createRow(rowIndex++); + if (rowMap == null) { + return; + } + + for (int c = 0; c < headers.size(); c++) { + Object value = rowMap.get(headers.get(c)); + if (value != null) { + row.createCell(c).setCellValue(value.toString()); + } + } + } + + public void appendAll(Collection> rows) { + if (rows == null || rows.isEmpty()) { + return; + } + for (Map row : rows) { + append(row); + } + } + + public void writeTo(OutputStream out) throws IOException { + workbook.write(out); + out.flush(); + } + + public void writeTo(Path path) throws IOException { + try (OutputStream out = Files.newOutputStream(path)) { + writeTo(out); + } + } + + @Override + public void close() throws IOException { + if (closeWorkbookOnClose) { + workbook.dispose(); + workbook.close(); + } + } + } + + private static final class StopParsingException extends RuntimeException { + private StopParsingException() { + super(null, null, false, false); } } @@ -827,6 +1342,109 @@ public final class ExcelMapper { } } + private static class HeaderOnlyHandler extends DefaultHandler { + private final SharedStringsTable sst; + private final int headerRowIndex; // 1-based + private final Map cellMap = new HashMap<>(); + + private int currentRowNum; + private String currentCellRef; + private String currentCellType; + private StringBuilder currentValue; + private boolean isValueOpen; + private List headers = new ArrayList<>(); + + HeaderOnlyHandler(SharedStringsTable sst, int headerRowIndex) { + validateHeaderRowIndex(headerRowIndex); + this.sst = sst; + this.headerRowIndex = headerRowIndex; + } + + List getHeaders() { + return headers; + } + + @Override + public void startElement(String uri, String localName, String qName, Attributes attributes) { + if ("row".equals(qName)) { + String r = attributes.getValue("r"); + if (r != null) { + currentRowNum = Integer.parseInt(r); + } else { + currentRowNum++; + } + cellMap.clear(); + } else if ("c".equals(qName)) { + currentCellRef = attributes.getValue("r"); + currentCellType = attributes.getValue("t"); + } else if ("v".equals(qName) || "t".equals(qName)) { + currentValue = new StringBuilder(); + isValueOpen = true; + } + } + + @Override + public void characters(char[] ch, int start, int length) { + if (isValueOpen && currentValue != null) { + currentValue.append(ch, start, length); + } + } + + @Override + public void endElement(String uri, String localName, String qName) { + if ("v".equals(qName) || "t".equals(qName)) { + String raw = currentValue != null ? currentValue.toString() : ""; + String resolved = resolveCellValue(raw, currentCellType); + + if (currentCellRef != null) { + int colIdx = new CellReference(currentCellRef).getCol(); + cellMap.put(colIdx, resolved); + } + + isValueOpen = false; + currentValue = null; + return; + } + + if ("row".equals(qName) && currentRowNum == headerRowIndex) { + headers = buildHeaders(cellMap); + throw new StopParsingException(); + } + } + + private List buildHeaders(Map cellMap) { + if (cellMap.isEmpty()) { + return List.of(); + } + + int maxCol = cellMap.keySet().stream().max(Integer::compareTo).orElse(-1); + List result = new ArrayList<>(maxCol + 1); + + for (int c = 0; c <= maxCol; c++) { + String header = cellMap.get(c); + if (header == null || header.isBlank()) { + header = "COL_" + c; + } + result.add(header); + } + + return result; + } + + private String resolveCellValue(String raw, String cellType) { + if ("s".equals(cellType)) { + try { + int idx = Integer.parseInt(raw); + RichTextString rich = sst.getItemAt(idx); + return rich != null ? rich.getString() : ""; + } catch (Exception e) { + return raw; + } + } + return raw; + } + } + private record ExcelFieldMeta(Field field, String header, int order, int width) { Object getValue(Object target) {