Annotation Type CsvBindAndJoinByName
-
@Documented @Retention(RUNTIME) @Target(FIELD) public @interface CsvBindAndJoinByName
Joins the values of multiple columns from the input into one bean field based on a pattern for the column names.- Since:
- 4.2
- Author:
- Andrew Rucker Jones
-
-
Required Element Summary
Required Elements Modifier and Type Required Element Description java.lang.Class<?>
elementType
Defines what type the elements of the map should have.
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description java.lang.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.java.lang.String
column
A regular expression defining which column names are to be included in this bean field.java.lang.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 aMultiValuedMap
.java.lang.String
format
If this is anything but an empty string, it will be used as a format string forString.format(String, Object...)
on writing.java.lang.String
locale
Defines the locale to be used for decoding the argument.java.lang.Class<? extends org.apache.commons.collections4.MultiValuedMap>
mapType
Defines the class used for the multi-valued map.boolean
required
Whether or not the annotated field is required to be present in every data set of the input.java.lang.String
writeLocale
The locale for writing.boolean
writeLocaleEqualsReadLocale
Whether or not the same locale is used for writing as for reading.
-
-
-
Element Detail
-
elementType
java.lang.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 isMap<String, ? extends Number>
.- Returns:
- The type of the map elements
-
-
-
required
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:
- If the field is required to contain information.
- Default:
- false
-
-
-
column
java.lang.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:
- The name of the column(s) in the CSV file from which this field should be taken.
- Default:
- ""
-
-
-
locale
java.lang.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:
- ""
- byte and
-
-
-
writeLocaleEqualsReadLocale
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 andwriteLocale()
is ignored.- Returns:
- Whether the read locale is used for writing as well
- Since:
- 5.0
- Default:
- true
-
-
-
writeLocale
java.lang.String writeLocale
The locale for writing. This field is ignored unlesswriteLocaleEqualsReadLocale()
isfalse
. The format is identical tolocale()
.- Returns:
- The locale for writing, if one is in use
- Since:
- 5.0
- See Also:
locale()
,writeLocaleEqualsReadLocale()
- Default:
- ""
-
-
-
mapType
java.lang.Class<? extends org.apache.commons.collections4.MultiValuedMap> mapType
Defines the class used for the multi-valued map.This must be a specific implementation of
MultiValuedMap
, and not an interface! The default is set toMultiValuedMap.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.
ArrayListValuedHashMap
vs.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:
ArrayListValuedHashMap
forMultiValuedMap
ArrayListValuedHashMap
forListValuedMap
HashSetValuedHashMap
forSetValuedMap
- Returns:
- A class implementing
MultiValuedMap
- Default:
- org.apache.commons.collections4.MultiValuedMap.class
- If the bean declares a specific implementation instead of the
associated interface
(e.g.
-
-
-
converter
java.lang.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 aMultiValuedMap
.- Returns:
- The converter applied to each of the data points extracted from the input
- Since:
- 4.3
- Default:
- com.opencsv.bean.AbstractCsvConverter.class
-
-
-
capture
java.lang.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
into94.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
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
java.lang.String format
If this is anything but an empty string, it will be used as a format string forString.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:
- A format string for writing fields
- Since:
- 4.3
- Default:
- ""
-
-