How ozlerhakan/poiji works
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