From 3f89cb5869fab126ff3ca1d4884552466d45293d Mon Sep 17 00:00:00 2001 From: Marten Deinum Date: Mon, 24 Mar 2014 20:42:47 +0100 Subject: [PATCH] Added readme. --- spring-batch-excel/README.md | 49 +++++++++++++++++++ .../item/excel/AbstractExcelItemReader.java | 1 + .../item/excel/ExcelFileParseException.java | 2 +- .../batch/item/excel/RowCallbackHandler.java | 1 + .../batch/item/excel/RowMapper.java | 1 + .../batch/item/excel/Sheet.java | 1 + .../batch/item/excel/jxl/JxlItemReader.java | 3 +- .../batch/item/excel/jxl/JxlSheet.java | 2 +- .../batch/item/excel/jxl/JxlUtils.java | 2 +- .../item/excel/mapping/DefaultRowMapper.java | 1 + .../excel/mapping/PassThroughRowMapper.java | 3 +- .../batch/item/excel/poi/PoiItemReader.java | 1 + .../batch/item/excel/poi/PoiSheet.java | 2 +- .../transform/ColumnToAttributeConverter.java | 1 + .../excel/transform/DefaultRowTokenizer.java | 1 + .../MappingColumnToAttributeConverter.java | 1 + ...PassThroughColumnToAttributeConverter.java | 1 + .../item/excel/transform/RowTokenizer.java | 2 +- 18 files changed, 68 insertions(+), 7 deletions(-) create mode 100644 spring-batch-excel/README.md diff --git a/spring-batch-excel/README.md b/spring-batch-excel/README.md new file mode 100644 index 0000000..a52e12e --- /dev/null +++ b/spring-batch-excel/README.md @@ -0,0 +1,49 @@ +# spring-batch-excel + +Spring Batch extension which contains ItemReader implementations for Excel. Support for both JExcel and Apache POI is available. + +## Configuration + +Next to the [configuration of Spring Batch](http://docs.spring.io/spring-batch/2.2.x/reference/html/configureJob.html) one needs to configure an `ItemReader` which knows how to read an Excel file. +There are 2 `ItemReaders` one can configure: + +- `org.springframework.batch.item.excel.jxl.JxlItemReader` +- `org.springframework.batch.item.excel.poi.PoiItemReader` + +Configuration of both readers is the same, the difference is the used technology ([JExcel](http://jexcelapi.sourceforge.net) or [Apache Poi](http://poi.apache.org)) and cababilities of both technologies (JExcel cannot read xlsx files, whereas Apache POI can read those). + + + + + + + + +Each reader takes a `resource` which is the excel file to read and a `rowMapper` which transforms the row in excel to an object which you can use in the rest of the process. +The project has 2 default `org.springframework.batch.item.excel.RowMapper` implementations. + +Optionally one can also set the `skippedRowsCallback`, `linesToSkip` and `strict` property. + +##### skippedRowsCallback +When rows are skipped an optional `org.springframework.batch.item.excel.RowCallbackHandler` is called with the skipped row. This comes in handy when one needs to write the skipped rows to another file or create some logging. + +##### linesToSkip +The number of lines to skip, this applies to each sheet in the Excel file. + +##### strict +By default `true`. This controls wether or not an exception is thrown if the file doesn't exists, by default an exception will be thrown. + +### PassThroughRowMapper +Transforms the read row from excel into a `String[]`. + +### DefaultRowMapper +Tries to convert the given row into an object, for this a `org.springframework.batch.item.excel.transform.RowTokenizer` and a `org.springframework.batch.item.file.mapping.FieldSetMapper` (from [the Spring Batch project](http://docs.spring.io/spring-batch/2.2.x/reference/html/readersAndWriters.html#fieldSetMapper)) is needed. + +By default the `org.springframework.batch.item.excel.transform.DefaultRowTokenizer` is used. This implementation assumes that the first row contains the column names. The column names are used to map to attributes on the object we are trying to create. How this mapping is done is configurable through a `org.springframework.batch.item.excel.transform.ColumnToAttributeConverter` implementation. +Again 2 implementations are provided by the framework + +- `org.springframework.batch.item.excel.transform.PassThroughColumnToAttributeConverter` +- `org.springframework.batch.item.excel.transform.MappingColumnToAttributeConverter` + +The `PassThroughColumnToAttributeConverter` simply assumes that the column name corresponds to a property on the object that is being created. +The `MappingColumnToAttributeConverter` contains a (optional) column-name to property-name mapping. diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/AbstractExcelItemReader.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/AbstractExcelItemReader.java index c329b19..4461968 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/AbstractExcelItemReader.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/AbstractExcelItemReader.java @@ -35,6 +35,7 @@ import java.io.InputStream; * * @param the type * @author Marten Deinum + * @since 1.1.0 */ public abstract class AbstractExcelItemReader extends AbstractItemCountingItemStreamItemReader implements ResourceAwareItemReaderItemStream, InitializingBean { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/ExcelFileParseException.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/ExcelFileParseException.java index 21283b2..e1fd5f9 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/ExcelFileParseException.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/ExcelFileParseException.java @@ -23,7 +23,7 @@ import org.springframework.batch.item.ParseException; * simply dependencies to make it is generic as possible. * * @author Marten Deinum - * + * @since 1.0.0 */ public class ExcelFileParseException extends ParseException { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowCallbackHandler.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowCallbackHandler.java index 450e611..dbc4c63 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowCallbackHandler.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowCallbackHandler.java @@ -20,6 +20,7 @@ package org.springframework.batch.item.excel; * Callback to handle skipped lines. Useful for header/footer processing. * * @author Marten Deinum + * @since 1.1.0 */ public interface RowCallbackHandler { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowMapper.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowMapper.java index 6001450..9f0c8db 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowMapper.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/RowMapper.java @@ -19,6 +19,7 @@ package org.springframework.batch.item.excel; * Map rows from an excel sheet to an object. * * @author Marten Deinum + * @since 1.0.0 * * @param */ diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/Sheet.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/Sheet.java index 248cc6f..4eef9cb 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/Sheet.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/Sheet.java @@ -19,6 +19,7 @@ package org.springframework.batch.item.excel; * Interface to wrap different Excel implementations like JExcel, JXL or Apache POI. * * @author Marten Deinum + * @since 1.0.0 * */ public interface Sheet { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlItemReader.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlItemReader.java index 4215160..79f9ab1 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlItemReader.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlItemReader.java @@ -30,7 +30,8 @@ import org.springframework.util.ClassUtils; * the {@link org.springframework.batch.item.file.FlatFileItemReader} * * @author Marten Deinum - * + * @since 1.0.0 + * * @param the type */ public class JxlItemReader extends AbstractExcelItemReader { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlSheet.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlSheet.java index 9867cbb..42449b8 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlSheet.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlSheet.java @@ -24,7 +24,7 @@ import org.springframework.batch.item.excel.Sheet; * {@link org.springframework.batch.item.excel.Sheet} implementation for JXL. * * @author Marten Deinum - * + * @since 1.0.0 */ public class JxlSheet implements Sheet { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlUtils.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlUtils.java index 6f67c8f..d2d55c5 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlUtils.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/jxl/JxlUtils.java @@ -27,7 +27,7 @@ import java.util.List; * Class containing utility methods to work with JXL. * * @author Marten Deinum - * + * @since 1.0.0 */ public final class JxlUtils { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/DefaultRowMapper.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/DefaultRowMapper.java index 1155445..351d614 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/DefaultRowMapper.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/DefaultRowMapper.java @@ -30,6 +30,7 @@ import org.springframework.util.Assert; * of fields and construction of objects. * * @author Marten Deinum + * @since 1.0.0 * * @param */ diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/PassThroughRowMapper.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/PassThroughRowMapper.java index ef1cc36..c5075ea 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/PassThroughRowMapper.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/mapping/PassThroughRowMapper.java @@ -23,7 +23,8 @@ import org.springframework.batch.item.excel.Sheet; * back directly rather than a mapped object. * * @author Marten Deinum - * + * @since 1.0.0 + * */ public class PassThroughRowMapper implements RowMapper { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiItemReader.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiItemReader.java index 90c4eec..ace4529 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiItemReader.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiItemReader.java @@ -28,6 +28,7 @@ import org.springframework.core.io.Resource; * the {@link org.springframework.batch.item.file.FlatFileItemReader} * * @author Marten Deinum + * @since 1.2.0 * * @param the type */ diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiSheet.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiSheet.java index ea38de3..0a8502e 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiSheet.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/poi/PoiSheet.java @@ -28,7 +28,7 @@ import java.util.List; * Sheet implementation for Apache POI. * * @author Marten Deinum - * + * @since 1.2.0 */ public class PoiSheet implements Sheet { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/ColumnToAttributeConverter.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/ColumnToAttributeConverter.java index 1779c7b..708c106 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/ColumnToAttributeConverter.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/ColumnToAttributeConverter.java @@ -18,6 +18,7 @@ * Convert a column name to an attribute name and vice versa. * * @author Marten Deinum + * @since 1.0.0 */ public interface ColumnToAttributeConverter { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/DefaultRowTokenizer.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/DefaultRowTokenizer.java index 56463b1..812fe2f 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/DefaultRowTokenizer.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/DefaultRowTokenizer.java @@ -27,6 +27,7 @@ import org.springframework.util.StringUtils; * {@link RowTokenizer} which assumes the column names are on the first row in the sheet. * * @author Marten Deinum + * @since 1.0.0 */ public class DefaultRowTokenizer implements RowTokenizer, InitializingBean { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/MappingColumnToAttributeConverter.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/MappingColumnToAttributeConverter.java index 649454a..417a796 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/MappingColumnToAttributeConverter.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/MappingColumnToAttributeConverter.java @@ -25,6 +25,7 @@ import java.util.Map; * configuration. If a mapping cannot be found it returns the name as is. * * @author Marten Deinum + * @since 1.0.0 */ public class MappingColumnToAttributeConverter implements ColumnToAttributeConverter { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/PassThroughColumnToAttributeConverter.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/PassThroughColumnToAttributeConverter.java index 398e93a..1e6b654 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/PassThroughColumnToAttributeConverter.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/PassThroughColumnToAttributeConverter.java @@ -19,6 +19,7 @@ package org.springframework.batch.item.excel.transform; * {@link ColumnToAttributeConverter} which simply returns the given value. * * @author Marten Deinum + * @since 1.0.0 */ public class PassThroughColumnToAttributeConverter implements ColumnToAttributeConverter { diff --git a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/RowTokenizer.java b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/RowTokenizer.java index 8603989..865b58b 100644 --- a/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/RowTokenizer.java +++ b/spring-batch-excel/src/main/java/org/springframework/batch/item/excel/transform/RowTokenizer.java @@ -22,8 +22,8 @@ import org.springframework.batch.item.file.transform.FieldSet; * Interface that is used by framework to convert a Cell[] into a {@link org.springframework.batch.item.file.transform.FieldSet}. * * @author Marten Deinum + * @since 1.0.0 */ - public interface RowTokenizer { FieldSet tokenize(Sheet sheet, String[] row);