opencsv 5.12.0 · com.opencsv.bean.CsvBindAndSplitByName

Method Summary

Modifier and Type	Method and Description
public String	Returns: A regular expression, the first capture group of which will be used for conversion to the bean field 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.
public Class<? extends Collection<E>>	Returns: A class implementing `java.util.Collection` collectionType() Defines the class used for the collection.
public String	Returns: The name of the column in the CSV file from which this field should be taken. column() If not specified, the name of the column must be identical to the name of the field.
public Class<? extends AbstractCsvConverter>	Returns: The converter applied to each of the data points extracted from the input converter() Once the input has been split, a custom converter can optionally be specified for conversion of each of the data points.
public Class<?>	Returns: The type of the collection elements elementType() Defines what type the elements of the collection should have.
public String	Returns: A format string for writing fields format() If this is anything but an empty string, it will be used as a format string for `java.lang.String#format(String, Object...)` on writing.
public String	Returns: The locale selected. The default is indicated by an empty string. locale() Defines the locale to be used for decoding the argument.
public String[]	Returns: The names of the profiles this configuration is for profiles() A profile can be used to annotate the same field differently for different inputs or outputs.
public boolean	Returns: If the field is required to contain information. required() Whether or not the annotated field is required to be present in every data set of the input.
public String	Returns: The regular expression used for splitting the input splitOn() Defines a regular expression for splitting the input.
public String	Returns: Delimiter between elements for writing a collection writeDelimiter() When writing a collection from a bean, this string will be used to separate elements of the collection.
public String	Returns: The locale for writing, if one is in use writeLocale() The locale for writing.
public boolean	Returns: Whether the read locale is used for writing as well writeLocaleEqualsReadLocale() Whether or not the same locale is used for writing as for reading.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

capture back to summary

capture	back to summary
public 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: 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. 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 `com.opencsv.exceptions.CsvDataTypeMismatchException` if the input is not being converted into a simple string. This is the inverse operation of `format()`. Returns:String A regular expression, the first capture group of which will be used for conversion to the bean field Since 4.3

public 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:

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.
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 com.opencsv.exceptions.CsvDataTypeMismatchException if the input is not being converted into a simple string.

This is the inverse operation of format().

Returns:String: A regular expression, the first capture group of which will be used for conversion to the bean field
Since: 4.3

collectionType back to summary

collectionType	back to summary
public Class<? extends Collection<E>> 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. If the bean declares a specific implementation instead of the associated interface (e.g. `java.util.ArrayList` vs. `java.util.List`), that specific implementation will always be used. Otherwise, the implementation named in this field will be used, if it is not an interface. 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: `java.util.ArrayList` for `java.util.Collection` `java.util.ArrayList` for `java.util.List` `java.util.HashSet` for `java.util.Set` unless `elementType()` is an enumeration type, in which case `java.util.EnumSet` is used `java.util.TreeSet` for `java.util.SortedSet` `java.util.TreeSet` for `java.util.NavigableSet` `java.util.ArrayDeque` for `java.util.Queue` `java.util.ArrayDeque` for `java.util.Deque` `org.apache.commons.collections4.bag.HashBag` for `org.apache.commons.collections4.Bag` `org.apache.commons.collections4.bag.TreeBag` for `org.apache.commons.collections4.SortedBag` Returns:Class<? extends Collection<E>> A class implementing `java.util.Collection`

public Class<? extends Collection<E>> 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.

If the bean declares a specific implementation instead of the associated interface (e.g. java.util.ArrayList vs. java.util.List), that specific implementation will always be used.
Otherwise, the implementation named in this field will be used, if it is not an interface.
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:
- java.util.ArrayList for java.util.Collection
- java.util.ArrayList for java.util.List
- java.util.HashSet for java.util.Set unless elementType() is an enumeration type, in which case java.util.EnumSet is used
- java.util.TreeSet for java.util.SortedSet
- java.util.TreeSet for java.util.NavigableSet
- java.util.ArrayDeque for java.util.Queue
- java.util.ArrayDeque for java.util.Deque
- org.apache.commons.collections4.bag.HashBag for org.apache.commons.collections4.Bag
- org.apache.commons.collections4.bag.TreeBag for org.apache.commons.collections4.SortedBag

Returns:Class<? extends Collection<E>>: A class implementing java.util.Collection

column	back to summary
public String column() If not specified, the name of the column must be identical to the name of the field. Returns:String The name of the column in the CSV file from which this field should be taken.

column

back to summary

public String column()

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

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

converter	back to summary
public 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:Class<? extends AbstractCsvConverter> The converter applied to each of the data points extracted from the input Since 4.3

converter

back to summary

public 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:Class<? extends AbstractCsvConverter>: The converter applied to each of the data points extracted from the input
Since: 4.3

elementType back to summary

elementType	back to summary
public 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:Class<?> The type of the collection elements

public 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:Class<?>: The type of the collection elements

format back to summary

format	back to summary
public String format() If this is anything but an empty string, it will be used as a format string for `java.lang.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:String A format string for writing fields Since 4.3

public String format()

If this is anything but an empty string, it will be used as a format string for java.lang.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:String: A format string for writing fields
Since: 4.3

locale back to summary

locale	back to summary
public 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 `java.util.Locale`. Locale conversion is supported for the following data types: byte and `java.lang.Byte` float and `java.lang.Float` double and `java.lang.Double` int and `java.lang.Integer` long and `java.lang.Long` short and `java.lang.Short` `java.math.BigDecimal` `java.math.BigInteger` All time data types supported by `com.opencsv.bean.CsvDate` The locale must be in a format accepted by `java.util.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:String The locale selected. The default is indicated by an empty string.

public 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 java.util.Locale. Locale conversion is supported for the following data types:

byte and java.lang.Byte
float and java.lang.Float
double and java.lang.Double
int and java.lang.Integer
long and java.lang.Long
short and java.lang.Short
java.math.BigDecimal
java.math.BigInteger
All time data types supported by com.opencsv.bean.CsvDate

The locale must be in a format accepted by java.util.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:String: The locale selected. The default is indicated by an empty string.

profiles	back to summary
public 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:String[] The names of the profiles this configuration is for Since 5.4

profiles

back to summary

public 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:String[]: The names of the profiles this configuration is for
Since: 5.4

required	back to summary
public 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:boolean If the field is required to contain information.

required

back to summary

public 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:boolean: If the field is required to contain information.

splitOn	back to summary
public 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:String The regular expression used for splitting the input

splitOn

back to summary

public 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:String: The regular expression used for splitting the input

writeDelimiter	back to summary
public 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:String Delimiter between elements for writing a collection

writeDelimiter

back to summary

public 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:String: Delimiter between elements for writing a collection

writeLocale back to summary

writeLocale	back to summary
public String writeLocale() The locale for writing. This field is ignored unless `writeLocaleEqualsReadLocale()` is `false`. The format is identical to `locale()`. Returns:String The locale for writing, if one is in use Since 5.0 See Also `locale()`, `writeLocaleEqualsReadLocale()`

public String writeLocale()

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

Returns:String: The locale for writing, if one is in use
Since: 5.0
See Also: locale(), writeLocaleEqualsReadLocale()

writeLocaleEqualsReadLocale back to summary

writeLocaleEqualsReadLocale	back to summary
public 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:boolean Whether the read locale is used for writing as well Since 5.0

public 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:boolean: Whether the read locale is used for writing as well
Since: 5.0

public @Interface CsvBindAndSplitByName

Method Summary

Method Detail