CSV files should have header names for all fields in the file, and these can be used to great advantage. By annotating a bean field with the name of the header whose data should be written in the field, opencsv can do all of the matching and copying for you. This also makes you independent of the order in which the headers occur in the file. For data like this:

you could create the following bean:

Here we simply name the fields identically to the header names. After that, reading is a simple job:

This will give you a list of the two beans as defined in the example input file. Note how type conversions to basic data types (wrapped and unwrapped primitives, enumerations, Strings, and java.util.Currency) occur automatically.

Input can get more complicated, though, and opencsv gives you the tools to deal with that. Let’s start with the possibility that the header names can’t be mapped to Java field names:

In this case, we have spaces in the names and one header with a number as the initial character. Other problems can be encountered, such as international characters in header names. Additionally, we would like to require that at least the name be mandatory. For this case, our bean doesn’t look much different:

The code for reading remains unchanged.

Now let’s say that your data for whatever reason look like this:

Someone has included the person’s middle name in the field for the first name. But we really only want the first name. Do we have to write a custom converter? No, friends, there is an easier way:

The capture option to all of the binding annotations (except the custom binding annotations, of course) allows you to tell opencsv just what part of the input field should actually be considered significant. opencsv takes the contents of the first capture group. In this example, we take everything up to but not including the first space and discard the rest. Please read the Javadoc for more details and handling of edge cases.

Not every scribe of CSV files is kind enough to provide header names. This is a no-no, but we’re not here to condemn the authors of poor data exports. Our goal is to provide our users with everything they could possibly need to parse CSV files, no matter how bad, as long as they’re still logically coherent in some way.

To that end, we have also accounted for the possibility that there are no headers, and data must be divined from column position. We will return to our previous input file sans header names:

The bean for these data would be:

Besides that, the annotations behave the same as their header name counterparts.

Enumerations work exactly like regular primitive fields. There is only one more thing to say about them: input is checked against the declared values of the enumeration type without regard to case. On writing, the enumeration value will always be written exactly as declared.

Converting to and from ISO 4217 currency codes via java.util.Currency works exactly like regular primitive fields.

We’ve considered simple data types, but we haven’t considered more complex yet common data types. We have also not considered locales other than the default locale or formatting options beyond those provided by a locale. Here we shall do all of this at the same time. Consider this input file:

The dates are dd.MM.yyyy, the salaries use a dot as the thousands delimiter, and a currency symbol is in use. For this input we create the following bean:

The date is handled with the annotation @CsvDate in addition to the mapping annotation. @CsvDate can take a format string, and incidentally handles all common date-type classes. See the Javadocs for more details. The format of the salary, including thousands separator and currency symbol, are dealt with using a combination of the German locale, one of many countries where the thousands separator is a dot, and @CsvNumber.

CSV files are lists, right? Well, some people like lists within lists. For them, we have the ability to annotate bean fields that are declared to be some type implementing java.util.Collection. When using CsvBindAndSplitByName or CsvBindAndSplitByPosition, one field in the CSV file is taken to be a list of data that are separated by a delimiter of some kind. The input is split along this delimiter and the results are put in a Collection and assigned to the bean field. What kind of Collection? Any kind you want. If opencsv knows it, it instantiates an implementing class for you. If opencsv doesn’t know it, you can educate opencsv. Every reasonable Collection-based interface from the JDK is known, and well as Bag and SortedBag from Apache Commons Collections. Some examples would doubtless illuminate my meaning.

This shows us much of the power of these annotations in a few lines. Let’s take the first field. It is defined to be a Collection of Floats. Note, please, the annotation @CsvBindAndSplitByName (or the equivalent for position) always requires the type of an element of the collection being created. Nothing else is mandatory. In particular, Collection itself has no directly implementing classes, but please note, we didn’t indicate to opencsv which kind of collection we want. opencsv chooses one for us.

The next field is a List of something derived from Number. This is where it becomes apparent why the element type is mandatory — it cannot always be determined. Besides that, in this line we are not satisfied with the List implementation opencsv chooses, so we specify LinkedList with the collectionType parameter to the annotation.

