opencsv 5.12.0 · com.opencsv.bean.CsvBindAndJoinByName

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 String	Returns: The name of the column(s) in the CSV file from which this field should be taken. column() A regular expression defining which column names are to be included in this bean field.
public Class<? extends AbstractCsvConverter>	Returns: The converter applied to each of the data points extracted from the input converter() Once the data points have been recovered from the various columns of the input, a custom converter can optionally be specified for conversion of each of the data points before they are joined in a `org.apache.commons.collections4.MultiValuedMap`.
public Class<?>	Returns: The type of the map elements elementType() Defines what type the elements of the map 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 Class<? extends MultiValuedMap<K, V>>	Returns: A class implementing `org.apache.commons.collections4.MultiValuedMap` mapType() Defines the class used for the multi-valued map.
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 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. 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.

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

column	back to summary
public String column() A regular expression defining which column names are to be included in this bean field. If not specified, the name of the column must be identical to the name of the field(s). Since this annotation can combine multiple columns from the input, and they are allowed to have the same name, it is legitimate to let opencsv default to using the field name even with this annotation. Returns:String The name of the column(s) in the CSV file from which this field should be taken.

column

back to summary

public String column()

A regular expression defining which column names are to be included in this bean field. If not specified, the name of the column must be identical to the name of the field(s). Since this annotation can combine multiple columns from the input, and they are allowed to have the same name, it is legitimate to let opencsv default to using the field name even with this annotation.

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

converter back to summary

converter	back to summary
public Class<? extends AbstractCsvConverter> converter() Once the data points have been recovered from the various columns of the input, a custom converter can optionally be specified for conversion of each of the data points before they are joined in a `org.apache.commons.collections4.MultiValuedMap`. Returns:Class<? extends AbstractCsvConverter> The converter applied to each of the data points extracted from the input Since 4.3

public Class<? extends AbstractCsvConverter> converter()

Once the data points have been recovered from the various columns of the input, a custom converter can optionally be specified for conversion of each of the data points before they are joined in a org.apache.commons.collections4.MultiValuedMap.

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 map should have. It is necessary to instantiate elements of the map, and it is not always possible to determine the type of the elements at runtime. A perfect example of this is `Map<String, ? extends Number>`. Returns:Class<?> The type of the map elements

public Class<?> elementType()

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

Returns:Class<?>: The type of the map 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 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 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.

mapType back to summary

mapType	back to summary
public Class<? extends MultiValuedMap<K, V>> mapType() Defines the class used for the multi-valued map. This must be a specific implementation of `org.apache.commons.collections4.MultiValuedMap`, and not an interface! The default is set to `MultiValuedMap.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 multi-valued map 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. `org.apache.commons.collections4.multimap.ArrayListValuedHashMap` vs. `org.apache.commons.collections4.ListValuedMap`), 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: `org.apache.commons.collections4.multimap.ArrayListValuedHashMap` for `org.apache.commons.collections4.MultiValuedMap` `org.apache.commons.collections4.multimap.ArrayListValuedHashMap` for `org.apache.commons.collections4.ListValuedMap` `org.apache.commons.collections4.multimap.HashSetValuedHashMap` for `org.apache.commons.collections4.SetValuedMap` Returns:Class<? extends MultiValuedMap<K, V>> A class implementing `org.apache.commons.collections4.MultiValuedMap`

public Class<? extends MultiValuedMap<K, V>> mapType()

Defines the class used for the multi-valued map.

This must be a specific implementation of org.apache.commons.collections4.MultiValuedMap, and not an interface! The default is set to MultiValuedMap.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 multi-valued map 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. org.apache.commons.collections4.multimap.ArrayListValuedHashMap vs. org.apache.commons.collections4.ListValuedMap), 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:

Returns:Class<? extends MultiValuedMap<K, V>>: A class implementing org.apache.commons.collections4.MultiValuedMap

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 every matching 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 every matching field in the CSV file on reading and the bean member variable on writing.

Returns:boolean: If the field is required to contain information.

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 CsvBindAndJoinByName

Method Summary

Method Detail