# ozlerhakan/poiji architecture

> Architecture diagram of the GitHub repository ozlerhakan/poiji, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ozlerhakan/poiji
- Repository: https://github.com/ozlerhakan/poiji

## Overview

##### Project type and purpose
- Poiji is an open-source, annotation-driven Java library (Maven project) that maps rows in Excel files (XLS/XLSX) to Java POJOs. It relies on Apache POI under the hood and exposes a fluent API (`Poiji.fromExcel(...)`) plus an options builder (`PoijiOptionsBuilder`) for customization.

##### File structure
- Top-level artifacts:
- pom.xml – Maven build and dependency management
- .github/workflows – CI/CD pipelines (build, publish)
- src/main/java/com/poiji/annotation – Custom mapping annotations (`@ExcelCell`, `@ExcelCellName`, etc.)
- src/main/java/com/poiji/bind – Core entrypoints (`Poiji`, `PoijiFile`, `PoijiInputStream`)
- src/main/java/com/poiji/bind/mapping – Unmarshaller implementations (HSSF vs. XSSF), workbook/​sheet handlers
- src/main/java/com/poiji/option – PoijiOptions and builder (fluent API for settings)
- src/main/java/com/poiji/parser – Type parsers (BigDecimal, Boolean, Number)
- src/main/java/com/poiji/config – Casting/formatting strategy interfaces and defaults
- src/main/java/com/poiji/util – Reflection helpers, constants, file utilities
- src/main/java/com/poiji/exception – Custom exceptions for validation and error handling
- src/test and src/test/resources – Unit tests and sample Excel files

##### README for additional insights
- Describes the public API surface (`Poiji.fromExcel` overloads, `PoijiOptionsBuilder` methods)
- Illustrates major features (annotation mapping, consumer interface, custom casting/formatting, property reading, debugging cell formats)
- Confirms key external dependency: Apache POI

##### Main components and their interactions
a. Components
- Client code (your application or consumer)
- API entrypoint (`com.poiji.bind.Poiji`)
- Input adapters (`PoijiFile`, `PoijiInputStream`, direct POI Sheet)
- Unmarshaller factory/dispatcher (decides HSSF vs XSSF based on file type or stream)
- Workbook/Sheet handlers (`WorkBookContentHandler`, `SheetUnmarshaller`)
- Mapping engine
– Annotation scanner (`AnnotationUtil`)
– Property unmarshalling (`PropertyUnmarshaller`, `PoijiHandler`)
– Parsers and casters (`Parser` implementations, `Casting` interface)
– Formatting (`Formatting` interface, `PoijiNumberFormat`, `PoijiLogCellFormat`)
- PoijiOptions (Builder pattern for all runtime settings)
- Exception layer (validates mandatory headers/cells, file type, instantiation errors)
- Output collector (returns List<T> or invokes Consumer<T>)
- External libs: Apache POI (for low-level Excel I/O), JUnit/TestNG for tests

b. Relationships & data flow
1. Client invokes `Poiji.fromExcel(...)` with File/InputStream/Sheet + target class + optional `PoijiOptions` + optional `Consumer<T>`.
2. Poiji inspects file type or POI Sheet, selects HSSF or XSSF unmarshaller.
3. Unmarshaller opens the Workbook, iterates sheets/rows/cells.
4. For each row:
– Annotations on target class fields are scanned.
– Values read from cells are passed through Formatting → Casting → Parser chain.
– `PropertyUnmarshaller` wraps value into the target field via reflection.
– Optional `Consumer<T>` is called per object; otherwise objects are collected into List<T>.
5. On errors (missing headers, illegal cast, invalid file extension), custom Poiji exceptions bubble up.

c. Architectural patterns and design principles
- Builder pattern: `PoijiOptionsBuilder` for immutably configuring parser behavior
- Strategy pattern: pluggable `Casting` and `Formatting` implementations
- Factory/dispatcher: unmarshaller selection (HSSF vs XSSF)
- Template method: workbook and sheet processing pipeline in `WorkBookContentHandler` and `SheetUnmarshaller`
- Annotation-driven mapping: decouples Excel schema from code

