Skip to content

Commit

Permalink
add toc [skip ci]
Browse files Browse the repository at this point in the history
  • Loading branch information
ozlerhakan committed Oct 3, 2020
1 parent 311da05 commit 63144ba
Showing 1 changed file with 20 additions and 12 deletions.
32 changes: 20 additions & 12 deletions README.adoc
Original file line number Diff line number Diff line change
@@ -1,12 +1,20 @@
:toc: macro
:toclevels: 1

= Poiji
:version: v3.0.0


image:https://travis-ci.org/ozlerhakan/poiji.svg?branch=master["Build Status", link="https://travis-ci.org/ozlerhakan/poiji"] image:https://api.codacy.com/project/badge/Grade/6587e90886184da29a1b7c5634695c9d["Codacy code quality", link="https://www.codacy.com/app/ozlerhakan/poiji?utm_source=github.com&utm_medium=referral&utm_content=ozlerhakan/poiji&utm_campaign=Badge_Grade"] image:https://coveralls.io/repos/github/ozlerhakan/poiji/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/github/ozlerhakan/poiji?branch=master"] image:https://img.shields.io/badge/apache.poi-4.1.2-brightgreen.svg[] image:https://app.fossa.com/api/projects/git%2Bgithub.com%2Fozlerhakan%2Fpoiji.svg?type=shield["FOSSA Status", link="https://app.fossa.com/projects/git%2Bgithub.com%2Fozlerhakan%2Fpoiji?ref=badge_shield"] image:https://img.shields.io/badge/license-MIT-blue.svg[]

Poiji is a teeny Java library that provides one way mapping from Excel sheets to Java classes. In a way it lets us convert each row of the specified excel data into Java objects. Poiji uses https://poi.apache.org/[Apache Poi] (the Java API for Microsoft Documents) under the hood to fulfill the mapping process.

[%collapsible]
toc::[]

== How it works


In your Maven/Gradle project, first add the corresponding dependency:

.maven
Expand Down Expand Up @@ -222,7 +230,7 @@ public class Student {
----
<1> With the `ExcelSheet` annotation we are configuring the name of the sheet to read data from. The other sheets will be ignored.

=== Encrypted Excel Files
=== Feature 3

Consider that your excel file is protected with a password, you can define the password via `PoijiOptionsBuilder` to read rows:

Expand All @@ -233,7 +241,7 @@ PoijiOptions options = PoijiOptionsBuilder.settings()
List<Employee> employees = Poiji.fromExcel(new File("employees.xls"), Employee.class, options);
----

=== Feature 3
=== Feature 4

The version `1.11` introduces a new annotation called `ExcelCellName` so that we can read the values by column names directly.

Expand Down Expand Up @@ -307,7 +315,7 @@ public class Person {
}
----

=== Feature 4
=== Feature 5

Your object model may be derived from a super class:

Expand Down Expand Up @@ -356,7 +364,7 @@ Car car = cars.get(0);
// 4
----

=== Feature 5
=== Feature 6

Consider you have a table like below:

Expand Down Expand Up @@ -450,7 +458,7 @@ GroupA firstRowPerson1 = firstRowGroups.getGroupA();
GroupB secondRowPerson2 = firstRowGroups.getGroupB();
----

=== Feature 6
=== Feature 7

As of 1.14, Poiji supports Consumer Interface. As https://github.com/ozlerhakan/poiji/pull/39#issuecomment-409521808[@fmarazita] explained the usage, there are several benefits of having a Consumer:

Expand Down Expand Up @@ -503,7 +511,7 @@ private void dbInsertion(Calculation siCalculation) {
}
----

=== Feature 7
=== Feature 8

Since Poiji 1.19.1, you can create your own casting implementation without relying on the default Poiji casting configuration using the `Casting` interface.

Expand Down Expand Up @@ -541,7 +549,7 @@ Then you can add your custom implementation with the `withCasting` method:
List<Person> people = Poiji.fromExcel(excel, Person.class, options);
----

=== Feature 8
=== Feature 9

Since Poiji 2.3.0, you can annotate a `Map<String, String>` with `@ExcelUnknownCells` to parse all entries,
which are not mapped in any other way (for example by index or by name).
Expand Down Expand Up @@ -588,7 +596,7 @@ This is the excel file we want to parse:
The object corresponding to the first row of the excel sheet then has a map with `{ENCODING=mp3, BITRATE=256}`
and the one for the second row has `{ENCODING=flac, BITRATE=1500}`.

=== Feature 9
=== Feature 10

Poiji 2.7.0 introduced the Option `namedHeaderMandatory`. If set to true, Poiji will check that all field annotated with `@ExcelCellName` must have a corresponding column in the Excel sheet. If any column is missing a `HeaderMissingException` will be thrown.

Expand Down Expand Up @@ -620,7 +628,7 @@ This is the excel file we want to parse:
In the default setting of Poiji (`namedHeaderMandatory=false`), the author field will be null for both objects.
With `namedHeaderMandatory=true`, a `HeaderMissingException` will be thrown.

=== Feature 10
=== Feature 11

As of 2.7.0, we can observe each cell format of a given excel file. Assume that we have an excel file like below:

Expand Down Expand Up @@ -657,7 +665,7 @@ cell10.getFormatIndex()

Now that we know the reason of why we don't see the expected date value, it's because the default format of the date cell is the `mm:ss.0` format with a given index 47, we need to change the default format of index (i.e. `47`). This format was automatically assigned to the cell having a number, but almost certainly with a special style or format. Note that this option should be used for debugging purpose only.

=== Feature 11
=== Feature 12

Using 2.7.0, we can change the default format of a cell using `PoijiNumberFormat`. Recall `feature 10`, we are unable to see the correct cell format what's more the excel file uses another format which we do not want to.

Expand Down Expand Up @@ -686,7 +694,7 @@ model.getDate();

We know that the index 47 uses the format `mm:ss.0` by default in the given excel file, thus we're able to override its format with `mm/dd/yyyy hh.mm aa` using the `putNumberFormat` method.

=== Feature 12
=== Feature 13

Since Poiji 2.8.0, it is possible to read excel properties from xlsx files.
To achieve that, create a class with fields annotated with `@ExcelProperty`.
Expand All @@ -713,7 +721,7 @@ Poiji can only read Text properties from an Excel file, so you have to use a `St
This does not apply to "modified", "lastPrinted" and "created", which are deserialized into a `Date`.


== Feature 13
=== Feature 14

Consider we have a xls or xlsx excel file like below:

Expand Down

0 comments on commit 63144ba

Please sign in to comment.