CSVObjects

Introduction

CSVObjects (earlier known as CSVParser) is a Java library and framework for parsing CSV
(Comma Separated Value) files, and populating user defined Java Bean attributes from the CSV field values.

The framework is based on declarative configuration of the mapping of the CSV fields to the users' Java bean objects.
This is performed via a csv-mapping.xml.

The mapping XML is maintained as committed resources and verified against custom @csv.* JavaDoc tags in source.

The project is distributed under the GNU General Public License, version 2 or later. See the LICENSE file for details.

Installation

CSVObjects 4.0.0 requires JDK 17 or newer, and is published to Maven Central
under the org.csvobjects group.

Maven

<dependency>
    <groupId>org.csvobjects</groupId>
    <artifactId>csvobjects</artifactId>
    <version>4.0.0</version>
</dependency>

Gradle

implementation 'org.csvobjects:csvobjects:4.0.0'

Apache Commons CSV is pulled in transitively as a runtime dependency.

Prior to 4.0.0, the library was distributed manually via GitHub Releases
under the net.sf.anupam package/groupId; see the
GitHub releases page if
you need one of those older artifacts.

Build from source (Maven)

Maven is the build system for this repository.

1. Use JDK 17+ (maven.compiler.release=17) and the included Maven wrapper.
2. Use Maven goals:
3. ./mvnw test for compile + tests.
4. ./mvnw verify for full verification.
5. ./mvnw verify -Pcheckstyle for Checkstyle reporting with default Google
   checks (gated on error-severity findings; naming/style checks are
   warning-severity and remain visible but non-blocking).
6. ./mvnw verify -Pdocs for Javadoc jar generation with custom taglets.
7. ./mvnw deploy -Prelease,docs for maintainers cutting a signed release
   to Maven Central (requires a GPG key and Central Portal credentials;
   see .github/workflows/release.yml).

Metadata parity is validated by tests using:

• org.csvobjects.csv.testsupport.tools.MappingMetadataVerifier

Canonical committed metadata resources:

• src/main/resources/csv-mapping.xml
• src/main/resources/org/csvobjects/csv/formatters/csv-formatter-config.xml

Usage

Place csv-mapping.xml at the root of your application's classpath. Define
your bean mappings there, then create a parser by mapping name:

void printEmployees() throws java.io.FileNotFoundException {
    CSVParserFactory factory = CSVParserFactory.getSingleton();

    try (CSVParser parser =
            factory.getCSVParser("employeeBean", "employees.csv", false)) {
        for (Object bean : parser) {
            Employee employee = (Employee) bean;
            System.out.println(employee.getFirstName());
        }
    }
}

The current release's Javadocs are available at
https://csvobjects.org/docs/api/.

Community

The canonical public repository is
evolve75/csvobjects. Contributions
are welcome through GitHub issues and pull requests.

Support

Report bugs, request features, and ask support questions through the
GitHub issue tracker.

What happened to CSVParser?

The project was originally published as CSVParser and was renamed CSVObjects
to better describe its mapping of CSV records into Java objects.

Project history

CSVObjects began life on SourceForge as the
csvparser project, under the
Java package and Maven groupId prefix net.sf.anupam. The SourceForge
project page now points visitors here. The package/groupId was renamed to
org.csvobjects in the 4.0.0 release, matching the project's current domain
and satisfying Maven Central's namespace-ownership requirement; see
CHANGELOG.md for the full list of 4.0.0 changes.