The third field is a SortedSet of dates (when a student was tardy to class). Sorted for convenience, and a set to avoid clerical errors of double entry. For this field we have specified that the string separating elements of this list in the input is one or more semicolons. This string is always interpreted as a regular expression. Interestingly, in case we write these data out to a CSV file later, the elements of the list should be separated with a single semicolon. Perhaps someone is trying to convert the data from a older format or remove redundancies.

The forth field is a list of teachers the student has. This field demonstrates the combination of collection-based fields and custom converters. The converter, which must be derived from AbstractCsvConverter, could look like this:

The corresponding data structure would be:

The final field is simply for student identification.

The input to be mapped to this bean could look like this:

The first student has never been tardy, so that list will be empty (but never null). The school secretary accidentally entered a tardy for the second student twice, but this will be eliminated by the SortedSet.

Let’s say you want to tell opencsv which Collection implementation to use, perhaps because you want to make certain it’s one that will perform better for your usage pattern, or perhaps because you want to use one opencsv knows nothing about, like your own implementation. There are two ways of doing this. We already saw one: specify the implementation you want to use in the annotation with the parameter "collectionType". The only stipulations on the implementing class are that it be public and have a nullary constructor. The other way is to declare the type of the bean field using the implementing class rather than the interface implemented, thus:

Here, instead of declaring List<Integer> myList, we used the implementing class. opencsv will respect this and instantiate the class specified. That class can be parameterized, naturally (e.g. MySuperDuperList<Integer>).

All of the other features you know, love, and depend on, such as a field being required, or support for locales, is equally well supported for Collection-based members.

For details on which subinterfaces of Collection opencsv knows and exactly what implementation opencsv uses for those interfaces if you don’t specify one, see the Javadoc for the annotations CsvBindAndSplitByName or CsvBindAndSplitByPosition.

If Collection-based bean fields were there to split one element into many, MultiValuedMap-based bean fields are there to consolidate many elements into one. What if you have the following input?

The first difficulty you will encounter is that three columns have the same name. The second difficulty is that the number of tracks in the header might increase over time, but you want them all. Both problems are easily solved, as are all problems in the opencsv-world:

The first field is unimportant for this illustration.

The second field is a MultiValuedMap that collects all of the values under all of the columns with the name "Album". If you are not familiar with MultiValuedMap, it is a part of Apache Commons Collections. The first parameter is the index, and the second parameter is the value. In the case of CsvBindAndJoinByName, the index should always be a string. The value should be of a type to which the elementType from the annotation is assignable.

Why would we choose to use such a cumbersome data type as a MultiValuedMap to implement this feature? Why not a simple List and everyone is happy? Two reasons: First, someone will want to know what the header was actually named on reading, and second, opencsv needs to know what the header is named when it writes beans to a CSV file. And really, at least for reading, a MultiValuedMap isn’t that cumbersome: Mostly you will want a list of all values, not caring about which header they were under, and that can simply be had by calling values() on the field.

Back to our topic, the second field will be a MultiValuedMap with exactly one key: "Artist". Under this key, there will be a list with up to three entries, in this case "Michael Jackson", "Lionel Richie" and "Stevie Wonder". It only remains to note that the type of the elements being read must always be specified for the same reason it is necessary for Collection-based bean fields.

The third field sums up most of the rest of the features this annotation provides. As you can see, the definition of the column names is a regular expression. Naturally, the "column" attribute of CsvBindAndJoinByName is always interpreted as a regular expression. In this annotation we have also requested a specific implementation of MultiValuedMap, which opencsv will honor. We have decided that this field is mandatory, which in this case means that at least one matching header must be in the input, and every record must have a non-empty value for at least one of the matching columns. Given the input from above, this MultiValuedMap will have four entries, one for each column, and each of these entries will have a list of one element as its value. The elements will be the track titles.

