0
# Reading Operations
1

2
Core functionality for reading Excel files with memory-efficient streaming and event-driven processing. EasyExcel supports XLS, XLSX, and CSV formats with configurable parsing options.
3

4
## Capabilities
5

6
### Main Read Entry Points
7

8
Factory methods for creating Excel readers with various input sources.
9

10
```java { .api }
11
/**
12
 * Create a reader builder without specifying input source
13
 * @return ExcelReaderBuilder for configuration
14
 */
15
public static ExcelReaderBuilder read();
16

17
/**
18
 * Create a reader builder for a file
19
 * @param file File to read
20
 * @return ExcelReaderBuilder for configuration
21
 */
22
public static ExcelReaderBuilder read(File file);
23

24
/**
25
 * Create a reader builder for a file path
26
 * @param pathName Path to the file to read
27
 * @return ExcelReaderBuilder for configuration
28
 */
29
public static ExcelReaderBuilder read(String pathName);
30

31
/**
32
 * Create a reader builder for an input stream
33
 * @param inputStream InputStream to read from
34
 * @return ExcelReaderBuilder for configuration
35
 */
36
public static ExcelReaderBuilder read(InputStream inputStream);
37

38
/**
39
 * Create a reader builder with listener
40
 * @param file File to read
41
 * @param readListener Listener to handle read events
42
 * @return ExcelReaderBuilder for configuration
43
 */
44
public static ExcelReaderBuilder read(File file, ReadListener<?> readListener);
45

46
/**
47
 * Create a reader builder with head class and listener
48
 * @param file File to read
49
 * @param head Class for data mapping
50
 * @param readListener Listener to handle read events
51
 * @return ExcelReaderBuilder for configuration
52
 */
53
public static ExcelReaderBuilder read(File file, Class<?> head, ReadListener<?> readListener);
54
```
55

56
### ExcelReaderBuilder Configuration
57

58
Fluent builder for configuring Excel reader options before execution.
59

60
```java { .api }
61
public class ExcelReaderBuilder {
62
    /**
63
     * Set the input source file
64
     * @param file File to read
65
     * @return this builder
66
     */
67
    public ExcelReaderBuilder file(File file);
68
    
69
    /**
70
     * Set the input source by path
71
     * @param pathName Path to file
72
     * @return this builder
73
     */
74
    public ExcelReaderBuilder file(String pathName);
75
    
76
    /**
77
     * Set the input source stream
78
     * @param inputStream InputStream to read
79
     * @return this builder
80
     */
81
    public ExcelReaderBuilder file(InputStream inputStream);
82
    
83
    /**
84
     * Set the head class for data mapping
85
     * @param head Class with ExcelProperty annotations
86
     * @return this builder
87
     */
88
    public ExcelReaderBuilder head(Class<?> head);
89
    
90
    /**
91
     * Register a read listener for event handling
92
     * @param readListener Listener to handle read events
93
     * @return this builder
94
     */
95
    public ExcelReaderBuilder registerReadListener(ReadListener<?> readListener);
96
    
97
    /**
98
     * Set character encoding for CSV files
99
     * @param charset Character encoding
100
     * @return this builder
101
     */
102
    public ExcelReaderBuilder charset(Charset charset);
103
    
104
    /**
105
     * Set password for encrypted files
106
     * @param password File password
107
     * @return this builder
108
     */
109
    public ExcelReaderBuilder password(String password);
110
    
111
    /**
112
     * Configure whether to ignore empty rows
113
     * @param ignoreEmptyRow true to ignore empty rows
114
     * @return this builder
115
     */
116
    public ExcelReaderBuilder ignoreEmptyRow(Boolean ignoreEmptyRow);
117
    
118
    /**
119
     * Configure reading of extra information
120
     * @param cellExtraTypeEnum Type of extra info (COMMENT, HYPERLINK, MERGE)
121
     * @return this builder
122
     */
123
    public ExcelReaderBuilder extraRead(CellExtraTypeEnum cellExtraTypeEnum);
124
    
125
    /**
126
     * Build the ExcelReader instance
127
     * @return ExcelReader for manual control
128
     */
129
    public ExcelReader build();
130
    
131
    /**
132
     * Read all sheets and return data synchronously
133
     * @return List of all data objects
134
     */
135
    public List<Object> doReadAllSync();
136
    
137
    /**
138
     * Execute reading of all sheets with registered listeners
139
     */
140
    public void doReadAll();
141
    
142
    /**
143
     * Create a sheet builder for specific sheet configuration
144
     * @return ExcelReaderSheetBuilder
145
     */
146
    public ExcelReaderSheetBuilder sheet();
147
    
148
    /**
149
     * Create a sheet builder for specific sheet
150
     * @param sheetNo Sheet index (0-based)
151
     * @return ExcelReaderSheetBuilder
152
     */
153
    public ExcelReaderSheetBuilder sheet(Integer sheetNo);
154
    
155
    /**
156
     * Create a sheet builder for named sheet
157
     * @param sheetName Sheet name
158
     * @return ExcelReaderSheetBuilder
159
     */
160
    public ExcelReaderSheetBuilder sheet(String sheetName);
161
}
162
```
163

