or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

annotations-and-mapping.mddata-conversion.mdevent-system.mdexception-handling.mdindex.mdreading-operations.mdwriting-operations.md
tile.json

tessl/maven-com-alibaba--easyexcel

High-performance Java library for reading and writing Excel files with minimal memory usage

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.alibaba/easyexcel@4.0.x

To install, run

npx @tessl/cli install tessl/maven-com-alibaba--easyexcel@4.0.0

index.mddocs/

EasyExcel

EasyExcel is a high-performance Java library for reading and writing Excel files with minimal memory usage. It solves memory overflow problems commonly encountered with Apache POI by rewriting the parsing logic for Excel 2007+ files (.xlsx). The library can process large Excel files using only minimal memory through streaming operations and provides a simple, annotation-based API for mapping Java objects to Excel rows.

Package Information

  • Package Name: com.alibaba:easyexcel
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>com.alibaba</groupId>
  <artifactId>easyexcel</artifactId>
  <version>4.0.3</version>
</dependency>

Core Imports

import com.alibaba.excel.EasyExcel;
import com.alibaba.excel.read.listener.ReadListener;
import com.alibaba.excel.context.AnalysisContext;

For annotation-based mapping:

import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.ExcelIgnore;
import com.alibaba.excel.annotation.format.DateTimeFormat;
import com.alibaba.excel.annotation.format.NumberFormat;

Basic Usage

Simple Reading

import com.alibaba.excel.EasyExcel;

// Read Excel file and convert to List
List<UserData> userList = EasyExcel.read("users.xlsx")
    .head(UserData.class)
    .sheet()
    .doReadSync();

// Event-driven reading for large files
EasyExcel.read("large-file.xlsx", UserData.class, new UserDataListener())
    .sheet()
    .doRead();

Simple Writing

import com.alibaba.excel.EasyExcel;

// Write data to Excel file
List<UserData> dataList = getUserData();
EasyExcel.write("output.xlsx", UserData.class)
    .sheet("Users")
    .doWrite(dataList);

Basic Data Model

import com.alibaba.excel.annotation.ExcelProperty;

public class UserData {
    @ExcelProperty("Name")
    private String name;
    
    @ExcelProperty("Age")
    private Integer age;
    
    @ExcelProperty("Email")
    private String email;
    
    // Getters and setters...
}

Architecture

EasyExcel is built around several key components:

  • Factory Pattern: EasyExcel and EasyExcelFactory provide static factory methods for creating readers and writers
  • Builder Pattern: Fluent builders (ExcelReaderBuilder, ExcelWriterBuilder) for configuration
  • Event-Driven Processing: Listener-based architecture (ReadListener) for memory-efficient processing of large files
  • Annotation System: Rich annotations for field mapping, formatting, and styling configuration
  • Converter System: Pluggable type conversion between Java objects and Excel cell values
  • Streaming Architecture: Low-memory consumption through streaming read/write operations

Capabilities

Reading Operations

Core functionality for reading Excel files with memory-efficient streaming and event-driven processing.

// Main entry points
public static ExcelReaderBuilder read();
public static ExcelReaderBuilder read(File file);
public static ExcelReaderBuilder read(String pathName);
public static ExcelReaderBuilder read(InputStream inputStream);

// Reader builder configuration
public class ExcelReaderBuilder {
    public ExcelReaderBuilder head(Class<?> head);
    public ExcelReaderBuilder registerReadListener(ReadListener<?> readListener);
    public ExcelReaderBuilder charset(Charset charset);
    public ExcelReaderBuilder password(String password);
    public ExcelReaderBuilder ignoreEmptyRow(Boolean ignoreEmptyRow);
    public ExcelReader build();
    public List<Object> doReadAllSync();
    public ExcelReaderSheetBuilder sheet();
}

Reading Operations

Writing Operations

Functionality for creating and writing Excel files with template support and styling options.