All of the usual features apply: conversion locale, combination with CsvDate, custom converters as with collection-based fields, and specifying your own implementation of MultiValuedMap either through the annotation or by defining the field with the specific implementation (default implementations for the applicable interface are documented in the Javadoc for CsvBindAndJoinByName). The latter being said, if the MultiValuedMap is already present (and possibly contains values), say through the use of a constructor, it will not be overwritten, but rather added to.

What about precedence? To stay with our running example, what if after extending the number of track titles in the input significantly (which would require no changes to the bean), we hire some junior programmer who doesn’t get it, and he adds the following field to the bean:

What does opencsv do with this? It follows the general computing principle of "specific trumps general": It puts any information found under the header "Track21" into the new field, not the MultiValuedMap. Obviously this doesn’t exist for the sole purpose of creating mistakes; you can use it to your advantage if you want one otherwise matching column to be treated individually.

Since we’re on the topic of precedence, what happens if two regular expressions from CsvBindAndJoinByName match one and the same input header name? Don’t do this. The results are undefined.

While minding the last caveat, it is possible to use this feature to collect everything not otherwise mapped:

There is another way one could possibly use this feature: Let’s say you get input of the same information from two different sources, and for reasons that are beyond your control, they have different header names. Perhaps they are in different languages. In one file, the header is:

And in another file, it’s:

You really don’t want two beans for the same thing. You can simply do this:

The only down side is, you will have to unpack the values with code like:

But wait! That’s not all! Using CsvBindAndJoinByPosition we can do the same thing with input that does not include headers. Let’s just say for the sake of argument that our album example from earlier now no longer includes headers, and that the structure grew over time. Perhaps the first version of the CSV file only included one artist, and the other two fields for artist were added at two different points in time after that. The tracks grew over time as well. So now our input looks like this:

In other words, first the album name, then the first artist, followed by two tracks, then the second artist followed by one more track, then the third artist again followed by one track. The bean for these data would look like this:

The first thing to notice in this example is that we have used CsvBindAndJoinByPosition, which takes a list of zero-based column numbers and ranges as its most important argument. The list is comma-separated, and can include any number of column indices as well as closed (e.g. "3-5") and half-open (e.g. "-5" or "10-") ranges.

The next thing to notice in this example is that for CsvBindAndJoinByPosition, the index type to MultiValuedMap must be Integer. Values are saved under the index of the column position they were found in.

The last thing to notice is that as long as new column positions are added to the end of the file, and these are all new tracks, they will all be placed in the variable "tracks" because the column position definition from the CsvBindAndJoinByPosition annotation defines an open range starting at index 7.

As with a header-based mapping, it is possible to create a mop-up field, if no other fields are mapped with CsvBindAndJoinByPosition, by mapping to a MultiValuedMap using the fully open range expression "-".

Writing with CsvBindAndJoinByName and CsvBindAndJoinByPosition are slightly more complicated. Both include ambiguous information about the source of the data, one in the form of regular expressions, and the other in the form of ranges. Once the data have been read in, there is no way from this information alone to determine which column each header came from. That, as we have already said, is why we use a MultiValuedMap: the index gives us this vital information. That said, it should be obvious that when writing, the MultiValuedMap must be completely filled out for every bean before sending it off to be written. That is, every index that is expected in the output must be present in the map and have at least a null value.

Now, we know that input data can get very messy, so we have provided our users with the ability to deal with the messiest of data by allowing you to define your own custom converters. The custom converters here are used at the level of the entire field, not like the custom converters previously covered in collection-based and MultiValuedMap-based bean fields. Every converter must be derived from AbstractBeanField, must be public, and must have a public nullary constructor. For reading, the convert() method must be overridden. opencsv provides two custom converters in the package com.opencsv.bean.customconverter. These can be useful converters themselves, but they also exist for instructive purposes: If you want to write your own custom converter, look at these for examples of how it’s done.

Let’s use two as illustrations. Let’s say we have the following input file:

In this file we have a list of server clusters. The cluster name comes first, followed by a space-delimited list of names of servers in the cluster. The final field indicates whether the cluster is in production use or not, but the truth value uses German. Here is the appropriate bean, using the custom converters opencsv provides:

