From 9c7635aa084c773f5787d4896cefb9fd21ddc67e Mon Sep 17 00:00:00 2001 From: Alexander Partsch Date: Wed, 24 Mar 2021 08:38:36 +0100 Subject: [PATCH] Close #13 Add Markdown Files --- ARCHITECTURE.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTE.md | 28 +++++++++++++++++ README.md | 68 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 180 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 CONTRIBUTE.md create mode 100644 README.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..46e6883 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,84 @@ +# POIPath Architecture + +*POIPath*'s intention is to deliver easy means for testing the correctness of generated +`XWPFDocument`s or `XSSFWorkbook`s. It was developed for the [jocument](https://github.com/DDS-GmbH/jocument) +library, which wraps a template engine around Apache POI. + +## Design + +The design idea is to have wrapper classes (or [Java Records](https://docs.oracle.com/javase/specs/jls/se14/preview/specs/records-jls.html)) +on each XWPF/XSS element to quickly navigate through a document structure and parse the +actual content out of it. The following example shows how to access a date cell of an +`XSSWorkbook`: + +```java +package org.example.popath; + +import java.util.LocalDate; +import com.docutools.poipath.PoiPath; +import com.docutools.poipath.xssf.*; +import import org.apache.poi.xssf.usermodel.XSSFWorkbook; + +public class PoiPathExample { + + public static void main(String[] args) { + try(var workbook = new XSSFWorkbook(new File(args[0]))) { + LocalDate date = PoiPath.xssf(workbook) + .sheet(0) + .row(0) + .cell(0) + .dateValue(); + + assert date.equals(LocalDate.of(2000, 1, 1)); + } + } + +} +``` + +## Code Map + +### [PoiPath](src/main/java/com/docutools/poipath/PoiPath.java) + +Entrypoint to load the corresponding wrapper class for the given POI document. + +### [com.docutools.poipath.xssf](src/main/java/com/docutools/poipath/xssf) + +This package contains all wrapper recrods to navigate through `XSSFWorkbook`s. + +### [com.docutools.poipath.xwpf](src/main/java/com/docutools/poipath/xwpf) + +This package contains all wrapper records to navigate through `XWPFDocument`s. + +## Corss-Cutting Concerns + +### Testing + +Test files (`.XLSX` or `.DOCX`) are added as resources to [src/test/resources](src/test/resources) +within the corresponding file type folder. + +We provide easy resource loading via the utility classes: + +* [Documents](src/test/java/com/docutools/poipath/Documents.java) +* [Workbooks](src/test/java/com/docutools/poipath/Workbooks.java) + +A typical test case may look like: + +```java +package com.docutools.poipath.xssf; + +import java.io.IOException; +import org.junit.jupiter.api.Test; +import com.docutools.poipath.Workbooks; + +class SomeXssfTests { + + @Test + void someXssfTest() throws IOException { + try(var workbook = Workbooks.resource("/XSSF/myExcelResource.xlsx")) { + assert PoiPath.xssf(workbook).numberOfSheets() == 2; + } + } + +} +``` \ No newline at end of file diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..b0850e6 --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,28 @@ +# Contributing +When contributing to this repository, please first discuss the change you wish to make via issue, +email, or any other method with the owners of this repository before making a change. + +## We Develop with Github +We use github to host code, to track issues and feature requests, as well as accept pull requests. + +## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests +Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests: + +1. Fork the repo and create your branch from `master`. +2. If you've added code that should be tested, add tests. +3. If you've changed APIs, update the documentation. +4. Ensure the test suite passes. +5. Make sure your code lints. +6. Issue that pull request! + +## Any contributions you make will be under the MIT Software License +In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern. + +## Report bugs using Github's [issues](https://github.com/DDS-GmbH/poipath/issues) +We use GitHub issues to track public bugs. Report a bug by [opening a new issue](); it's that easy! + +## Use a Consistent Coding Style + +This project is using [Checkstyle](https://checkstyle.sourceforge.io/) to ensure a shared code style is enforced. + +You can find the checkstyle conventions in [this file](config/checkstyle/checkstyle.xml), which can be imported to any current JAVA IDE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d1ec6bf --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +# poipath +> Testing library for [Apache POI](https://poi.apache.org/) documents. + +*poipath* let's you easily navigate through [XSSFWorkbook](https://poi.apache.org/apidocs/dev/org/apache/poi/xssf/usermodel/XSSFWorkbook.html) +or [XWPFDocument](https://poi.apache.org/apidocs/dev/org/apache/poi/xwpf/usermodel/XWPFDocument.html) +datastructures from *Apache POI* which can be quite useful in testing. + +```xml + + com.docu-tools + poipath + 1.0.0 + +``` + +Here an example for testing an Excel report: + +```java +package myreportingapp; + +import java.io.File; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Assertions; +import com.docutools.poipath.PoiPath; +import org.apache.poi.xssf.usermodel.XSSFWorkbook; + +class TestReports { + + @Test + void testMyReport() throws Exception { + try(var report = PoiPath.xssf(new XSSFWorkbook(new File("/path/to/file.xlsx")))) { + + Assertions.assertEquals(report.sheet("Overview") + .row(2).cell(3).dateValue(), LocalDate.of(2021, 12, 13)); + + Assertions.assertEquals(report.sheet("Overview") + .row(3).cell(3).stringValue(), "Performance Report"); + + } + } + +} +``` + +## Feature Overview + +### XSSF + +- [x] Navigate Sheets, Rows, Cells +- [x] Extract primitively typed values based on cell type (Number, String, Boolean) +- [x] Get raw and executed formulas +- [x] Parse dates +- [ ] Monetary amounts +- [ ] Control elements +- [ ] Pictures or diagrams +- [ ] Header/footer +- [ ] Document/page settings + +### XWPF + +- [x] Navigate body elements (paragraphs and tables) +- [x] Extract runs and pictures from paragraphs +- [x] Extract rows and cells from tables +- [x] Easily load full text from paragraphs and table cells +- [ ] Header/footer +- [ ] Document/page settings +- [ ] Footer notes +- [ ] Table of contents \ No newline at end of file