// Main entry points  
public static ExcelWriterBuilder write();
public static ExcelWriterBuilder write(File file);
public static ExcelWriterBuilder write(String pathName);
public static ExcelWriterBuilder write(OutputStream outputStream);

// Writer builder configuration
public class ExcelWriterBuilder {
    public ExcelWriterBuilder head(Class<?> head);
    public ExcelWriterBuilder charset(Charset charset);
    public ExcelWriterBuilder password(String password);
    public ExcelWriterBuilder withTemplate(File templateFile);
    public ExcelWriter build();
    public ExcelWriterSheetBuilder sheet();
}

Writing Operations

Annotations and Mapping

Annotation-based system for mapping Java fields to Excel columns with formatting and styling support.

// Core mapping annotations
@ExcelProperty(value = "Column Name", index = 0, order = 1)
@ExcelIgnore
@ExcelIgnoreUnannotated

// Format annotations
@DateTimeFormat("yyyy-MM-dd HH:mm:ss")
@NumberFormat("#.##")

// Style annotations
@ColumnWidth(15)
@HeadStyle(fillForegroundColor = 40)
@ContentStyle(dataFormat = 49)
@HeadRowHeight(20)
@ContentRowHeight(18)

Annotations and Mapping

Event System

Event-driven processing system with listeners for handling large datasets efficiently.

// Core listener interface
public interface ReadListener<T> {
    void invoke(T data, AnalysisContext context);
    void doAfterAllAnalysed(AnalysisContext context);
    void onException(Exception exception, AnalysisContext context);
    void invokeHead(Map<Integer, ReadCellData<?>> headMap, AnalysisContext context);
}

// Context for accessing metadata
public interface AnalysisContext {
    Object getCurrentRowAnalysisResult();
    Integer getCurrentRowNum();
    ReadSheet getCurrentSheet();
    ExcelTypeEnum getExcelType();
}

Event System

Data Conversion

Type conversion system for transforming between Java objects and Excel cell values.

// Core converter interface
public interface Converter<T> {
    Class<?> supportJavaTypeKey();
    CellDataTypeEnum supportExcelTypeKey();
    T convertToJavaData(ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration);
    WriteCellData<?> convertToExcelData(T value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration);
}

Data Conversion

Exception Handling

Comprehensive exception hierarchy for different error scenarios during Excel processing.

// Base exceptions
public class ExcelRuntimeException extends RuntimeException;
public class ExcelAnalysisException extends ExcelRuntimeException;
public class ExcelGenerateException extends ExcelRuntimeException;

// Data conversion exceptions
public class ExcelDataConvertException extends ExcelAnalysisException;
public class ExcelWriteDataConvertException extends ExcelGenerateException;

// Flow control exceptions
public class ExcelAnalysisStopException extends ExcelAnalysisException;
public class ExcelAnalysisStopSheetException extends ExcelAnalysisStopException;

Exception Handling

Common Types

// File format enum
public enum ExcelTypeEnum {
    XLS, XLSX, CSV
}

// Cell data type enum
public enum CellDataTypeEnum {
    STRING, NUMBER, BOOLEAN, DATE, EMPTY, ERROR, IMAGE, FORMULA, 
    RICH_TEXT_STRING, DIRECT_STRING
}

// Extra information types
public enum CellExtraTypeEnum {
    COMMENT, HYPERLINK, MERGE
}

// Core data structures
public class ReadCellData<T> {
    private T data;
    private String formula;
    private CellDataTypeEnum type;
    // Additional properties...
}

public class WriteCellData<T> {
    private T data;
    private String formula;
    private CellDataTypeEnum type;
    // Additional properties...
}

// Configuration classes
public class ReadSheet {
    private Integer sheetNo;
    private String sheetName;
    private Class<?> head;
    private Integer headRowNumber;
    // Additional properties...
}

public class WriteSheet {
    private Integer sheetNo;
    private String sheetName;
    private Class<?> head;
    // Additional properties...
}