More than that is not necessary. If you need boolean values in other languages, take a gander at the code in ConvertGermanToBoolean; Apache BeanUtils provides a slick way of converting booleans.

The corresponding annotations for custom converters based on column position are also provided.

Sometimes we want to split the input into a hierarchy of beans instead of having it all in one flat bean. We can do this with the annotation @CsvRecurse.

Let’s say we have the following input:

We could put all of this in one bean, of course, but we could also create the following beans:

This way, your data can be hierarchical.

If you want to split the data among completely unrelated beans, create a containing bean for the beans you actually need, thus:

Then simply extract the subordinate beans you need after parsing.

opencsv will instantiate the entire hierarchy of subordinate beans while reading data in, even if it does not need a subordinate bean for a particular dataset because all associated input fields are empty. opencsv will, however, always check first to see if the subordinate bean has already been created (by the constructor of the enclosing bean), and will not replace it if it exists. As a result, any subordinate beans must either have an accessible nullary constructor, or they must be created by the enclosing bean.

Access to subordinate beans is accomplished the same way it is in the rest of opencsv: accessor methods where available, and Reflection otherwise.

There may be times when you receive differently formatted input files that nonetheless have the same data, and you will want to map them to the same bean. Here are two example inputs:

This from customer 1:

Compared to this from customer 2:

As you can see, the inputs have mostly the same information, but the formats are incompatible for the purposes of using exactly one bean.

Profiles allow you to resolve these superficial differences and use the same data bean for both inputs. All annotations save CsvRecurse include a "profiles" parameter for this purpose. CsvRecurse does not include the parameter because all annotations in recursively included beans are likewise subject to profile selection.

The bean for our two inputs (and possibly more) could look like this:

To use this, your code might look like this:

The field "surname" is annotated with two CsvBindByName annotations, enclosed in a CsvBindByNames annotation, though the enclosure is optional. The first annotation does not specify any profiles, so it is used when no annotation for a specific profile is found, or when no profile is specified on parsing. It says that the default setting is to find a column named "last name" to bind to the field. The second annotation stipulates it is to be used with the profiles "customer 2" and "customer 5" (whose data we have not seen in this example). It does not name a column, so the typical fallback for header naming is used: the name of the field. In this case, that’s "surname".

The field "name" is annotated with three CsvBindByName annotations. The first does just what one would expect: it binds the field "name" to the column "name" from the input. We don’t have an input like this in our example files, but perhaps such data come from other customers, like customer 5. This annotation does not specify a profile, so it is the default profile. The second annotation is only for the profile "customer 1", and it binds the field to the input column named "first name". The third annotation is similar in function.

The field "initial" is annotated with only one CsvBindByName, which binds the input column "middle initial" to the field. It uses the default profile. This field is also annotated with a CsvIgnore which says the field will be ignored for the profile "customer 2".

The field "salaryInUSD" is annotated with two CsvBindByName annotations that should be self-explanatory by now. It is worth noting, though, that both are connected to one named profile each. If a different profile is specified for parsing, e.g. "customer 5", this field will simply not be bound at all — in other words, it will be ignored. The field is also annotated with two CsvNumber annotations: one each for the profiles specified in the CsvBindByName annotations, as it would happen. The two annotations simply provide different format strings for the input numbers.

The field "heightInCentimeters" has only one CsvBindByName annotation to bind the field to the input column "height" independent of profile (since it is the default profile, and no other binding annotations exist for the field). After that come two CsvNumber annotations that demonstrate the same principle as the binding annotations: the first is for the default profile, the second is only for the profile "customer 2".

Here’s how you can map to a bean based on the field positions in your CSV file:

With a header name mapping strategy, things are even easier. As long as you do not annotate anything in the bean, the header name mapping strategy will assume that all columns may be matched to a member variable of the bean with precisely the same name (save capitalization). Every field is considered optional.

