Overview of EasyPOI

While Apache POI provides robust low-level control over spreadsheet formats, developers often encounter verbose boilerplate when handling complex reporting requirements. EasyPOI addresses this by introducing a higher-level abstraction that prioritizes developer productivity. Built upon Apache POI, it automates repetitive tasks such as header generation, formatting, and data mapping through a clean annotation-based and configuration-driven approach.

This library was originally conceptualized to handle rapid changing business report specifications without requiring constant code refactoring. By decoupling data models from spreadsheet layouts, it significantly reduces maintenance overhead and accelreates development cycles.

Project Setup

Integrate the necessary modules into your Maven project. The core components handle data manipulation, web context integration, and annotation processing:

<dependencies>
    <dependency>
        <groupId>cn.afterturn</groupId>
        <artifactId>easypoi-base</artifactId>
        <version>4.4.0</version>
    </dependency>
    <dependency>
        <groupId>cn.afterturn</groupId>
        <artifactId>easypoi-web</artifactId>
        <version>4.4.0</version>
    </dependency>
    <dependency>
        <groupId>cn.afterturn</groupId>
        <artifactId>easypoi-annotation</artifactId>
        <version>4.4.0</version>
    </dependency>
</dependencies>

Annotation-Driven Export and Import

The most straightforward usage pattern involves annotating Java beans. The @Excel marker defines column headers, data formatting, and cell dimensions directly on the model feilds.

Model Definition

public class EmployeeRecord {

    @Excel(name = "Full Name")
    private String fullName;

    @Excel(name = "Years of Service")
    private int tenure;

    @Excel(name = "Hire Date", format = "yyyy-MM-dd HH:mm:ss", width = 25.0)
    private java.util.Date hireTimestamp;

    // Standard getters and setters omitted for brevity
}

Generating Spreadsheets

Exporting data requires populating a list of objects and passing it to the export utility. The ExportParams object configures sheet titles and sheet names.

public static void generateReport() throws Exception {
    List<EmployeeRecord> roster = new ArrayList<>();
    for (int idx = 0; idx < 10; idx++) {
        EmployeeRecord record = new EmployeeRecord();
        record.setFullName("Employee_" + idx);
        record.setTenure(2 + idx);
        record.setHireTimestamp(new java.util.Date(System.currentTimeMillis() + (idx * 86400000L)));
        roster.add(record);
    }

    ExportParams config = new ExportParams("Personnel Department", "Monthly Roster");
    Workbook workbook = ExcelExportUtil.exportExcel(config, EmployeeRecord.class, roster);

    try (FileOutputStream outputStream = new FileOutputStream("output_roster.xls")) {
        workbook.write(outputStream);
    }
}

Reading Spreadsheets

Importing follows a symmetric pattern. Configuration parameters specify how many rows contain titles versus column headers.

public static void loadReport() {
    ImportParams importConfig = new ImportParams();
    importConfig.setTitleRows(1);
    importConfig.setHeadRows(1);

    long startTime = System.currentTimeMillis();
    List<EmployeeRecord> loadedData = ExcelImportUtil.importExcel(
        new File("output_roster.xls"), EmployeeRecord.class, importConfig);

    System.out.println("Processing took: " + (System.currentTimeMillis() - startTime) + " ms");
    System.out.println("Loaded records: " + loadedData.size());
}

Dynamic Data Structure Mapping

When working with unstructured data or runtime-determined schemas, EasyPOI supports dynamic column configuration via ExcelExportEntity and Map collections.

Exporting Dynamic Data

public static void exportDynamicData() throws Exception {
    List<ExcelExportEntity> columnDefinitions = new ArrayList<>();
    columnDefinitions.add(new ExcelExportEntity("Identifier", "id"));
    columnDefinitions.add(new ExcelExportEntity("Status", "status"));

    ExcelExportEntity timestampCol = new ExcelExportEntity("Processed At", "processedAt");
    timestampCol.setFormat("yyyy-MM-dd");
    timestampCol.setWidth(18.0);
    columnDefinitions.add(timestampCol);

    List<Map<String, Object>> dataset = new ArrayList<>();
    for (int i = 0; i < 5; i++) {
        Map<String, Object> row = new HashMap<>();
        row.put("id", "TASK-" + i);
        row.put("status", i % 2 == 0 ? "Completed" : "Pending");
        row.put("processedAt", new java.util.Date());
        dataset.add(row);
    }

    ExportParams params = new ExportParams("Operations", "Task Log");
    Workbook sheet = ExcelExportUtil.exportExcel(params, columnDefinitions, dataset);

    try (FileOutputStream out = new FileOutputStream("dynamic_tasks.xls")) {
        sheet.write(out);
    }
}

Importing Dynamic Data

Reading dynamic sheets returns a list of maps, preserving the key-value structure defined during export or existing in the file.

public static void importDynamicData() {
    ImportParams config = new ImportParams();
    config.setTitleRows(1);
    config.setHeadRows(1);

    List<Map<String, Object>> rows = ExcelImportUtil.importExcel(
        new File("dynamic_tasks.xls"), Map.class, config);

    rows.forEach(row -> System.out.println("Row data: " + row));
}

Performance and Memory Management

By default, EasyPOI loads data structures entirely into heap memory before rendering the final binary stream. This approach delivers exceptional throughput for standard dataset sizes. However, when processing files with hundreds of thousands of rows, heap exhaustion becomes a risk. For large-scale operations, the library provides streaming alternatives such as ExcelExportUtil.exportBigExcel() and SAX-based parsers. These methods write or read data in chunks, maintaining a constant memory footprint regardless of file size.