@Retention
(
value
=
RUNTIME
)
@Target
(
value
=
FIELD
)
@Repeatable
(
value
=
CsvBindByNames.class
)
public @interface
CsvBindByName
Specifies a binding between a column name of the CSV input and a field in a
bean.
Since:
Author:
Andrew Rucker Jones
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.
String
column
If not specified, the name of the column must be identical to the name
of the field.
String
format
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
writeLocale
The locale for writing.
boolean
writeLocaleEqualsReadLocale
Whether or not the same locale is used for writing as for reading.
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:
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.
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.
public abstract String writeLocale
Returns:
The locale for writing, if one is in use
Since:
See Also:
locale()
,
writeLocaleEqualsReadLocale()
Default:
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.
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()
.
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 is the inverse operation of
capture()
.
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.
