com.opencsv.bean

Annotation Type CsvBindAndSplitByName

@Documented
 @Retention(value=RUNTIME)
 @Target(value=FIELD)
 @Repeatable(value=CsvBindAndSplitByNames.class)
public @interface CsvBindAndSplitByName

This annotation interprets one field of the input as a collection that will be split up into its components and assigned to a collection-based bean field.

Since:

4.2

Author:

Andrew Rucker Jones

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
Class<?>	elementType Defines what type the elements of the collection should have.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	capture If this is anything but an empty string, it will be used as a regular expression to extract part of the input before conversion to the bean field.
Class<? extends Collection>	collectionType Defines the class used for the collection.
String	column If not specified, the name of the column must be identical to the name of the field.
Class<? extends AbstractCsvConverter>	converter Once the input has been split, a custom converter can optionally be specified for conversion of each of the data points.
String	format If this is anything but an empty string, it will be used as a format string for String.format(String, Object...) on writing.
String	locale Defines the locale to be used for decoding the argument.
String[]	profiles A profile can be used to annotate the same field differently for different inputs or outputs.
boolean	required Whether or not the annotated field is required to be present in every data set of the input.
String	splitOn Defines a regular expression for splitting the input.
String	writeDelimiter When writing a collection from a bean, this string will be used to separate elements of the collection.
String	writeLocale The locale for writing.
boolean	writeLocaleEqualsReadLocale Whether or not the same locale is used for writing as for reading.

Element Detail

elementType

public abstract Class<?> elementType

Defines what type the elements of the collection should have. It is necessary to instantiate elements of the collection, and it is not always possible to determine the type of the given collection at runtime. A perfect example of this is List<? extends Number>.

Returns:

The type of the collection elements

required

public abstract boolean required

Whether or not the annotated field is required to be present in every data set of the input. This means that the input cannot be empty. The output after conversion is not guaranteed to be non-empty. "Input" means the string from the field in the CSV file on reading and the bean member variable on writing.

Returns:

If the field is required to contain information.

Default:

false

column

public abstract String column

If not specified, the name of the column must be identical to the name of the field.

Returns:

The name of the column in the CSV file from which this field should be taken.

Default:

""

locale

public abstract String locale

Defines the locale to be used for decoding the argument.

If not specified, the current default locale is used. The locale must be one recognized by Locale. Locale conversion is supported for the following data types:

• byte and Byte
• float and Float
• double and Double
• int and Integer
• long and Long
• short and Short
• BigDecimal
• BigInteger
• All time data types supported by CsvDate

The locale must be in a format accepted by Locale.forLanguageTag(java.lang.String)

Caution must be exercised with the default locale, for the default locale for numerical types does not mean the locale of the running program, such as en-US or de-DE, but rather no locale. Numbers will be parsed more or less the way the Java compiler would parse them. That means, for instance, that thousands separators in long numbers are not permitted, even if the locale of the running program would accept them. When dealing with locale-sensitive data, it is always best to specify the locale explicitly.

Returns:

The locale selected. The default is indicated by an empty string.

Default:

""

writeLocaleEqualsReadLocale

public abstract boolean writeLocaleEqualsReadLocale

Whether or not the same locale is used for writing as for reading. If this is true, locale() is used for both reading and writing and writeLocale() is ignored.

Returns:

Whether the read locale is used for writing as well

Since:

5.0

Default:

true

writeLocale

public abstract String writeLocale

The locale for writing. This field is ignored unless writeLocaleEqualsReadLocale() is false. The format is identical to locale().

Returns:

The locale for writing, if one is in use

Since:

5.0

See Also:

locale(), writeLocaleEqualsReadLocale()

Default:

""

splitOn

public abstract String splitOn

Defines a regular expression for splitting the input. The input string is split using the value of this attribute and the result is put into a collection. The default splits on whitespace.

Returns:

The regular expression used for splitting the input

Default:

"\\s+"

writeDelimiter

public abstract String writeDelimiter

When writing a collection from a bean, this string will be used to separate elements of the collection. Defaults to one space.

Returns:

Delimiter between elements for writing a collection

Default:

" "

collectionType

public abstract Class<? extends Collection> collectionType

Defines the class used for the collection.

