What is CSVObjects?

CSVObjects is a Java library for parsing and unmarshalling comma-separated values into your own JavaBean classes. It keeps record parsing separate from application code: describe the relationship between columns and bean properties once, then iterate over mapped objects.

Mappings live in a declarative csv-mapping.xml file. They can model nested beans, skip a CSV header, and apply reusable field formatters before values reach bean setters. The parser is read-only and implements Iterable<Object> and AutoCloseable.

CSVObjects requires Java 17 or newer, uses Apache Commons CSV, and is distributed under the GNU GPL version 2 or later.

Getting Started

Install CSVObjects

Download csvobjects-3.0.2.jar from GitHub and add it, along with Apache Commons CSV 1.14.1, to your application's classpath. Source and Javadoc archives are available from the same release. 

curl -LO https://github.com/evolve75/csvobjects/releases/download/R3.0.2/csvobjects-3.0.2.jar

Define a Mapping

Place csv-mapping.xml at the root of your application classpath. Positions are zero-based and attributes name JavaBean properties. 

<csv-mapping>
  <bean-mapping name="employeeBean"
                class="com.example.Employee"
                csvHeader="true">
    <field-mapping name="employeeId"
                   type="java.lang.String"
                   position="0"
                   attribute="employeeId"
                   reformat="none"
                   bean-ref="none"/>
  </bean-mapping>
</csv-mapping>

Parse Records

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.getEmployeeId());
    }
}

See the current Javadocs for the complete parser, mapping, formatter, and exception APIs.

FAQ

Does CSVObjects write CSV files?
No. CSVObjects is intentionally a read-only CSV-to-JavaBean mapping library.
Where does the mapping file go?
The default factory loads csv-mapping.xml from the root of the application classpath.
Can one record populate nested objects?
Yes. A field mapping can reference another configured bean mapping.
Can values be normalized during parsing?
Yes. Field mappings can use configured formatters such as trimming or case conversion.

Support & Security

The latest release is supported. Older releases receive best-effort support. Use the GitHub issue tracker for bug reports, feature requests, and security coordination.

Contributing to CSVObjects

Contributions are welcome through issues and pull requests. Please preserve the library's mapping-driven, read-only behavior and include tests for changes.