If no annotations of any kind are present, the header name mapping strategy is automatically chosen for you.

If you explicitly specify the mapping strategy FuzzyMappingStrategy, all annotated member variables are respected, if any are present, and if any input fields are left unmapped, they will be mapped to the best non-annotated member variable. "Best" means the closest fuzzy string match between available header names and available member variable names, case insensitive.

If we have the following input header names:

We could write the following bean:

And use this code for reading:

Everything will work like you want it to with a minimum of annotating. Both @CsvBindAndJoinByName() as well as @CsvBindAndSplitByName() will be honored exactly, consuming the headers from the input they are meant to consume. After that, the fuzzy mapping strategy will compute that the header name "first header" is closest to the member variable name "firstHeader", "second header" is closest to "secondHeader", and "mispeling" is closest to "misspelling". The mappings will be initialized appropriately.

The dangers of this mapping strategy should be obvious. Even though the algorithm for computing the closest match is stable, the results might not be obvious to you. If you have headers named "header  1" (with two spaces) and "header 11", and only one member variable named "header1" (perhaps you wish to ignore "header 11" in the input), it is non-deterministic which of the two input columns will be mapped to the member variable "header1". You might accidentally get stuck with the wrong mapping.

A similar problem can arise if the structure of your input data is not stable. If someone else is in control of the input and may add or delete columns at any time, fuzzy mappings that have worked fine for a long time may stop working because the new input file has a better match between header name and member variable.

Finally, if you have headers that should remain unmatched and member variables without annotations that should also remain unmatched, you will have a problem. This mapping strategy will map any unused field to the best unused member variable, no matter how poor the match. If you need to get around this, the best way is to annotate the member variable to be skipped and map it to a fictitious but optional header.

Nonetheless, if you know your data, and a mismapping will not cause catastrophic failure of a critical system, this mapping strategy can save you some burdensome annotating for obvious mappings.

Since this matching strategy only makes sense for reading, it is not supported for writing, but it should behave exactly as HeaderColumnNameMappingStrategy.

    CSVReader c = new CSVReaderBuilder(new FileReader("yourfile.csv"))
                .withCSVParser(new CSVParserBuilder()
                        .withQuoteChar('\'')
                        .withSeparator('\t')
                        .build())
                .withSkipLines(2)
                .build();

     CsvToBean csvToBean = new CsvToBeanBuilder(new FileReader("yourfile.csv"))
       .withSeparator('\t').withQuoteChar('\'').withSkipLines(2).build();

      // List<MyBean> beans comes from somewhere earlier in your code.
      Writer writer = new FileWriter("yourfile.csv");
      HeaderColumnNameMappingStrategy<MyBean> strategy = new HeaderColumnNameMappingStrategyBuilder<MyBean>().build();
      strategy.setType(MyBean.class);
      strategy.setColumnOrderOnWrite(new MyComparator());
      StatefulBeanToCsv beanToCsv = StatefulBeanToCsvBuilder(writer)
         .withMappingStrategy(strategy)
         .build();
      beanToCsv.write(beans);
      writer.close();

public class LineDoesNotHaveForbiddenString implements LineValidator {

    private final String FORBIDDEN_STRING;
    private final String MESSAGE;

    public LineDoesNotHaveForbiddenString(String forbiddenString) {
        this.FORBIDDEN_STRING = forbiddenString;
        this.MESSAGE = "Line should not contain " + forbiddenString;
    }

    @Override
    public boolean isValid(String line) {
        if (line == null || FORBIDDEN_STRING == null) {
            return true;
        }

        return !line.contains(FORBIDDEN_STRING);
    }

    @Override
    public void validate(String line) throws CsvValidationException {
        if (!isValid(line)) {
            throw new CsvValidationException(MESSAGE);
        }
    }

