Skip to content

Commit f56069d

Browse files
GOODBOY008GOODBOY008
committed
refactor: deprecate EasyExcel, FastExcel, and FastExcelFactory classes with migration guidance to FesodSheet
1 parent 2a945c0 commit f56069d

File tree

5 files changed

+242
-5
lines changed

5 files changed

+242
-5
lines changed

‎fesod/src/main/java/org/apache/fesod/sheet/EasyExcel.java‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,52 @@
2020
package org.apache.fesod.sheet;
2121

2222
/**
23-
* This is actually {@link FesodSheetFactory}, and short names look better.
23+
* Legacy alias for {@link FesodSheetFactory}.
24+
*
25+
* <p><strong>DEPRECATED:</strong> This class has been deprecated as part of the project's transition
26+
* to the Apache Fesod branding. Users should migrate to {@link FesodSheet} or {@link FesodSheetFactory}
27+
* for all new development.
28+
*
29+
* <h3>Migration Guide</h3>
30+
* <p>Replace all occurrences of {@code EasyExcel} with {@code FesodSheet} in your codebase:
31+
*
32+
* <table border="1">
33+
* <caption>Migration Examples</caption>
34+
* <tr>
35+
* <th>Old Code (Deprecated)</th>
36+
* <th>New Code (Recommended)</th>
37+
* </tr>
38+
* <tr>
39+
* <td>{@code EasyExcel.read(file, DemoData.class, listener)}</td>
40+
* <td>{@code FesodSheet.read(file, DemoData.class, listener)}</td>
41+
* </tr>
42+
* <tr>
43+
* <td>{@code EasyExcel.write(file, DemoData.class)}</td>
44+
* <td>{@code FesodSheet.write(file, DemoData.class)}</td>
45+
* </tr>
46+
* <tr>
47+
* <td>{@code EasyExcel.readSheet(0)}</td>
48+
* <td>{@code FesodSheet.readSheet(0)}</td>
49+
* </tr>
50+
* <tr>
51+
* <td>{@code EasyExcel.writerSheet("Sheet1")}</td>
52+
* <td>{@code FesodSheet.writerSheet("Sheet1")}</td>
53+
* </tr>
54+
* </table>
55+
*
56+
* <h3>Why Deprecated?</h3>
57+
* <p>This class was originally named "EasyExcel" but has been superseded by "FesodSheet"
58+
* to align with Apache Fesod's official branding and naming conventions. The functionality
59+
* remains identical; only the class name has changed.
60+
*
61+
* <h3>Removal Timeline</h3>
62+
* <p>This class is marked for removal in a future major version. All functionality is
63+
* available in {@link FesodSheet} and {@link FesodSheetFactory}.
64+
*
65+
* @deprecated Since version 1.0.0. Use {@link FesodSheet} or {@link FesodSheetFactory} instead.
66+
* This class will be removed in a future major release.
67+
* @see FesodSheet
68+
* @see FesodSheetFactory
2469
*/
2570
@Deprecated
2671
public class EasyExcel extends FesodSheetFactory {}

‎fesod/src/main/java/org/apache/fesod/sheet/FastExcel.java‎

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,64 @@
2020
package org.apache.fesod.sheet;
2121

2222
/**
23-
* This is actually {@link FastExcelFactory}, and short names look better.
23+
* Legacy short alias for {@link FesodSheetFactory}.
2424
*
25+
* <p><strong>DEPRECATED:</strong> This class has been deprecated as part of the project's evolution
26+
* from "FastExcel" to "Apache Fesod". Users should migrate to {@link FesodSheet} or
27+
* {@link FesodSheetFactory} for all new development.
28+
*
29+
* <h3>Migration Guide</h3>
30+
* <p>Replace all occurrences of {@code FastExcel} with {@code FesodSheet} in your codebase:
31+
*
32+
* <table border="1">
33+
* <caption>Migration Examples</caption>
34+
* <tr>
35+
* <th>Old Code (Deprecated)</th>
36+
* <th>New Code (Recommended)</th>
37+
* </tr>
38+
* <tr>
39+
* <td>{@code FastExcel.read("data.xlsx", DemoData.class, listener)}</td>
40+
* <td>{@code FesodSheet.read("data.xlsx", DemoData.class, listener)}</td>
41+
* </tr>
42+
* <tr>
43+
* <td>{@code FastExcel.write("output.xlsx", DemoData.class)}</td>
44+
* <td>{@code FesodSheet.write("output.xlsx", DemoData.class)}</td>
45+
* </tr>
46+
* <tr>
47+
* <td>{@code FastExcel.readSheet(0)}</td>
48+
* <td>{@code FesodSheet.readSheet(0)}</td>
49+
* </tr>
50+
* <tr>
51+
* <td>{@code FastExcel.writerSheet("MySheet")}</td>
52+
* <td>{@code FesodSheet.writerSheet("MySheet")}</td>
53+
* </tr>
54+
* </table>
55+
*
56+
* <h3>Why Deprecated?</h3>
57+
* <p>This class was originally named "FastExcel" to provide a short, memorable entry point
58+
* for the library. However, following the project's acceptance into the Apache Software Foundation
59+
* as Apache Fesod (incubating), it has been superseded by "FesodSheet" to align with the official
60+
* project branding. The functionality remains identical; only the class name has changed.
61+
*
62+
* <h3>Historical Context</h3>
63+
* <p>The name "FastExcel" emphasized the library's high-performance characteristics and ease of use.
64+
* The Apache Fesod name (Fast Easy Spreadsheet and Other Documents) retains this heritage while
65+
* fitting Apache naming conventions.
66+
*
67+
* <h3>Relationship with FastExcelFactory</h3>
68+
* <p>Both {@code FastExcel} and {@link FastExcelFactory} are deprecated aliases pointing to
69+
* the same underlying implementation. {@code FastExcel} was the short, convenient alias while
70+
* {@code FastExcelFactory} used the explicit "Factory" suffix.
71+
*
72+
* <h3>Removal Timeline</h3>
73+
* <p>This class is marked for removal in a future major version. All functionality is
74+
* available in {@link FesodSheet} and {@link FesodSheetFactory}.
75+
*
76+
* @deprecated Since version 1.0.0. Use {@link FesodSheet} or {@link FesodSheetFactory} instead.
77+
* This class will be removed in a future major release.
78+
* @see FesodSheet
79+
* @see FesodSheetFactory
80+
* @see FastExcelFactory
2581
*/
2682
@Deprecated
2783
public class FastExcel extends FesodSheetFactory {}

