Merge branch 'v1.x.x'

README.md

@@ -1,3 +1,4 @@
+
 [![Build Status](https://travis-ci.org/millij/poi-object-mapper.svg?branch=master)](https://travis-ci.org/millij/poi-object-mapper)
 [![codecov](https://codecov.io/gh/millij/poi-object-mapper/branch/master/graph/badge.svg)](https://codecov.io/gh/millij/poi-object-mapper)
 
@@ -13,7 +14,19 @@ The aim of this project is to provide easy to use highlevel APIs to read the Off
 
 ## Include
 
-This library is not yet available in the Maven Central. For now it hast to be installed manually. Please check the [releases](https://github.com/millij/poi-object-mapper/releases) page for change log and versions.
+This library is available in [Maven Central](https://mvnrepository.com/artifact/io.github.millij/poi-object-mapper). 
+
+`pom.xml` entry details..
+
+```
+<dependency>
+    <groupId>io.github.millij</groupId>
+    <artifactId>poi-object-mapper</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+To install manually, please check the [releases](https://github.com/millij/poi-object-mapper/releases) page for available versions and  change log.
 
 #### Dependencies
 
@@ -23,6 +36,7 @@ The current implementation uses **POI version 3.17**.
 ## Usage
 
 ### Spreadsheets (Excel)
+
 Consider the below sample spreadsheet, where data of employees is present.
 
 | Name              | Age   | Gender | Height (mts) | Address                            |
@@ -31,7 +45,9 @@ Consider the below sample spreadsheet, where data of employees is present.
 | John Doe          | 45    | MALE   | 2.1          |                                    |
 | Guiliano Carlini  |       | MALE   | 1.78         | Palo Alto, CA – 43234              |
 
+
 ##### Mapping Rows to a Java Bean
+
 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.    
 
 ```java
@@ -60,7 +76,7 @@ Reading spreadsheet rows as objects ..
     ...
     final File xlsxFile = new File("<path_to_file>");
     final XlsReader reader = new XlsReader();
-    List<Employee> employees = reader.read(xlsxFile, Employee.class);
+    List<Employee> employees = reader.read(Employee.class, xlsxFile);
     ...
 ```
 
@@ -87,10 +103,12 @@ Reading spreadsheet rows as objects ..
 
 
 
-## Known Issues
+## Issues
+
+The known issues are already listed under [Issues Section](https://github.com/millij/poi-object-mapper/releases).
+
+Please add there your bugs findings, feature requests, enhancements etc. 
+
+
 
-- Reading Large files is not suggested as stream reading is yet to be supported.
-- XLS file writing is not supported.
-- Mapping `Date` files through a `DateFormat` is not supported yet.
-- Reading `Formula` cells is not supported yet.
 

build.gradle

@@ -11,7 +11,7 @@ repositories {
 }
 
 group = 'io.github.millij'
-version = '1.0.0-SNAPSHOT'
+version = '1.0.0'
 
 
 dependencies {
@@ -33,9 +33,9 @@ dependencies {
     // Test compile
     // ----------------------------------------------------------------------------------
 
-    testCompile group: "org.slf4j", name: "slf4j-log4j12", version: "1.7.12"
+    testCompile group: 'org.slf4j', name: 'slf4j-log4j12', version: '1.7.12'
 
-    testCompile group: 'junit', name: 'junit', version: '4.+'
+    testCompile group: 'junit', name: 'junit', version: '4.12'
 
 }
 

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

@@ -16,30 +16,157 @@
 public interface SpreadsheetReader {
 
 
-    // Read with row eventHandler
-
-    <T> void read(Class<T> beanClz, File file, RowListener<T> eventHandler) throws SpreadsheetReadException;
-
-    <T> void read(Class<T> beanClz, InputStream is, RowListener<T> eventHandler) throws SpreadsheetReadException;
-
-
-    <T> void read(Class<T> beanClz, File file, int sheetNo, RowListener<T> eventHandler)
-            throws SpreadsheetReadException;
-
-    <T> void read(Class<T> beanClz, InputStream is, int sheetNo, RowListener<T> eventHandler)
+    // Read with Custom RowListener
+
+    /**
+     * Reads the spreadsheet file to beans of the given type. This method will attempt to read all
+     * the available sheets of the file and creates the objects of the passed type.
+     * 
+     * <p>
+     * The {@link RowListener} implementation callback gets triggered after reading each Row. Best
+     * Suited for reading Large files in restricted memory environments.
+     * </p>
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz The Class type to deserialize the rows data
+     * @param file {@link File} object of the spreadsheet file
+     * @param listener Custom {@link RowListener} implementation for row data callbacks.
+     * 
+     * @throws SpreadsheetReadException an exception is thrown in cases where the file data is not
+     *         readable or row data to bean mapping failed.
+     */
+    <T> void read(Class<T> beanClz, File file, RowListener<T> listener) throws SpreadsheetReadException;
+
+
+    /**
+     * Reads the spreadsheet file to beans of the given type. This method will attempt to read all
+     * the available sheets of the file and creates the objects of the passed type.
+     * 
+     * <p>
+     * The {@link RowListener} implementation callback gets triggered after reading each Row. Best
+     * Suited for reading Large files in restricted memory environments.
+     * </p>
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz The Class type to deserialize the rows data
+     * @param is {@link InputStream} of the spreadsheet file
+     * @param listener Custom {@link RowListener} implementation for row data callbacks.
+     * 
+     * @throws SpreadsheetReadException an exception is thrown in cases where the file data is not
+     *         readable or row data to bean mapping failed.
+     */
+    <T> void read(Class<T> beanClz, InputStream is, RowListener<T> listener) throws SpreadsheetReadException;
+
+
+    /**
+     * Reads the spreadsheet file to beans of the given type. Note that only the requested sheet
+     * (sheet numbers are indexed from 0) will be read.
+     * 
+     * <p>
+     * The {@link RowListener} implementation callback gets triggered after reading each Row. Best
+     * Suited for reading Large files in restricted memory environments.
+     * </p>
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz The Class type to deserialize the rows data
+     * @param file {@link File} object of the spreadsheet file
+     * @param sheetNo index of the Sheet to be read (index starts from 0)
+     * @param listener Custom {@link RowListener} implementation for row data callbacks.
+     * 
+     * @throws SpreadsheetReadException an exception is thrown in cases where the file data is not
+     *         readable or row data to bean mapping failed.
+     */
+    <T> void read(Class<T> beanClz, File file, int sheetNo, RowListener<T> listener) throws SpreadsheetReadException;
+
+
+    /**
+     * Reads the spreadsheet file to beans of the given type. Note that only the requested sheet
+     * (sheet numbers are indexed from 0) will be read.
+     * 
+     * <p>
+     * The {@link RowListener} implementation callback gets triggered after reading each Row. Best
+     * Suited for reading Large files in restricted memory environments.
+     * </p>
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz The Class type to deserialize the rows data
+     * @param is {@link InputStream} of the spreadsheet file
+     * @param sheetNo index of the Sheet to be read (index starts from 0)
+     * @param listener Custom {@link RowListener} implementation for row data callbacks.
+     * 
+     * @throws SpreadsheetReadException an exception is thrown in cases where the file data is not
+     *         readable or row data to bean mapping failed.
+     */
+    <T> void read(Class<T> beanClz, InputStream is, int sheetNo, RowListener<T> listener)
             throws SpreadsheetReadException;
 
 
 
-    // Read all
+    // Read with default RowListener
 
+    /**
+     * Reads the spreadsheet file to beans of the given type. This method will attempt to read all
+     * the available sheets of the file and creates the objects of the passed type.
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz The Class type to deserialize the rows data
+     * @param file {@link File} object of the spreadsheet file
+     * 
+     * @return a {@link List} of objects of the parameterized type
+     * 
+     * @throws SpreadsheetReadException an exception is thrown in cases where the file data is not
+     *         readable or row data to bean mapping failed.
+     */
     <T> List<T> read(Class<T> beanClz, File file) throws SpreadsheetReadException;
 
+
+    /**
+     * Reads the spreadsheet file to beans of the given type. This method will attempt to read all
+     * the available sheets of the file and creates the objects of the passed type.
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz The Class type to deserialize the rows data
+     * @param is {@link InputStream} of the spreadsheet file
+     * 
+     * @return a {@link List} of objects of the parameterized type
+     * 
+     * @throws SpreadsheetReadException an exception is thrown in cases where the file data is not
+     *         readable or row data to bean mapping failed.
+     */
     <T> List<T> read(Class<T> beanClz, InputStream is) throws SpreadsheetReadException;
 
 
+    /**
+     * Reads the spreadsheet file to beans of the given type. Note that only the requested sheet
+     * (sheet numbers are indexed from 0) will be read.
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz beanClz The Class type to deserialize the rows data
+     * @param file file {@link File} object of the spreadsheet file
+     * @param sheetNo index of the Sheet to be read (index starts from 0)
+     * 
+     * @return a {@link List} of objects of the parameterized type
+     * 
+     * @throws SpreadsheetReadException SpreadsheetReadException an exception is thrown in cases
+     *         where the file data is not readable or row data to bean mapping failed.
+     */
     <T> List<T> read(Class<T> beanClz, File file, int sheetNo) throws SpreadsheetReadException;
 
+
+    /**
+     * Reads the spreadsheet file to beans of the given type. Note that only the requested sheet
+     * (sheet numbers are indexed from 0) will be read.
+     * 
+     * @param <T> The Parameterized bean Class.
+     * @param beanClz beanClz The Class type to deserialize the rows data
+     * @param is {@link InputStream} of the spreadsheet file
+     * @param sheetNo index of the Sheet to be read (index starts from 0)
+     * 
+     * @return a {@link List} of objects of the parameterized type
+     * 
+     * @throws SpreadsheetReadException SpreadsheetReadException an exception is thrown in cases
+     *         where the file data is not readable or row data to bean mapping failed.
+     */
     <T> List<T> read(Class<T> beanClz, InputStream is, int sheetNo) throws SpreadsheetReadException;