Merge branch 'v3.x.x'

Author: millij

README.md

@@ -5,9 +5,9 @@
 
 # poi-object-mapper
 
-**poi-object-mapper** is a wrapper java library for [Apache POI](https://poi.apache.org/) (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.
+**poi-object-mapper** is a wrapper java library for [Apache POI](https://poi.apache.org/) (Apache POI provides java API to read Microsoft Office Formats). POI APIs are very low level giving access 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](https://github.com/FasterXML/jackson), 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.
+The aim of this project is to provide easy to use high-level 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](https://github.com/FasterXML/jackson), 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).*
 
@@ -22,7 +22,7 @@ This library is available in [Maven Central](https://mvnrepository.com/artifact/
 <dependency>
     <groupId>io.github.millij</groupId>
     <artifactId>poi-object-mapper</artifactId>
-    <version>3.1.0</version>
+    <version>3.2.0</version>
 </dependency>
 ```
 
@@ -95,7 +95,7 @@ Reading spreadsheet rows as `Map<String, Object>` Objects ..
 ```
 
 
-##### Writing a collection of objects to file
+##### Writing a List of objects to file
 
 Similar to `Reader`, the mapped Java Beans can be written to files.
 
@@ -116,7 +116,43 @@ Use `XlsWriter` for `.xls` files and `XlsxWriter` for `.xlsx` files.
     ...
 ```
 
-## Implementation Details
+##### Writing a List of objects defined as Map to file
+
+Similar to `Reader`, the `Writer` also supports Row data defined as `Map<String, Object>`. 
+This is to support the data that is not backed by a concrete bean Class definition
+
+Use `XlsWriter` for `.xls` files and `XlsxWriter` for `.xlsx` files.
+
+```java
+    ...
+    // Employees
+    final Map<String, Object> emp1 = new HashMap<>();
+    emp1.put("Name", "foo");
+    emp1.put("Age", 12);
+    emp1.put("Gender", "MALE");
+    emp1.put("Height (mts)", 1.68);
+
+    final Map<String, Object> emp2 = new HashMap<>();
+    emp1.put("Name", "bar");
+    emp1.put("Age", null);
+    emp1.put("Gender", "MALE");
+
+    final List<Map<String, Object>> employees = Arrays.asList(emp1, emp2);
+
+    // Headers (or Column Names)
+    final List<String> headers = new ArrayList<>();
+    headers.add("Name");
+    headers.add("Age");
+    headers.add("Gender");
+    headers.add("Height (mts)");
+    headers.add("Address");
+
+    // Writer
+    final SpreadsheetWriter writer = new XlsxWriter();
+    writer.addSheet(employees, headers);
+    writer.write("<output_file_path>");
+
+```
 
 
 

build.gradle

@@ -11,11 +11,11 @@ repositories {
 }
 
 
-sourceCompatibility = 1.11
-targetCompatibility = 1.11
+sourceCompatibility = 1.8
+targetCompatibility = 1.8
 
 group = 'io.github.millij'
-version = '3.1.0'
+version = '3.2.0'
 
 
 dependencies {

src/main/java/io/github/millij/poi/ss/handler/AbstractSheetContentsHandler.java

@@ -2,14 +2,14 @@
 
 import java.util.HashMap;
 import java.util.Map;
-import java.util.Objects;
 
 import org.apache.poi.xssf.eventusermodel.XSSFSheetXMLHandler.SheetContentsHandler;
 import org.apache.poi.xssf.usermodel.XSSFComment;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import io.github.millij.poi.util.Spreadsheet;
+import io.github.millij.poi.util.Strings;
 
 
 abstract class AbstractSheetContentsHandler implements SheetContentsHandler {
@@ -30,7 +30,6 @@ abstract class AbstractSheetContentsHandler implements SheetContentsHandler {
     abstract void afterRowEnd(int rowNum, Map<String, Object> rowObj);
 
 
-
     // SheetContentsHandler Implementations
     // ------------------------------------------------------------------------
 
@@ -53,12 +52,12 @@ public void endRow(final int rowNum) {
     @Override
     public void cell(final String cellRef, final String cellVal, final XSSFComment comment) {
         // Sanity Checks
-        if (Objects.isNull(cellRef) || cellRef.isBlank()) {
+        if (Strings.isBlank(cellRef)) {
             LOGGER.error("Row[#] {} : Cell reference is empty - {}", currentRow, cellRef);
             return;
         }
 
-        if (Objects.isNull(cellVal) || cellVal.isBlank()) {
+        if (Strings.isBlank(cellVal)) {
             LOGGER.warn("Row[#] {} - Cell[ref] formatted value is empty : {} - {}", currentRow, cellRef, cellVal);
             return;
         }

src/main/java/io/github/millij/poi/ss/model/annotations/SheetColumn.java

@@ -40,16 +40,16 @@
 
 
     /**
-     * Data presentation format of the Data cell.
+     * Data presentation format of the Data Column.
      * 
      * @return Data format String.
      */
     String format() default "";
 
     /**
-     * DateTime Type
+     * DateTimeType value of the Column
      * 
-     * @return
+     * @return the {@link DateTimeType} value of the Column
      */
     DateTimeType datetime() default DateTimeType.NONE;
 

src/main/java/io/github/millij/poi/ss/reader/XlsReader.java

@@ -179,7 +179,7 @@ protected void processSheet(final HSSFSheet sheet, final RowListener<Map<String,
             }
 
             final Map<String, Object> rowDataMap = this.extractRowDataAsMap(row);
-            if (rowDataMap == null || rowDataMap.isEmpty()) {
+            if (Objects.isNull(rowDataMap) || rowDataMap.isEmpty()) {
                 continue;
             }
 
@@ -209,7 +209,7 @@ protected <T> void processSheet(final Class<T> beanClz, final HSSFSheet sheet, f
             }
 
             final Map<String, Object> rowDataMap = this.extractRowDataAsMap(row);
-            if (rowDataMap == null || rowDataMap.isEmpty()) {
+            if (Objects.isNull(rowDataMap) || rowDataMap.isEmpty()) {
                 continue;
             }
 

src/main/java/io/github/millij/poi/ss/writer/AbstractSpreadsheetWriter.java

@@ -21,6 +21,7 @@
 
 import io.github.millij.poi.ss.model.Column;
 import io.github.millij.poi.util.Spreadsheet;
+import io.github.millij.poi.util.Strings;
 
 
 /**
@@ -51,14 +52,14 @@ public AbstractSpreadsheetWriter(final Workbook workbook) {
     // ------------------------------------------------------------------------
 
 
-    // Sheet :: Add
+    // Sheet :: Bean
 
     @Override
     public <T> void addSheet(final Class<T> beanType, final List<T> rowObjects, final String inSheetName,
             final List<String> inHeaders) {
         // Sanity checks
         if (Objects.isNull(beanType)) {
-            throw new IllegalArgumentException("AbstractSpreadsheetWriter :: Bean Type is NULL");
+            throw new IllegalArgumentException("#addSheet :: Bean Type is NULL");
         }
 
         // Sheet config
@@ -77,7 +78,7 @@ public <T> void addSheet(final Class<T> beanType, final List<T> rowObjects, fina
             }
 
             // Create sheet
-            final Sheet sheet = Objects.isNull(sheetName) || sheetName.isBlank() //
+            final Sheet sheet = Strings.isBlank(sheetName) //
                     ? workbook.createSheet() //
                     : workbook.createSheet(sheetName);
             LOGGER.debug("Added new Sheet[name] to the workbook : {}", sheet.getSheetName());
@@ -110,18 +111,79 @@ public <T> void addSheet(final Class<T> beanType, final List<T> rowObjects, fina
     }
 
 
-    // Sheet :: Append to existing
+    // Sheet :: Map<String, Object>
+
+    @Override
+    public void addSheet(final List<Map<String, Object>> rowsData, final String inSheetName,
+            final List<String> inHeaders) {
+        // Sanity check
+        if (Objects.isNull(rowsData)) {
+            throw new IllegalArgumentException("#addSheet :: Rows data map is NULL");
+        }
+        if (Objects.isNull(inHeaders) || inHeaders.isEmpty()) {
+            throw new IllegalArgumentException("#addSheet :: Headers list is NULL or EMPTY");
+        }
+
+        try {
+            final Sheet exSheet = workbook.getSheet(inSheetName);
+            if (Objects.nonNull(exSheet)) {
+                String errMsg = String.format("A Sheet with the passed name already exists : %s", inSheetName);
+                throw new IllegalArgumentException(errMsg);
+            }
+
+            // Create sheet
+            final Sheet sheet = Strings.isBlank(inSheetName) //
+                    ? workbook.createSheet() //
+                    : workbook.createSheet(inSheetName);
+            LOGGER.debug("Added new Sheet[name] to the workbook : {}", sheet.getSheetName());
+
+            // Header
+            final Row headerRow = sheet.createRow(0);
+            for (int cellNum = 0; cellNum < inHeaders.size(); cellNum++) {
+                final Cell cell = headerRow.createCell(cellNum);
+                cell.setCellValue(inHeaders.get(cellNum));
+            }
+
+            // Data Rows
+            for (int i = 0, rowNum = 1; i < rowsData.size(); i++, rowNum++) {
+                final Row row = sheet.createRow(rowNum);
+                final Map<String, Object> rowData = rowsData.get(i);
+                if (Objects.isNull(rowData) || rowData.isEmpty()) {
+                    continue; // Skip if row is null
+                }
+
+                for (int cellNum = 0; cellNum < inHeaders.size(); cellNum++) {
+                    final String key = inHeaders.get(cellNum);
+                    final Object value = rowData.get(key);
+
+                    final Cell cell = row.createCell(cellNum);
+                    if (Objects.nonNull(value)) {
+                        cell.setCellValue(String.valueOf(value));
+                    }
+                }
+            }
+        } catch (Exception ex) {
+            String errMsg = String.format("Error while preparing sheet with passed row objects : %s", ex.getMessage());
+            LOGGER.error(errMsg, ex);
+        }
+    }
 
 
     // Write
 
     @Override
-    public void write(final String filepath) throws IOException {
-        try (final OutputStream outputStrem = new FileOutputStream(new File(filepath))) {
+    public void write(final File file) throws IOException {
+        // Sanity checks
+        if (Objects.isNull(file)) {
+            throw new IllegalArgumentException("#write :: Input File object is NULL");
+        }
+
+        try (final OutputStream outputStrem = new FileOutputStream(file)) {
             workbook.write(outputStrem);
             workbook.close();
+
         } catch (Exception ex) {
-            final String errMsg = String.format("Failed to write workbook data to file : %s", filepath);
+            final String errMsg = String.format("Failed to write workbook data to file : %s", file.getPath());
             LOGGER.error(errMsg);
             throw ex;
         }