Abstract

This proposal suggests restructuring Apache Fesod from a monolithic module into a multi-module Maven project, separating functionality by Excel format (CSV, XLS, XLSX). This change will improve modularity, reduce dependency bloat, and provide users with more flexibility in choosing which formats to support.

Motivation

Current Challenges

The current monolithic structure of Apache Fesod has several limitations that impact both users and contributors:

1. Unnecessary Dependencies: Users who only need CSV support must still include POI libraries (for XLS/XLSX), adding ~10MB of dependencies.

2. Tight Coupling: Format-specific code (CSV, XLS, XLSX) is intermingled within the same module, making it difficult to:

   • Understand which code handles which format
   • Modify one format without risk of affecting others
   • Add new formats without touching existing code

3. Complex Codebase Navigation: The current structure uses conditional logic (switch statements) to handle different formats, scattered across multiple classes.

4. Testing Complexity: Unit tests for all formats are mixed together, making it harder to:

   • Run format-specific tests
   • Identify which tests cover which functionality
   • Maintain test isolation

5. Example Code Confusion: The fesod-examples module contains a mix of actual examples (in demo package) and temporary test code (in temp package), with unclear purpose.

Benefits of Multi-Module Architecture

For End Users:

• Smaller dependency footprint (include only needed formats)

For Contributors:

• Easier to understand and modify format-specific code
• Reduced risk of cross-format bugs
• Clearer test organization

For the Project:

• Better separation of concerns
• Potential for independent format evolution
• Clearer module boundaries and responsibilities
• Improved code maintainability

Current Architecture

Existing Module Structure

Apache Fesod currently consists of two Maven modules:

Proposed Architecture

Proposed Module Structure

The refactored project will have the following module hierarchy:

fesod-parent (root POM)
├── fesod-core (shared infrastructure)
├── fesod-csv (CSV format support)
├── fesod-xls (XLS/BIFF8 format support)
├── fesod-xlsx (XLSX/OOXML format support)
├── fesod-all (backward compatibility aggregator)
└── fesod-examples (usage examples)

Dependency Graph

graph TD
    A[fesod-core] --> B[Common Dependencies]
    C[fesod-csv] --> A
    C --> D[commons-csv]
    E[fesod-xls] --> A
    E --> F[poi]
    G[fesod-xlsx] --> A
    G --> H[poi-ooxml]
    H --> F
    I[fesod-examples] --> C
    I --> E
    I --> G
    I --> J[Spring Boot]
    B --> K[ehcache]
    B --> L[commons-io]
    B --> M[slf4j-api]

Module Interaction Patterns

Read Operation Flow (Sample)

sequenceDiagram
    participant User
    participant Factory
    participant Core
    participant FormatModule as Format Module (CSV/XLS/XLSX)
    
    User->>Factory: FastExcel.read(file)
    Factory->>Core: Detect format (ExcelTypeEnum)
    Factory->>FormatModule: ServiceLoader discover provider
    FormatModule->>Factory: Return format provider
    Factory->>FormatModule: Create ExcelReader
    FormatModule->>Core: Use core metadata & converters
    FormatModule->>User: Return configured reader
    User->>FormatModule: Execute read operation
    FormatModule->>Core: Fire events & process data
    Core->>User: Deliver parsed data via listeners

Compatibility and Migration

Backward Compatibility Strategy

To ensure a smooth transition for existing users, we will provide multiple compatibility mechanisms:

For Existing Users

Users who upgrade will have two migration paths:

Option 1: No Changes Required (Recommended for initial adoption)

Continue using the aggregator module with the same Maven coordinates:

<dependency>
    <groupId>org.apache.fesod</groupId>
    <artifactId>fesod</artifactId>
    <version>2.0.0</version>
</dependency>

The fesod artifact will become an aggregator that includes all format modules, maintaining complete backward compatibility.

Option 2: Selective Module Usage (For optimization)

Choose only the formats needed:

<!-- Core + CSV only -->
<dependency>
    <groupId>org.apache.fesod</groupId>
    <artifactId>fesod-core</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.apache.fesod</groupId>
    <artifactId>fesod-csv</artifactId>
    <version>2.0.0</version>
</dependency>

This proposal is open for community discussion and will be updated based on feedback.