d. Key technologies/frameworks
- Java 8+
- Apache POI (XSSF/HSSF)
- Maven for build and publishing
- GitHub Actions for CI/CD
- JUnit (and related test frameworks) for unit tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application"]:::input
    Poiji["Poiji.fromExcel()"]:::core
    PoijiOptions["PoijiOptionsBuilder"]:::ext
    FileAdapter["PoijiFile"]:::input
    StreamAdapter["PoijiInputStream"]:::input
    SheetAdapter["POI Sheet"]:::input
    UnmarshallerFactory["UnmarshallerFactory\n(HSSF vs XSSF)"]:::core
    HSSF["HSSFUnmarshaller"]:::core
    XSSF["XSSFUnmarshaller"]:::core

    subgraph WorkbookLayer
        WBC["WorkBookContentHandler"]:::core
        SU["SheetUnmarshaller"]:::core
        PWB["PoijiWorkBook"]:::core
        WBS["WorkBookSheet"]:::core
    end

    subgraph MappingEngine
        subgraph AnnotationModule
            AN["Annotations"]:::ext
        end
        PU["PropertyUnmarshaller"]:::core
        PH["PoijiHandler"]:::core
        PMH["PoijiPropertyHelper"]:::core
        UHelper["UnmarshallerHelper"]:::core
        PropHandler["PropertyHandler"]:::core
        subgraph FormattingModule
            NSF["PoijiNumberFormat"]:::ext
            LCF["PoijiLogCellFormat"]:::ext
            DTF["PoijiDataFormatter"]:::ext
        end
        subgraph ConfigStrategies
            CastingI["Casting"]:::ext
            DefaultCasting["DefaultCasting"]:::ext
            CastingErr["DefaultCastingError"]:::ext
            FormattingI["Formatting"]:::ext
            DefaultFormatting["DefaultFormatting"]:::ext
        end
        subgraph ParserModule
            ParserI["Parser"]:::ext
            BigDecimalP["BigDecimalParser"]:::ext
            BooleanP["BooleanParser"]:::ext
            NumberP["NumberParser"]:::ext
            ParsersReg["Parsers"]:::ext
        end
    end

    Exceptions["Exception Layer"]:::ext
    Collector["List<T>/Consumer<T>"]:::core
    ExternalPOI["Apache POI"]:::external

    Client -->|"calls"| Poiji
    Poiji -->|"uses options"| PoijiOptions
    Poiji -->|"adapts"| FileAdapter
    Poiji -->|"adapts"| StreamAdapter
    Poiji -->|"or uses"| SheetAdapter
    FileAdapter --> UnmarshallerFactory
    StreamAdapter --> UnmarshallerFactory
    SheetAdapter --> UnmarshallerFactory
    UnmarshallerFactory -->|"decides"| HSSF
    UnmarshallerFactory -->|"decides"| XSSF
    HSSF --> WBC
    XSSF --> WBC
    WBC --> SU
    SU --> PU
    PU --> PH
    PU --> AN
    PH --> UHelper
    PH --> PMH
    PH --> PropHandler
    PH --> FormattingModule
    FormattingModule -->|uses| ConfigStrategies
    PH -->|"calls parser"| ParserModule
    ParserModule -->|reads| ExternalPOI
    PH --> Collector
    PoijiOptions --> WBC
    PoijiOptions --> FormattingModule
    PoijiOptions --> ParserModule

    click AN "https://github.com/ozlerhakan/poiji/tree/master/src/main/java/com/poiji/annotation/"
    click Poiji "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/Poiji.java"
    click FileAdapter "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/PoijiFile.java"
    click StreamAdapter "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/PoijiInputStream.java"
    click UnmarshallerFactory "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/Unmarshaller.java"
    click PU "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/PropertyUnmarshaller.java"
    click HSSF "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/HSSFUnmarshaller.java"
    click XSSF "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/XSSFUnmarshaller.java"
    click WBC "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/WorkBookContentHandler.java"
    click SU "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/SheetUnmarshaller.java"
    click PWB "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PoijiWorkBook.java"
    click WBS "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/WorkBookSheet.java"
    click PH "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PoijiHandler.java"
    click UHelper "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/UnmarshallerHelper.java"
    click PropHandler "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PropertyHandler.java"
    click PMH "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PoijiPropertyHelper.java"
    click NSF "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PoijiNumberFormat.java"
    click LCF "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PoijiLogCellFormat.java"
    click DTF "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/bind/mapping/PoijiDataFormatter.java"
    click PoijiOptions "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/option/PoijiOptions.java"
    click CastingI "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/config/Casting.java"
    click DefaultCasting "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/config/DefaultCasting.java"
    click CastingErr "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/config/DefaultCastingError.java"
    click FormattingI "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/config/Formatting.java"
    click DefaultFormatting "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/config/DefaultFormatting.java"
    click ParserI "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/parser/Parser.java"
    click BigDecimalP "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/parser/BigDecimalParser.java"
    click BooleanP "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/parser/BooleanParser.java"
    click NumberP "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/parser/NumberParser.java"
    click ParsersReg "https://github.com/ozlerhakan/poiji/blob/master/src/main/java/com/poiji/parser/Parsers.java"
    click Exceptions "https://github.com/ozlerhakan/poiji/tree/master/src/main/java/com/poiji/exception/"
    click Util "https://github.com/ozlerhakan/poiji/tree/master/src/main/java/com/poiji/util/"

    classDef input fill:#e0ffe0,stroke:#2d7f2d,color:#2d7f2d
    classDef core fill:#e0e0ff,stroke:#2d2d7f,color:#2d2d7f
    classDef ext fill:#fff5cc,stroke:#7f5f00,color:#7f5f00
    classDef external fill:#ffe0cc,stroke:#7f3300,color:#7f1a00
```