‎fesod/src/main/java/org/apache/fesod/sheet/FastExcelFactory.java‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,58 @@
2020
package org.apache.fesod.sheet;
2121

2222
/**
23-
* Reader and writer factory class
23+
* Legacy factory class alias for {@link FesodSheetFactory}.
24+
*
25+
* <p><strong>DEPRECATED:</strong> This class has been deprecated as part of the project's evolution
26+
* from "FastExcel" to "Apache Fesod". Users should migrate to {@link FesodSheet} or
27+
* {@link FesodSheetFactory} for all new development.
28+
*
29+
* <h3>Migration Guide</h3>
30+
* <p>Replace all occurrences of {@code FastExcelFactory} with {@code FesodSheet} in your codebase:
31+
*
32+
* <table border="1">
33+
* <caption>Migration Examples</caption>
34+
* <tr>
35+
* <th>Old Code (Deprecated)</th>
36+
* <th>New Code (Recommended)</th>
37+
* </tr>
38+
* <tr>
39+
* <td>{@code FastExcelFactory.read(inputStream, DemoData.class, listener)}</td>
40+
* <td>{@code FesodSheet.read(inputStream, DemoData.class, listener)}</td>
41+
* </tr>
42+
* <tr>
43+
* <td>{@code FastExcelFactory.write(outputStream, DemoData.class)}</td>
44+
* <td>{@code FesodSheet.write(outputStream, DemoData.class)}</td>
45+
* </tr>
46+
* <tr>
47+
* <td>{@code FastExcelFactory.readSheet(0, "Sheet1")}</td>
48+
* <td>{@code FesodSheet.readSheet(0, "Sheet1")}</td>
49+
* </tr>
50+
* <tr>
51+
* <td>{@code FastExcelFactory.writerTable(0)}</td>
52+
* <td>{@code FesodSheet.writerTable(0)}</td>
53+
* </tr>
54+
* </table>
55+
*
56+
* <h3>Why Deprecated?</h3>
57+
* <p>This class was part of the original "FastExcel" branding but has been superseded by
58+
* "FesodSheet" following the project's acceptance into the Apache Software Foundation as
59+
* Apache Fesod (incubating). The functionality remains identical; only the class name has changed.
60+
*
61+
* <h3>Relationship with FastExcel</h3>
62+
* <p>Both {@link FastExcel} and {@code FastExcelFactory} are deprecated aliases pointing to
63+
* the same underlying implementation. {@code FastExcel} was the short alias while
64+
* {@code FastExcelFactory} used the explicit "Factory" suffix.
65+
*
66+
* <h3>Removal Timeline</h3>
67+
* <p>This class is marked for removal in a future major version. All functionality is
68+
* available in {@link FesodSheet} and {@link FesodSheetFactory}.
69+
*
70+
* @deprecated Since version 1.0.0. Use {@link FesodSheet} or {@link FesodSheetFactory} instead.
71+
* This class will be removed in a future major release.
72+
* @see FesodSheet
73+
* @see FesodSheetFactory
74+
* @see FastExcel
2475
*/
2576
@Deprecated
2677
public class FastExcelFactory extends FesodSheetFactory {}