164
### ExcelReaderSheetBuilder Configuration
165

166
Configure specific sheet reading parameters.
167

168
```java { .api }
169
public class ExcelReaderSheetBuilder {
170
    /**
171
     * Set sheet index to read
172
     * @param sheetNo Sheet index (0-based)
173
     * @return this builder
174
     */
175
    public ExcelReaderSheetBuilder sheetNo(Integer sheetNo);
176
    
177
    /**
178
     * Set sheet name to read
179
     * @param sheetName Sheet name
180
     * @return this builder
181
     */
182
    public ExcelReaderSheetBuilder sheetName(String sheetName);
183
    
184
    /**
185
     * Set head class for this sheet
186
     * @param head Class with annotations
187
     * @return this builder
188
     */
189
    public ExcelReaderSheetBuilder head(Class<?> head);
190
    
191
    /**
192
     * Set header row number
193
     * @param headRowNumber Row number containing headers (0-based)
194
     * @return this builder
195
     */
196
    public ExcelReaderSheetBuilder headRowNumber(Integer headRowNumber);
197
    
198
    /**
199
     * Register listener for this sheet
200
     * @param readListener Listener for handling events
201
     * @return this builder
202
     */
203
    public ExcelReaderSheetBuilder registerReadListener(ReadListener<?> readListener);
204
    
205
    /**
206
     * Execute reading for this sheet
207
     */
208
    public void doRead();
209
    
210
    /**
211
     * Execute synchronous reading and return data
212
     * @return List of data objects from this sheet
213
     */
214
    public List<Object> doReadSync();
215
}
216
```
217

218
### ExcelReader Manual Control
219

220
Direct control over the reading process for advanced scenarios.
221

222
```java { .api }
223
public class ExcelReader implements Closeable {
224
    /**
225
     * Read all sheets using registered listeners
226
     * @return ExcelReader for chaining
227
     */
228
    public ExcelReader readAll();
229
    
230
    /**
231
     * Read specific sheets
232
     * @param readSheets Sheets to read
233
     * @return ExcelReader for chaining
234
     */
235
    public ExcelReader read(ReadSheet... readSheets);
236
    
237
    /**
238
     * Get the analysis context
239
     * @return AnalysisContext with metadata
240
     */
241
    public AnalysisContext analysisContext();
242
    
243
    /**
244
     * Finish reading and cleanup resources
245
     */
246
    public void finish();
247
    
248
    /**
249
     * Close the reader and cleanup resources
250
     */
251
    public void close();
252
}
253
```
254

255
### Sheet Factory Methods
256

257
Static factory methods for creating sheet configurations.
258

259
```java { .api }
260
/**
261
 * Create a default sheet configuration
262
 * @return ExcelReaderSheetBuilder
263
 */
264
public static ExcelReaderSheetBuilder readSheet();
265

266
/**
267
 * Create a sheet configuration by index
268
 * @param sheetNo Sheet index (0-based)
269
 * @return ExcelReaderSheetBuilder
270
 */
271
public static ExcelReaderSheetBuilder readSheet(Integer sheetNo);
272

273
/**
274
 * Create a sheet configuration by name
275
 * @param sheetName Sheet name
276
 * @return ExcelReaderSheetBuilder
277
 */
278
public static ExcelReaderSheetBuilder readSheet(String sheetName);
279

280
/**
281
 * Create a sheet configuration with index and name
282
 * @param sheetNo Sheet index (0-based)
283
 * @param sheetName Sheet name
284
 * @return ExcelReaderSheetBuilder
285
 */
286
public static ExcelReaderSheetBuilder readSheet(Integer sheetNo, String sheetName);
287
```
288

