@Documented @Retention(value=RUNTIME) @Target(value=FIELD) @Repeatable(value=CsvBindAndSplitByPositions.class) public @interface CsvBindAndSplitByPosition
Modifier and Type | Required Element and Description |
---|---|
Class<?> |
elementType
Defines what type the elements of the collection should have.
|
int |
position
The column position in the input that is used to fill the annotated
field.
|
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.
|
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.
|
public abstract int position
public abstract Class<?> elementType
List<? extends Number>
.public abstract boolean required
public abstract String locale
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
Float
Double
Integer
Long
Short
BigDecimal
BigInteger
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.
public abstract boolean writeLocaleEqualsReadLocale
locale()
is used for both reading and writing
and writeLocale()
is ignored.public abstract String writeLocale
writeLocaleEqualsReadLocale()
is
false
. The format is identical to locale()
.locale()
,
writeLocaleEqualsReadLocale()
public abstract String splitOn
public abstract String writeDelimiter
public abstract Class<? extends Collection> collectionType
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.
ArrayList
vs.
List
), that specific implementation will always be
used.ArrayList
for Collection
ArrayList
for List
HashSet
for Set
unless
elementType()
is an enumeration type, in which case
EnumSet
is usedTreeSet
for SortedSet
TreeSet
for NavigableSet
ArrayDeque
for Queue
ArrayDeque
for Deque
HashBag
for Bag
TreeBag
for SortedBag
Collection
public abstract Class<? extends AbstractCsvConverter> converter
public abstract String capture
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:
CsvDataTypeMismatchException
if the
input is not being converted into a simple string.This is the inverse operation of format()
.
public abstract String format
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()
.
public abstract String[] profiles
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.
Copyright © 2005–2023. All rights reserved.