‎fesod/src/main/java/org/apache/fesod/sheet/FesodSheet.java‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,39 @@
2020
package org.apache.fesod.sheet;
2121

2222
/**
23-
* This is actually {@link FesodSheetFactory}, and short names look better.
23+
* Convenient alias for {@link FesodSheetFactory} with a shorter, more readable name.
24+
*
25+
* <p>This class extends {@link FesodSheetFactory} without adding any additional functionality,
26+
* serving purely as a naming convenience. It provides the same fluent API for creating Excel
27+
* readers and writers, making code more concise and expressive.
28+
*
29+
* <p><strong>Recommended Usage:</strong> This is the preferred entry point for Fesod operations
30+
* due to its concise naming. All static methods from {@link FesodSheetFactory} are available.
31+
*
32+
* <h3>Quick Start Examples</h3>
33+
* <pre>{@code
34+
* // Reading Excel file
35+
* FesodSheet.read("data.xlsx", UserData.class, new UserDataListener())
36+
* .sheet()
37+
* .doRead();
38+
*
39+
* // Writing Excel file
40+
* FesodSheet.write("output.xlsx", UserData.class)
41+
* .sheet("Users")
42+
* .doWrite(userList);
43+
* }</pre>
44+
*
45+
* <h3>Comparison with Other Entry Points</h3>
46+
* <ul>
47+
* <li>{@code FesodSheet} - <strong>Recommended</strong>: Short, clean naming</li>
48+
* <li>{@code FesodSheetFactory} - Explicit factory naming, same functionality</li>
49+
* <li>{@code EasyExcel} - <strong>Deprecated</strong>: Legacy alias, use FesodSheet instead</li>
50+
* <li>{@code FastExcel/FastExcelFactory} - <strong>Deprecated</strong>: Legacy aliases, use FesodSheet instead</li>
51+
* </ul>
52+
*
53+
* @see FesodSheetFactory
54+
* @see ExcelReader
55+
* @see ExcelWriter
56+
* @since 1.0.0
2457
*/
2558
public class FesodSheet extends FesodSheetFactory {}

‎fesod/src/main/java/org/apache/fesod/sheet/FesodSheetFactory.java‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,59 @@
3030
import org.apache.fesod.sheet.write.builder.ExcelWriterTableBuilder;
3131

3232
/**
33-
* Reader and writer factory class
33+
* Factory class providing static methods for creating Excel readers and writers.
34+
*
35+
* <p>This class serves as the primary entry point for the Fesod library, offering a fluent API
36+
* for both reading and writing Excel files. It implements the Facade pattern to simplify Excel
37+
* operations by providing a unified interface to the underlying builder components.
38+
*
39+
* <h3>Key Features</h3>
40+
* <ul>
41+
* <li>Supports multiple input/output sources: File, String path, InputStream, OutputStream</li>
42+
* <li>Provides builder pattern for flexible configuration</li>
43+
* <li>Supports annotation-driven mapping via {@code @ExcelProperty}</li>
44+
* <li>Handles both .xls (Excel 97-2003) and .xlsx (Excel 2007+) formats</li>
45+
* <li>Enables stream-based processing for memory efficiency</li>
46+
* </ul>
47+
*
48+
* <h3>Reading Examples</h3>
49+
* <pre>{@code
50+
* // Simple read with listener
51+
* FesodSheetFactory.read("demo.xlsx", DemoData.class, new DemoDataListener())
52+
* .sheet()
53+
* .doRead();
54+
*
55+
* // Advanced read with custom configuration
56+
* try (ExcelReader excelReader = FesodSheetFactory.read(file)
57+
* .headRowNumber(1)
58+
* .ignoreEmptyRow(true)
59+
* .build()) {
60+
* ReadSheet readSheet = FesodSheetFactory.readSheet(0).build();
61+
* excelReader.read(readSheet);
62+
* }
63+
* }</pre>
64+
*
65+
* <h3>Writing Examples</h3>
66+
* <pre>{@code
67+
* // Simple write
68+
* FesodSheetFactory.write("output.xlsx", DemoData.class)
69+
* .sheet("Sheet1")
70+
* .doWrite(dataList);
71+
*
72+
* // Advanced write with custom configuration
73+
* try (ExcelWriter excelWriter = FesodSheetFactory.write(outputStream)
74+
* .build()) {
75+
* WriteSheet writeSheet = FesodSheetFactory.writerSheet(0, "Template").build();
76+
* excelWriter.write(dataList, writeSheet);
77+
* }
78+
* }</pre>
79+
*
80+
* @see FesodSheet
81+
* @see ExcelReader
82+
* @see ExcelWriter
83+
* @see org.apache.fesod.sheet.read.builder.ExcelReaderBuilder
84+
* @see org.apache.fesod.sheet.write.builder.ExcelWriterBuilder
85+
* @since 1.0.0
3486
*/
3587
public class FesodSheetFactory {
3688

0 commit comments

Comments
 (0)