5.0 is a major release because it breaks backward compatibility. What do you get for that? Here is a list of the improvements in opencsv 5.0.
- CsvToBean now has a stream() method to allow you to gracefully continue processing your beans if you so choose. Since it bypasses internal copying to a new list, it saves a smidgen of time and space.
- Similarly, StatefulBeanToCsv now accepts a Stream to a new write() method.
- Full support for the Java 8 Time API is included. Conversion to and from all JDK-types that implement TemporalAccessor is included.
- In all annotations that accepted a conversion locale, it is now possible to stipulate a different conversion locale for writing than the one used for reading.
- Similarly, @CsvDate and @CsvNumber can now take a different format for writing than reading.
- A new mapping strategy (FuzzyMappingStrategy) for reading into beans that uses a fuzzy matching algorithm between header names and member variable names to reduce your burden in annotating beans.
- The ability to split mappings from input/output columns to member variables of multiple embedded beans has been added through the annotation @CsvRecurse. One root bean is still necessary.
- If you write beans to a CSV output using the header name mapping strategy without annotations, opencsv will now ignore any field named "serialVersionUID" as long as the bean class implements Serializable.
- You can now instruct opencsv to ignore fields. This can be accomplished with the new annotation @CsvIgnore, or, if you do not have source control over the beans you use, with MappingStrategy.ignoreFields(). This last has a default implementation in the MappingStrategy interface that throws an UnsupportedOperationException, and all relevant builders include methods for feeding this information to the mapping strategy.
- As a byproduct of refactoring the mapping strategies, there is now a base class for mapping strategies that map header names: HeaderNameBaseMappingStrategy. If you have derived a mapping strategy from HeaderColumnNameMappingStrategy or HeaderColumnNameTranslateMappingStrategy, it might be advantageous to you to use this base class.
Here are the things you can expect to encounter during an upgrade and what to do about them.
- Java 8 is now the minimum supported version.
- Everything that was deprecated has been removed.
- All non-essential constructors and CsvToBean.parse() methods have been removed. Please use the builder classes instead.
- IterableCSVToBean and IterableCSVToBeanBuilder have both been removed. CsvToBean itself is iterable; use it instead.
- Scads of methods that had to do with the internal implementation details of a mapping strategy have been removed from the interface MappingStrategy. You probably never needed these anyway if you wrote your own mapping strategy.
- The custom converter SplitOnWhitespace has been removed. Use the "split" parameter to the annotation in question.
- Writing non-annotated beans now produces capitalized headers like the rest of opencsv.
- Introspection has been replaced with Reflection. As a result, writing beans no longer fails if a getter is not available.
- If you created custom converters and declared them with the type parameter for the bean type (e.g. MyConverter<T> extends AbstractBeanField<T>) instead of declaring them with a raw class (e.g. MyConverter extends AbstractBeanField), you will need to add one more type parameter for the type of the index into multivalued fields (e.g. MyConverter<T, I> extends AbstractBeanField<T, I>).
- With the introduction of the LineValidator and RowValidator the following classes will throw CsvValidationException as well as an IOException
- Method signatures have changed in AbstractBeanField. If you have overridden some of the more basic methods in this class, you may have to change your methods appropriately. This will not affect ordinary custom converters.
- Method signatures have changed in AbstractMappingStrategy, and one new abstract method has been added. If you derive a mapping strategy directly from AbstractMappingStrategy, you will have to change your method signatures accordingly, if you overrode any of the affected methods, and you will need to implement loadUnadornedFieldMap() to create the input/output to member variable mapping in the absence of binding annotations.
- The two constructors for StatefulBeanToCsv have a new parameter: the fields to ignore. If you are calling these directly instead of using the builders we provide, you will have to add the last argument. If you are not ignoring any fields, simply pass in null.
And we have a new list of things that we have deprecated and plan to remove in 6.0, as well as what you can do about it.
- MappingStrategy.isAnnotationDriven() is simply no longer necessary. It was always an internal implementation detail that has nothing to do with anything but two specific mapping strategies. We have made it a default method in the interface, so you can remove your code immediately if you have implemented your own mapping strategy.
- LiteralComparator can be replaced by a few Comparators from Apache Commons Collections strung together. See the deprecation note for details.
- CsvToBeanFilter should be replaced with BeanVerifier.