    String getMessage() {
        return MESSAGE;
    }
}

   private static final String BAD = "bad";
   private static final String AWFUL = "awful";
   private LineDoesNotHaveForbiddenString lineDoesNotHaveBadString;
   private LineDoesNotHaveForbiddenString lineDoesNotHaveAwfulString;

   @DisplayName("CSVReader with LineValidator with bad string")
   @Test
   public void readerWithLineValidatorWithBadString() throws IOException {
      String lines = "a,b,c\nd,bad,f\n";
      StringReader stringReader = new StringReader(lines);
      CSVReaderBuilder builder = new CSVReaderBuilder(stringReader);
      CSVReader csvReader = builder
                .withLineValidator(lineDoesNotHaveAwfulString)
                .withLineValidator(lineDoesNotHaveBadString)
                .build();
      assertThrows(CsvValidationException.class, () -> {
            List<String[]> rows = csvReader.readAll();
        });
    }

    private static final Function<String[], Boolean> ROW_MUST_HAVE_THREE_COLUMNS = (x) -> {
        return x.length == 3;
    };
    private static final RowValidator THREE_COLUMNS_ROW_VALIDATOR = new RowFunctionValidator(ROW_MUST_HAVE_THREE_COLUMNS, "Row must have three columns!");

    @DisplayName("CSVReader populates line number of exception thrown by RowValidatorAggregator")
    @Test
    public void readerWithRowValidatorExceptionContainsLineNumber() {
        String lines = "a,b,c\nd,f\n";
        StringReader stringReader = new StringReader(lines);
        CSVReaderBuilder builder = new CSVReaderBuilder(stringReader);
        CSVReader csvReader = builder
                .withRowValidator(THREE_COLUMNS_ROW_VALIDATOR)
                .build();
        try {
            List<String[]> rows = csvReader.readAll();
            fail("Expected a CsvValidationException to be thrown!");
        } catch (CsvValidationException cve) {
            assertEquals(2, cve.getLineNumber());
        } catch (Exception e) {
            fail("Caught an exception other than CsvValidationException!", e);
        }
    }

    @PreAssignmentValidator(validator = MustMatchRegexExpression.class, paramString = "^[0-9]{3,6}$")
    @CsvBindByName(column = "id")
    private int beanId;

 public class BlankColumnsBecomeNull implements RowProcessor {

    @Override
    public String processColumnItem(String column) {
        if (column == null || !column.isEmpty()) {
            return column;
        } else {
            return null;
        }
    }

    @Override
    public void processRow(String[] row) {
        for (int i = 0; i < row.length; i++) {
            row[i] = processColumnItem(row[i]);
        }
    }
 }

    private static RowProcessor ROW_PROCESSOR = new BlankColumnsBecomeNull();
    private static final String LINES = "a,, \n, ,\n";

    @DisplayName("CSVReader with RowProcessor with good string")
    @Test
    public void readerWithRowProcessor() throws IOException, CsvException {

        StringReader stringReader = new StringReader(LINES);
        CSVReaderBuilder builder = new CSVReaderBuilder(stringReader);

        CSVReader csvReader = builder
                .withRowProcessor(ROW_PROCESSOR)
                .build();

        List<String[]> rows = csvReader.readAll();
        assertEquals(2, rows.size());

        String[] row1 = rows.get(0);
        assertEquals(3, row1.length);
        assertEquals("a", row1[0]);
        assertNull(row1[1]);
        assertEquals(" ", row1[2]);

        String[] row2 = rows.get(1);
        assertEquals(3, row2.length);
        assertNull(row2[0]);
        assertEquals(" ", row2[1]);
        assertNull(row2[2]);
    }

public class ConvertEmptyOrBlankStringsToDefault implements StringProcessor {
    String defaultValue;

    @Override
    public String processString(String value) {
        if (value == null || value.trim().isEmpty()) {
            return defaultValue;
        }
        return value;
    }

    @Override
    public void setParameterString(String value) {
        defaultValue = value;
    }
}

    @PreAssignmentProcessor(processor = ConvertEmptyOrBlankStringsToDefault.class, paramString = "31415926")
    @CsvBindByName(column = "big number", capture = "^[A-Za-z ]*value: (.*)$", format = "value: %s")
    private long bigNumber;