{"id":13485797,"url":"https://github.com/creditdatamw/zerocell","last_synced_at":"2025-04-05T02:11:54.538Z","repository":{"id":27134013,"uuid":"112628388","full_name":"creditdatamw/zerocell","owner":"creditdatamw","description":"Simple, efficient Excel to POJO library for Java ","archived":false,"fork":false,"pushed_at":"2024-12-12T12:31:05.000Z","size":268,"stargazers_count":81,"open_issues_count":3,"forks_count":24,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-29T01:14:34.118Z","etag":null,"topics":["annotation-processor","annotations","excel","java8","pojo"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/creditdatamw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-30T15:35:00.000Z","updated_at":"2025-01-13T15:00:36.000Z","dependencies_parsed_at":"2023-02-16T19:00:47.968Z","dependency_job_id":"cce27bd5-bc23-42b4-bb6d-f2d59c7d1ae5","html_url":"https://github.com/creditdatamw/zerocell","commit_stats":{"total_commits":122,"total_committers":8,"mean_commits":15.25,"dds":"0.38524590163934425","last_synced_commit":"90a33370069a29054058091be26a5f3e0eb22814"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creditdatamw%2Fzerocell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creditdatamw%2Fzerocell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creditdatamw%2Fzerocell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/creditdatamw%2Fzerocell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/creditdatamw","download_url":"https://codeload.github.com/creditdatamw/zerocell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276189,"owners_count":20912288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation-processor","annotations","excel","java8","pojo"],"created_at":"2024-07-31T18:00:31.862Z","updated_at":"2025-04-05T02:11:54.518Z","avatar_url":"https://github.com/creditdatamw.png","language":"Java","readme":"[![](https://img.shields.io/github/license/creditdatamw/zerocell.svg)](./LICENSE)\n[![](https://img.shields.io/maven-central/v/com.creditdatamw.labs/zerocell-core.svg)](http://mvnrepository.com/artifact/com.creditdatamw.labs/zerocell-core)\n\nZeroCell\n========\n\nZeroCell provides a simple API for loading data from Excel sheets into \nPlain Old Java Objects (POJOs) using annotations to map columns from an Excel sheet \nto fields in Java classes. \n\nIn case you don't fancy annotations or don't want to have to change your existing classes, \nyou can map the columns to the fields without the annotations.\n\n## Why should I use this?\n\nThe library doesn't use the same approach that Apache POIs usermodel API and \nother POI based libraries use to process/store data loaded from the Excel file \nas a result it uses less resources as it doesn't process things such as Cell styles that take up memory.\nYou also don't have to spend time setting data from cells to your Java objects, just\ndefine the mappings and let ZeroCell handle the rest.\n\n## What ZeroCell _cannot_ do for you\n\n* Read or process excel workbook styles and other visual effects\n* Load data into complex object hierarchies\n* Write to excel files: The Apache POI library (which we use underneath) has a good API for writing to Excel files and provides the `SXSSFWorkbook` for writing large files in an efficient manner.\n\n## Usage\n\nThere are three ways to use zerocell: via annotations, the programmatic api and using the annotation processor.\n\nFirst things first, add the following dependency to your `pom.xml`\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.creditdatamw.labs\u003c/groupId\u003e\n    \u003cartifactId\u003ezerocell-core\u003c/artifactId\u003e\n    \u003cversion\u003e0.3.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Using Annotations\n\nYou create a class with `@Column` (and optionally `@RowNumber`) \nannotations to represent a row in an Excel sheet and\nthen use the static methods on the `Reader` class to read the \nlist of data from the file.\n\nFor example:\n\n```java\npublic class Person {\n    @RowNumber\n    private int rowNumber;\n    \n    @Column(index=0, name=\"FIRST_NAME\")\n    private String firstName;\n    \n    @Column(index=1, name=\"LAST_NAME\")\n    private String lastName;\n    \n    @Column(index=2, name=\"DATE_OF_BIRTH\")\n    private LocalDate dateOfBirth;\n    \n    // Getters and setters here ...\n    \n    public static void main(String... args) {\n        // Then using the `Reader` class you can load \n        // a list from the excel file as follows:\n        List\u003cPerson\u003e people = Reader.of(Person.class)\n                            .from(new File(\"people.xlsx\"))\n                            .sheet(\"Sheet 1\")\n                            .list();\n        \n        // You can also inspect the column names of \n        // the class using the static `columnsOf` method:\n        String[] columns = Reader.columnsOf(Person.class);    \n    }\n}\n```\n\n### Using the Programmatic API\n\nIf you don't want to use annotations you can still use ZeroCell to load from Excel sheet\nto your Java objects without too much work. The only difference with the annotation approach\n is that you have to define the column mappings via the `Reader.using` method.\n\nFor example:\n\n```java\npublic class Person {\n    private int rowNo;\n    \n    private String id;\n\t\n    private String firstName;\n    \n    private String middleName;\n\t\n    private String lastName;\n    \n    private LocalDate dateOfBirth;\n\t\n    private LocalDate dateOfRegistration;\n    \n    // Getters and setters here ...\n    \n    public static void main(String... args) {\n        // Map the columns using, Reader.using method here\n        List\u003cPerson\u003e people = Reader.of(Person.class)\n                            .from(new File(\"people.xlsx\"))                            \n                            .using(\n                                new RowNumberInfo(\"rowNo\", Integer.class),\n                                new ColumnInfo(\"ID\", \"id\", 0, String.class),\n                                new ColumnInfo(\"FIRST_NAME\", \"firstName\", 1, String.class),\n                                new ColumnInfo(\"MIDDLE_NAME\", \"middleName\", 2, String.class),\n                                new ColumnInfo(\"LAST_NAME\", \"lastName\", 3, String.class),\n                                new ColumnInfo(\"DATE_OF_BIRTH\", \"dateOfBirth\", 4, LocalDate.class),\n                                new ColumnInfo(\"DATE_REGISTERED\", \"dateOfRegistration\", 5, Date.class)\n                            )\n                            .sheet(\"Sheet 1\")\n                            .list();\n         \n        people.forEach(person -\u003e {\n            // Do something with person here    \n        });    \n    }\n}\n```\n\n### Using the Annotation Processor\n\nZeroCell provides an annotation processor to generate Reader \nclasses to read records from Excel without Runtime reflection \nwhich makes the code amenable to better auditing and customization.\n\nIn order to use the functionality you will _need_ to add \nthe `zerocell-processor` dependency to your POM. This adds a compile-time \nannotation processor which generates the classes:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.creditdatamw.labs\u003c/groupId\u003e\n    \u003cartifactId\u003ezerocell-processor\u003c/artifactId\u003e\n    \u003cversion\u003e0.3.2\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\nThen, in your code use the `@ZerocellReaderBuilder` annotation on a class\nthat contains ZeroCell `@Column` annotations.\n\nUsing a class defined as in the example shown below:\n\n```java\npackage com.example;\n\n@ZerocellReaderBuilder\npublic class Person {\n    @RowNumber\n    private int rowNumber;\n    \n    @Column(index=0, name=\"FIRST_NAME\")\n    private String firstName;\n    \n    @Column(index=1, name=\"LAST_NAME\")\n    private String lastName;\n    \n    @Column(index=2, name=\"DATE_OF_BIRTH\")\n    private LocalDate dateOfBirth;\n    \n    public static void main(String... args) {\n        File file = new File(\"people.xlsx\");\n        String sheet = \"Sheet 1\";\n        ZeroCellReader\u003cPerson\u003e reader = new com.example.PersonReader();\n        List\u003cPerson\u003e people = reader.read(file, sheet);\n        people.forEach(person -\u003e {\n            // do something with person\n        });\n    }\n}\n```\n\nGenerates a class in the com.example package\n\n```java\npackage com.example;\n\npublic class PersonReader implements ZeroCellReader {\n  // generated code here\n}\n```\n\n\n## Using Converters\n\nConverters allow you to process the value loaded from an Excel Cell for a \nparticular field, primarily converters enable you to transform String values to \nanother data type. This allows you to load data into fields that have types \nother than the default supported types.\n\nAn example converter is shown below:\n\n```java\npublic class SimpleISOCurrency {\n    public final String isoCurrency;\n    public final double amount;\n\n    public SimpleISOCurrency(String iso, double amount) {\n        assert amount \u003e 0.0;\n        this.isoCurrency = iso;\n        this.amount = amount;\n    }\n}\n\npublic class MalawiKwachaConverter implements Converter\u003cSimpleISOCurrency\u003e {\n    @Override\n    public SimpleISOCurrency convert(String value, String columnName, int row) {\n        return new SimpleISOCurrency(\"MWK\", Double.parseDouble(value));\n    }\n}\n\n// Usage looks like this:\n\n// ...\n@Column(index=1, name=\"Balance (MWK)\", converter=MalawiKwachaConverter.class)\nprivate SimpleISOCurrency balance;\n// ...\n```\n\n### Using converters for pre-processing\n\nYou can also use converters as sort of pre-processing step where you operate on \nthe String from the file before it's set on the field.\n\nBelow is a simple example:\n\n```java\n/**\n * Simple Converter that prefixes values with ID-\n */\npublic class IdPrefixingConverter implements Converter\u003cString\u003e {\n    @Override\n    public String convert(String value, String columnName, int row) {\n        return String.format(\"ID-%s\", value);\n    }\n}\n\n// Usage looks like this:\n\n// ...\n@Column(index=3, name=\"ID No.\", converter=IdPrefixingConverter.class)\nprivate String idNo;\n// ...\n```\n\n### Basic ISO LocalDate Converter\n\nBelow is a simple implementation of an converter for `java.time.LocalDate` that\nyou can use. \n\n\u003e Please note: that if you need to parse date times considering timezones \n\u003e you should implement your own converter and use a type like \n\u003e [OffsetDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/OffsetDateTime.html)\n\n```java\n\npublic class BasicISOLocalDateConverter implements Converter\u003cLocalDate\u003e {\n    /**\n    * Basic ISO converter - attempts to parse a string that is formatted as an\n    * ISO8601 date and convert it to a java.time.LocalDate instance.\n    * \n    * @param value the value to convert\n    * @param column the name of the current column\n    * @param row the current row index\n    * \n    * @throws ZeroCellException if the value cannot be parsed as an ISO date\n    */\n    @Override\n    public LocalDate convert(String value, String column, int row) {\n        if (value == null) return null;\n        DateTimeFormatter formatter = DateTimeFormatter.BASIC_ISO_DATE;\n        try {\n            return LocalDate.parse(value, formatter);\n        } catch (DateTimeParseException e) {\n            throw new ZeroCellException(e);\n        }\n    }\n}\n```\n\n## Loading the Correct Sheet\n\nIf you do not specify the name of the sheet to load from, zerocell attempts to\nload data from the first Sheet in the Workbook. If the Sheet doesn't have matching\ncolumns as the defined model an exception will be thrown. In order to ensure\nthe correct sheet is loaded it is recommended to always specify the sheet name.\n\n## Exception Handling\n\nThe API throws `ZeroCellException` if something goes wrong, e.g. sheet not found. \nIt is an unchecked exception and may cause your code to stop executing if not \nhandled. Typically `ZeroCellException` will wrap another exception, so it's worth \npeeking at the cause using `Exception#getCause`.\n\n## CONTRIBUTING\n\nSee the [`CONTRIBUTING.md`](CONTRIBUTING.md) file for more information.\n\n---\n\nCopyright (c) Credit Data CRB Ltd\n","funding_links":[],"categories":["Projects","项目"],"sub_categories":["Document Processing","文档处理"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreditdatamw%2Fzerocell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcreditdatamw%2Fzerocell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcreditdatamw%2Fzerocell/lists"}