0
# EasyExcel
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: com.alibaba:easyexcel
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.alibaba</groupId>
13
    <artifactId>easyexcel</artifactId>
14
    <version>4.0.3</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.alibaba.excel.EasyExcel;
22
import com.alibaba.excel.read.listener.ReadListener;
23
import com.alibaba.excel.context.AnalysisContext;
24
```
25

26
For annotation-based mapping:
27
```java
28
import com.alibaba.excel.annotation.ExcelProperty;
29
import com.alibaba.excel.annotation.ExcelIgnore;
30
import com.alibaba.excel.annotation.format.DateTimeFormat;
31
import com.alibaba.excel.annotation.format.NumberFormat;
32
```
33

34
## Basic Usage
35

36
### Simple Reading
37
```java
38
import com.alibaba.excel.EasyExcel;
39

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

46
// Event-driven reading for large files
47
EasyExcel.read("large-file.xlsx", UserData.class, new UserDataListener())
48
    .sheet()
49
    .doRead();
50
```
51

52
### Simple Writing
53
```java
54
import com.alibaba.excel.EasyExcel;
55

56
// Write data to Excel file
57
List<UserData> dataList = getUserData();
58
EasyExcel.write("output.xlsx", UserData.class)
59
    .sheet("Users")
60
    .doWrite(dataList);
61
```
62

63
### Basic Data Model
64
```java
65
import com.alibaba.excel.annotation.ExcelProperty;
66

67
public class UserData {
68
    @ExcelProperty("Name")
69
    private String name;
70
    
71
    @ExcelProperty("Age")
72
    private Integer age;
73
    
74
    @ExcelProperty("Email")
75
    private String email;
76
    
77
    // Getters and setters...
78
}
79
```
80

81
## Architecture
82

83
EasyExcel is built around several key components:
84

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

92
## Capabilities
93

94
### Reading Operations
95

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

98
```java { .api }
99
// Main entry points
100
public static ExcelReaderBuilder read();
101
public static ExcelReaderBuilder read(File file);
102
public static ExcelReaderBuilder read(String pathName);
103
public static ExcelReaderBuilder read(InputStream inputStream);
104

105
// Reader builder configuration
106
public class ExcelReaderBuilder {
107
    public ExcelReaderBuilder head(Class<?> head);
108
    public ExcelReaderBuilder registerReadListener(ReadListener<?> readListener);
109
    public ExcelReaderBuilder charset(Charset charset);
110
    public ExcelReaderBuilder password(String password);
111
    public ExcelReaderBuilder ignoreEmptyRow(Boolean ignoreEmptyRow);
112
    public ExcelReader build();
113
    public List<Object> doReadAllSync();
114
    public ExcelReaderSheetBuilder sheet();
115
}
116
```
117

118
[Reading Operations](./reading-operations.md)
119

120
### Writing Operations
121

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

124
```java { .api }
125
// Main entry points  
126
public static ExcelWriterBuilder write();
127
public static ExcelWriterBuilder write(File file);
128
public static ExcelWriterBuilder write(String pathName);
129
public static ExcelWriterBuilder write(OutputStream outputStream);
130

131
// Writer builder configuration
132
public class ExcelWriterBuilder {
133
    public ExcelWriterBuilder head(Class<?> head);
134
    public ExcelWriterBuilder charset(Charset charset);
135
    public ExcelWriterBuilder password(String password);
136
    public ExcelWriterBuilder withTemplate(File templateFile);
137
    public ExcelWriter build();
138
    public ExcelWriterSheetBuilder sheet();
139
}
140
```
141

142
[Writing Operations](./writing-operations.md)
143

144
### Annotations and Mapping
145

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

148
```java { .api }
149
// Core mapping annotations
150
@ExcelProperty(value = "Column Name", index = 0, order = 1)
151
@ExcelIgnore
152
@ExcelIgnoreUnannotated
153

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

158
// Style annotations
159
@ColumnWidth(15)
160
@HeadStyle(fillForegroundColor = 40)
161
@ContentStyle(dataFormat = 49)
162
@HeadRowHeight(20)
163
@ContentRowHeight(18)
164
```
165

166
[Annotations and Mapping](./annotations-and-mapping.md)
167

168
### Event System
169

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

172
```java { .api }
173
// Core listener interface
174
public interface ReadListener<T> {
175
    void invoke(T data, AnalysisContext context);
176
    void doAfterAllAnalysed(AnalysisContext context);
177
    void onException(Exception exception, AnalysisContext context);
178
    void invokeHead(Map<Integer, ReadCellData<?>> headMap, AnalysisContext context);
179
}
180

181
// Context for accessing metadata
182
public interface AnalysisContext {
183
    Object getCurrentRowAnalysisResult();
184
    Integer getCurrentRowNum();
185
    ReadSheet getCurrentSheet();
186
    ExcelTypeEnum getExcelType();
187
}
188
```
189

190
[Event System](./event-system.md)
191

192
### Data Conversion
193

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

196
```java { .api }
197
// Core converter interface
198
public interface Converter<T> {
199
    Class<?> supportJavaTypeKey();
200
    CellDataTypeEnum supportExcelTypeKey();
201
    T convertToJavaData(ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration);
202
    WriteCellData<?> convertToExcelData(T value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration);
203
}
204
```
205

206
[Data Conversion](./data-conversion.md)
207

208
### Exception Handling
209

210
Comprehensive exception hierarchy for different error scenarios during Excel processing.
211

212
```java { .api }
213
// Base exceptions
214
public class ExcelRuntimeException extends RuntimeException;
215
public class ExcelAnalysisException extends ExcelRuntimeException;
216
public class ExcelGenerateException extends ExcelRuntimeException;
217

218
// Data conversion exceptions
219
public class ExcelDataConvertException extends ExcelAnalysisException;
220
public class ExcelWriteDataConvertException extends ExcelGenerateException;
221

222
// Flow control exceptions
223
public class ExcelAnalysisStopException extends ExcelAnalysisException;
224
public class ExcelAnalysisStopSheetException extends ExcelAnalysisStopException;
225
```
226

227
[Exception Handling](./exception-handling.md)
228

229
## Common Types
230

231
```java { .api }
232
// File format enum
233
public enum ExcelTypeEnum {
234
    XLS, XLSX, CSV
235
}
236

237
// Cell data type enum
238
public enum CellDataTypeEnum {
239
    STRING, NUMBER, BOOLEAN, DATE, EMPTY, ERROR, IMAGE, FORMULA, 
240
    RICH_TEXT_STRING, DIRECT_STRING
241
}
242

243
// Extra information types
244
public enum CellExtraTypeEnum {
245
    COMMENT, HYPERLINK, MERGE
246
}
247

248
// Core data structures
249
public class ReadCellData<T> {
250
    private T data;
251
    private String formula;
252
    private CellDataTypeEnum type;
253
    // Additional properties...
254
}
255

256
public class WriteCellData<T> {
257
    private T data;
258
    private String formula;
259
    private CellDataTypeEnum type;
260
    // Additional properties...
261
}
262

263
// Configuration classes
264
public class ReadSheet {
265
    private Integer sheetNo;
266
    private String sheetName;
267
    private Class<?> head;
268
    private Integer headRowNumber;
269
    // Additional properties...
270
}
271

272
public class WriteSheet {
273
    private Integer sheetNo;
274
    private String sheetName;
275
    private Class<?> head;
276
    // Additional properties...
277
}
278
```