poi-object-mapper is a wrapper java library for Apache POI (Apache POI provides java API to read Microsoft Office Formats). POI APIs are very low level giving acess to all the internals of the file formats.

The aim of this project is to provide easy to use highlevel APIs to read the Office file formats by wrapping the POI APIs. In simple terms, the wrapper APIs would look similar to the Jackson Project for XML and JSON, where the data can be mapped to a JAVA Bean and through the mapper APIs, the file data can directly be read as java objects.

- Note that the current version of the library supports only spreadsheets (Excel files).

This library is available in Maven Central.

pom.xml entry details..

<dependency>
    <groupId>io.github.millij</groupId>
    <artifactId>poi-object-mapper</artifactId>
    <version>3.1.0</version>
</dependency>

To install manually, please check the releases page for available versions and change log.

The current implementation uses POI version 5.2.5.

Consider the below sample spreadsheet, where data of employees is present.

Create a java bean and map its properties to the columns using the @SheetColumn annotation. The @SheetColumn annotation can be declared on the Field, as well as its Accessor Methods. Pick any one of them to configure the mapped Column as per convenience.

@Sheet
public class Employee {
    // Pick either field or its accessor methods to apply the Column mapping.
    ...
    @SheetColumn("Age")
    private Integer age;
    ...
    @SheetColumn("Name")
    public String getName() {
        return name;
    }
    ...
}

Once a mapped Java Bean is ready, use a Reader to read the file rows as objects.

Use XlsReader for .xls files and XlsxReader for .xlsx files.

Reading spreadsheet rows as objects ..

    ...
    final File xlsFile = new File("<path_to_file>");
    final XlsReader reader = new XlsReader();
    final List<Employee> employees = reader.read(Employee.class, xlsFile);
    ...

Reading spreadsheet rows as Map<String, Object> Objects ..

    ...
    final File xlsxFile = new File("<path_to_file>");
    final XlsxReader reader = new XlsxReader(); // OR XlsReader as needed
    final List<Map<String, Object>> rowObjects = reader.read(xlsxFile);
    ...

Similar to Reader, the mapped Java Beans can be written to files.

Use XlsWriter for .xls files and XlsxWriter for .xlsx files.

    ...
    // Employees
    final List<Employee> employees = new ArrayList<>();
    employees.add(new Employee("1", "foo", 12, "MALE", 1.68));
    employees.add(new Employee("2", "bar", null, "MALE", 1.68));
    employees.add(new Employee("3", "foo bar", null, null, null));

    // Writer
    final SpreadsheetWriter writer = new XlsxWriter();
    writer.addSheet(Employee.class, employees);
    writer.write("<output_file_path>");
    ...

The known issues are already listed under Issues Section.

Please add there your bugs findings, feature requests, enhancements etc.