289
## Usage Examples
290

291
### Basic Synchronous Reading
292
```java
293
import com.alibaba.excel.EasyExcel;
294
import java.util.List;
295

296
// Simple reading with data model
297
List<UserData> users = EasyExcel.read("users.xlsx")
298
    .head(UserData.class)
299
    .sheet()
300
    .doReadSync();
301

302
// Reading specific sheet by index
303
List<UserData> users = EasyExcel.read("workbook.xlsx")
304
    .head(UserData.class)
305
    .sheet(1) // Second sheet
306
    .doReadSync();
307

308
// Reading specific sheet by name
309
List<UserData> users = EasyExcel.read("workbook.xlsx")
310
    .head(UserData.class)
311
    .sheet("UserData")
312
    .doReadSync();
313
```
314

315
### Event-Driven Reading for Large Files
316
```java
317
import com.alibaba.excel.EasyExcel;
318
import com.alibaba.excel.read.listener.ReadListener;
319

320
// Create custom listener
321
public class UserDataListener implements ReadListener<UserData> {
322
    @Override
323
    public void invoke(UserData data, AnalysisContext context) {
324
        // Process each row
325
        System.out.println("Row " + context.getCurrentRowNum() + ": " + data);
326
    }
327
    
328
    @Override
329
    public void doAfterAllAnalysed(AnalysisContext context) {
330
        System.out.println("Reading completed");
331
    }
332
}
333

334
// Use event-driven reading
335
EasyExcel.read("large-file.xlsx", UserData.class, new UserDataListener())
336
    .sheet()
337
    .doRead();
338
```
339

340
### Advanced Configuration
341
```java
342
import com.alibaba.excel.EasyExcel;
343
import com.alibaba.excel.enums.CellExtraTypeEnum;
344
import java.nio.charset.StandardCharsets;
345

346
// Advanced reading configuration
347
EasyExcel.read("data.xlsx")
348
    .head(UserData.class)
349
    .charset(StandardCharsets.UTF_8) // For CSV files
350
    .password("secret123") // For encrypted files
351
    .ignoreEmptyRow(false) // Include empty rows
352
    .extraRead(CellExtraTypeEnum.COMMENT) // Read comments
353
    .registerReadListener(new UserDataListener())
354
    .sheet(0)
355
    .headRowNumber(2) // Headers on row 3 (0-based)
356
    .doRead();
357
```
358

359
### Manual Reader Control
360
```java
361
import com.alibaba.excel.EasyExcel;
362
import com.alibaba.excel.ExcelReader;
363
import com.alibaba.excel.read.metadata.ReadSheet;
364

365
// Manual control over reading process
366
try (ExcelReader excelReader = EasyExcel.read("workbook.xlsx")
367
        .head(UserData.class)
368
        .registerReadListener(new UserDataListener())
369
        .build()) {
370
    
371
    // Read specific sheets
372
    ReadSheet sheet1 = EasyExcel.readSheet(0).build();
373
    ReadSheet sheet2 = EasyExcel.readSheet(1).build();
374
    
375
    excelReader.read(sheet1, sheet2);
376
    
377
    // Access context information
378
    AnalysisContext context = excelReader.analysisContext();
379
    System.out.println("Current sheet: " + context.getCurrentSheet().getSheetName());
380
}
381
```
382

383
### Reading Without Data Model
384
```java
385
import com.alibaba.excel.EasyExcel;
386
import com.alibaba.excel.read.listener.ReadListener;
387
import java.util.Map;
388

389
// Reading as Map when no data model is available
390
public class MapDataListener implements ReadListener<Map<Integer, String>> {
391
    @Override
392
    public void invoke(Map<Integer, String> data, AnalysisContext context) {
393
        System.out.println("Row data: " + data);
394
    }
395
    
396
    @Override
397
    public void doAfterAllAnalysed(AnalysisContext context) {
398
        System.out.println("Analysis completed");
399
    }
400
}
401

402
// Read without head class
403
EasyExcel.read("data.xlsx", new MapDataListener())
404
    .sheet()
405
    .doRead();
406
```