[Proposal] Fesod Examples Module Refactoring #725
Description
Fesod Examples Module Refactoring Proposal
1. Summary
This proposal outlines a plan to refactor the fesod-examples module by:
- Moving example code from
src/test/javatosrc/main/java(following Apache Spark/Flink patterns) - Cleaning up temporary/issue-specific test classes
- Establishing clear guidelines for example code organization
2. Background & Motivation
2.1 Current State
The fesod-examples module currently contains all code under src/test/java:
fesod-examples/src/test/java/org/apache/fesod/sheet/
├── demo/ # Well-structured examples for documentation
│ ├── fill/ # 2 files - Fill functionality examples
│ ├── migration/ # Empty
│ ├── rare/ # 1 file - Rare use cases
│ ├── read/ # 23 files - Read examples with data classes & listeners
│ ├── web/ # 6 files - Spring Boot web integration examples
│ └── write/ # 19 files - Write examples with handlers & styles
├── temp/ # Temporary/experimental tests (~70+ files)
│ ├── bug/ # Bug reproduction tests
│ ├── cache/ # Cache related tests
│ ├── csv/ # CSV format tests
│ ├── issue1662/ # Issue-specific tests
│ ├── issue1663/ # Issue-specific tests
│ ├── issue2319/ # Issue-specific tests
│ ├── issue2443/ # Issue-specific tests
│ ├── issue406/ # Issue-specific tests
│ ├── poi/ # POI compatibility tests
│ ├── large/ # Large file tests
│ └── ... # Other experimental/temp tests
└── util/ # 2 files - Test utilities
2.2 Best Practices
- Examples are in
src/main/javaas runnable programs - Package:
org.apache.spark.examples.* - Each example has a
main()method - Used for documentation and user learning
- Tests are separate integration tests
- Examples are in
src/main/java - Package:
org.apache.flink.streaming.examples.* - Examples are actual runnable programs
- Integration tests validate examples via
src/test/java
3. Proposed Changes
3.1 Phase 1: Restructure to Production Layout
Move demo examples to src/main/java:
fesod-examples/src/main/java/org/apache/fesod/sheet/examples/
├── read/
│ ├── SimpleReadExample.java # Basic reading
│ ├── ConverterReadExample.java # Custom converters
│ ├── IndexOrNameReadExample.java # Column mapping
│ ├── NoModelReadExample.java # Map-based reading
│ ├── ExtraDataReadExample.java # Comments/hyperlinks
│ └── data/ # Data classes
│ ├── DemoData.java
│ └── ...
├── write/
│ ├── SimpleWriteExample.java # Basic writing
│ ├── StyleWriteExample.java # Custom styles
│ ├── ImageWriteExample.java # Image handling
│ ├── MergeWriteExample.java # Cell merging
│ └── data/ # Data classes
│ ├── DemoData.java
│ └── ...
├── fill/
│ ├── SimpleFillExample.java # Template filling
│ └── data/
│ └── FillData.java
└── web/
├── WebExcelExample.java # Spring Boot integration
└── data/
├── DownloadData.java
└── UploadData.java
Keep integration tests in src/test/java:
fesod-examples/src/test/java/org/apache/fesod/sheet/examples/
├── ReadExamplesIT.java # Integration tests for read examples
├── WriteExamplesIT.java # Integration tests for write examples
├── FillExamplesIT.java # Integration tests for fill examples
└── WebExamplesIT.java # Integration tests for web examples
3.2 Phase 2: Handle Temp Directory Classes
Remove all classes in the temp/ directory as they are:
- Bug reproduction tests for already-fixed issues
- Issue-specific tests no longer relevant
- Experimental code not part of standard examples
- Cluttering the codebase and making maintenance harder
These should be either:
- Migrated to fesod core unit tests if they validate important functionality
- Removed completely if they are duplicates or no longer relevant