This must be a specific implementation of a collection, and not an interface! The default is set to Collection.class as a signal to use the default for the interface supplied in the bean to be populated.

The logic for determining which class to instantiate for the collection is as follows. In all cases, the implementation must have a nullary constructor.

1. If the bean declares a specific implementation instead of the associated interface (e.g. ArrayList vs. List), that specific implementation will always be used.
2. Otherwise, the implementation named in this field will be used, if it is not an interface.
3. If no implementation is specified in this field (i.e. if an interface is specified, as is the default), a default is used based on the interface of the bean field annotated. These are:
   • ArrayList for Collection
   • ArrayList for List
   • HashSet for Set unless elementType() is an enumeration type, in which case EnumSet is used
   • TreeSet for SortedSet
   • TreeSet for NavigableSet
   • ArrayDeque for Queue
   • ArrayDeque for Deque
   • HashBag for Bag
   • TreeBag for SortedBag

Returns:

A class implementing Collection

Default:

java.util.Collection.class

converter

public abstract Class<? extends AbstractCsvConverter> converter

Once the input has been split, a custom converter can optionally be specified for conversion of each of the data points.

Returns:

The converter applied to each of the data points extracted from the input

Since:

4.3

Default:

com.opencsv.bean.AbstractCsvConverter.class

capture

public abstract String capture

If this is anything but an empty string, it will be used as a regular expression to extract part of the input before conversion to the bean field.

An empty string behaves as if the regular expression ^(.*)$ had been specified.

The regular expression will be compiled and every field of input will be passed through it, naturally after the input has been normalized (quotations and escape characters removed). The first capture group will be extracted, and that string will be passed on to the appropriate conversion routine for the bean field in question.

This makes it possible to easily convert input fields with forms like Grade: 94.2 into 94.2, which can then be converted to a floating point bean field, all without writing a custom converter.

In the case of splitting the input, which is what this annotation does, the input will be split before this regular expression is then applied to every element of the list resulting from splitting the input. This regular expression is not applied to the entire input field before splitting.

The regular expression is applied to the entire string in question (i.e. with Matcher.matches()), instead of just the beginning of the string (Matcher.lookingAt()) or anywhere in the string (Matcher.find()). If it fails to match, the input string is passed unchanged to the appropriate conversion routine for the bean field. The reason for this is two-fold:

1. The matching may occur against an empty string. If the field is not required, this is legitimate, but it's likely the regular expression is not written to accommodate this possibility, and it may indeed not be at all desirable to.
2. If there is an error in either the regular expression or the input that causes the match to fail, there is a good likelihood that the subsequent conversion will fail with a CsvDataTypeMismatchException if the input is not being converted into a simple string.

This is the inverse operation of format().

Returns:

A regular expression, the first capture group of which will be used for conversion to the bean field

Since:

4.3

Default:

""

format

public abstract String format

If this is anything but an empty string, it will be used as a format string for String.format(String, Object...) on writing.

An empty string behaves as if the format string "%s" had been specified.

The format string, if it is not empty, should contain one and only one %s, which will be replaced by the string value of the bean field after conversion. If, however, the bean field is empty, then the output will be empty as well, as opposed to passing an empty string to this format string and using that as the output.

This formatting will be applied to every element of the input collection separately before writing.

This is the inverse operation of capture().

Returns:

A format string for writing fields

Since:

4.3

Default:

""

profiles

public abstract String[] profiles

A profile can be used to annotate the same field differently for different inputs or outputs.

Perhaps you have multiple input sources, and they all use different header names or positions for the same data. With profiles, you don't have to create different beans with the same fields and different annotations for each input. Simply annotate the same field multiple times and specify the profile when you parse the input.

The same applies to output: if you want to be able to represent the same data in multiple CSV formats (that is, with different headers or orders), annotate the bean fields multiple times with different profiles and specify which profile you want to use on writing.

Results are undefined if profile names are not unique.

If the same configuration applies to multiple profiles, simply list all applicable profile names here. This parameter is an array of strings.

The empty string, which is the default value, specifies the default profile and will be used if no annotation for the specific profile being used can be found, or if no profile is specified.

Returns:

The names of the profiles this configuration is for

Since:

5.4

Default:

""