Annotation Type CsvBindByName


  • @Documented
    @Retention(RUNTIME)
    @Target(FIELD)
    public @interface CsvBindByName
    Specifies a binding between a column name of the CSV input and a field in a bean.
    Since:
    3.8
    Author:
    Andrew Rucker Jones
    • 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
      If not specified, the name of the column must be identical to the name of the field.
      java.lang.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.
      java.lang.String locale
      Defines the locale to be used for decoding the argument.
      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

      • 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 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

        java.lang.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

        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:
        ""
      • 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 and writeLocale() is ignored.
        Returns:
        Whether the read locale is used for writing as well
        Since:
        5.0
        Default:
        true
      • 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 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:

        1. 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.
        2. 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 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().

        Returns:
        A format string for writing fields
        Since:
        4.3
        Default:
        ""