org.apache.commons.beanutils.converters

## Class ArrayConverter

- java.lang.Object
- - org.apache.commons.beanutils.converters.AbstractConverter
  - - org.apache.commons.beanutils.converters.ArrayConverter

- All Implemented Interfaces:
    Converter

      public class ArrayConverter
      extends AbstractConverter

  Generic `Converter` implementation that handles conversion to and from array objects.

  Can be configured to either return a default value or throw a `ConversionException` if a conversion error occurs.

  The main features of this implementation are:

  - Element Conversion - delegates to a `Converter`, appropriate for the type, to convert individual elements of the array. This leverages the power of existing converters without having to replicate their functionality for converting to the element type and removes the need to create a specifc array type converters.
  - Arrays or Collections - can convert from either arrays or Collections to an array, limited only by the capability of the delegate `Converter`.
  - Delimited Lists - can Convert to and from a delimited list in String format.
  - Conversion to String - converts an array to a `String` in one of two ways: as a delimited list or by converting the first element in the array to a String - this is controlled by the `setOnlyFirstToString(boolean)` parameter.
  - Multi Dimensional Arrays - it is possible to convert a `String` to a multi-dimensional arrays, by embedding `ArrayConverter` within each other - see example below.
  - Default Value
  - No Default - use the `ArrayConverter(Class, Converter)` constructor to create a converter which throws a `ConversionException` if the value is missing or invalid.
  - Default values - use the `ArrayConverter(Class, Converter, int)` constructor to create a converter which returns a default value. The defaultSize parameter controls the default value in the following way:
  - defaultSize < 0 - default is `null`
  - defaultSize = 0 - default is an array of length zero
  - defaultSize > 0 - default is an array with a length specified by `defaultSize` (N.B. elements in the array will be `null`)

  ### Parsing Delimited Lists

  This implementation can convert a delimited list in `String` format into an array of the appropriate type. By default, it uses a comma as the delimiter but the following methods can be used to configure parsing:
  - `setDelimiter(char)` - allows the character used as the delimiter to be configured [default is a comma].
  - `setAllowedChars(char[])` - adds additional characters (to the default alphabetic/numeric) to those considered to be valid token characters.

  ### Multi Dimensional Arrays

  It is possible to convert a `String` to mulit-dimensional arrays by using `ArrayConverter` as the element `Converter` within another `ArrayConverter`.

  For example, the following code demonstrates how to construct a `Converter` to convert a delimited `String` into a two dimensional integer array:

          // Construct an Integer Converter
          IntegerConverter integerConverter = new IntegerConverter();

          // Construct an array Converter for an integer array (i.e. int[]) using
          // an IntegerConverter as the element converter.
          // N.B. Uses the default comma (i.e. ",") as the delimiter between individual numbers
          ArrayConverter arrayConverter = new ArrayConverter(int[].class, integerConverter);

          // Construct a "Matrix" Converter which converts arrays of integer arrays using
          // the pre-ceeding ArrayConverter as the element Converter.
          // N.B. Uses a semi-colon (i.e. ";") as the delimiter to separate the different sets of numbers.
          //      Also the delimiter used by the first ArrayConverter needs to be added to the
          //      "allowed characters" for this one.
          ArrayConverter matrixConverter = new ArrayConverter(int[][].class, arrayConverter);
          matrixConverter.setDelimiter(';');
          matrixConverter.setAllowedChars(new char[] {','});

          // Do the Conversion
          String matrixString = "11,12,13 ; 21,22,23 ; 31,32,33 ; 41,42,43";
          int[][] result = (int[][])matrixConverter.convert(int[][].class, matrixString);

  Since:
    1.8.0
  Version:
    $Id$

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArrayConverter(Class<?> defaultType, Converter elementConverter)` Construct an array `Converter` with the specified component `Converter` that throws a `ConversionException` if an error occurs.
    `ArrayConverter(Class<?> defaultType, Converter elementConverter, int defaultSize)` Construct an array `Converter` with the specified component `Converter` that returns a default array of the specified size (or `null`) if an error occurs.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `convertArray(Object value)` Returns the value unchanged.
    `protected Collection<?>` | `convertToCollection(Class<?> type, Object value)` Converts non-array values to a Collection prior to being converted either to an array or a String.
    `protected String` | `convertToString(Object value)` Handles conversion to a String.
    `protected <T> T` | `convertToType(Class<T> type, Object value)` Handles conversion to an array of the specified type.
    `protected Object` | `getDefault(Class<?> type)` Return the default value for conversions to the specified type.
    `protected Class<?>` | `getDefaultType()` Return the default type this `Converter` handles.
    `void` | `setAllowedChars(char[] allowedChars)` Set the allowed characters to be used for parsing a delimited String.
    `void` | `setDelimiter(char delimiter)` Set the delimiter to be used for parsing a delimited String.
    `void` | `setOnlyFirstToString(boolean onlyFirstToString)` Indicates whether converting to a String should create a delimited list or just convert the first value.
    `String` | `toString()` Provide a String representation of this array converter.

    - ### Methods inherited from class org.apache.commons.beanutils.converters.AbstractConverter

      `conversionException, convert, handleError, handleMissing, isUseDefault, setDefaultValue`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ArrayConverter

          public ArrayConverter(Class<?> defaultType,
                                Converter elementConverter)

      Construct an array `Converter` with the specified component `Converter` that throws a `ConversionException` if an error occurs.
      Parameters:
        `defaultType` - The default array type this `Converter` handles
        `elementConverter` - Converter used to convert individual array elements.

    - #### ArrayConverter

          public ArrayConverter(Class<?> defaultType,
                                Converter elementConverter,
                                int defaultSize)

      Construct an array `Converter` with the specified component `Converter` that returns a default array of the specified size (or `null`) if an error occurs.
      Parameters:
        `defaultType` - The default array type this `Converter` handles
        `elementConverter` - Converter used to convert individual array elements.
        `defaultSize` - Specifies the size of the default array value or if less than zero indicates that a `null` default value should be used.

  - ### Method Detail

    - #### setDelimiter

          public void setDelimiter(char delimiter)

      Set the delimiter to be used for parsing a delimited String.
      Parameters:
        `delimiter` - The delimiter [default ',']

    - #### setAllowedChars

          public void setAllowedChars(char[] allowedChars)

      Set the allowed characters to be used for parsing a delimited String.
      Parameters:
        `allowedChars` - Characters which are to be considered as part of the tokens when parsing a delimited String [default is '.' and '-']

    - #### setOnlyFirstToString

          public void setOnlyFirstToString(boolean onlyFirstToString)

      Indicates whether converting to a String should create a delimited list or just convert the first value.
      Parameters:
        `onlyFirstToString` - `true` converts only the first value in the array to a String, `false` converts all values in the array into a delimited list (default is `true`

    - #### getDefaultType

          protected Class<?> getDefaultType()

      Return the default type this `Converter` handles.
      Specified by:
        `getDefaultType` in class `AbstractConverter`
      Returns:
        The default type this `Converter` handles.

    - #### convertToString

          protected String convertToString(Object value)
                                    throws Throwable

      Handles conversion to a String.
      Overrides:
        `convertToString` in class `AbstractConverter`
      Parameters:
        `value` - The value to be converted.
      Returns:
        the converted String value.
      Throws:
        `Throwable` - if an error occurs converting to a String

    - #### convertToType

          protected <T> T convertToType(Class<T> type,
                                        Object value)
                                 throws Throwable

      Handles conversion to an array of the specified type.
      Specified by:
        `convertToType` in class `AbstractConverter`
      Type Parameters:
        `T` - Target type of the conversion.
      Parameters:
        `type` - The type to which this value should be converted.
        `value` - The input value to be converted.
      Returns:
        The converted value.
      Throws:
        `Throwable` - if an error occurs converting to the specified type

    - #### convertArray

          protected Object convertArray(Object value)

      Returns the value unchanged.
      Overrides:
        `convertArray` in class `AbstractConverter`
      Parameters:
        `value` - The value to convert
      Returns:
        The value unchanged

    - #### convertToCollection

          protected Collection<?> convertToCollection(Class<?> type,
                                                      Object value)

      Converts non-array values to a Collection prior to being converted either to an array or a String.
      - `Collection` values are returned unchanged
      - `Number`, `Boolean` and `Date` values returned as a the only element in a List.
      - All other types are converted to a String and parsed as a delimited list.
      N.B. The method is called by both the `convertToType(Class, Object)` and `convertToString(Object)` methods for non-array types.
      Parameters:
        `type` - The type to convert the value to
        `value` - value to be converted
      Returns:
        Collection elements.

    - #### getDefault

          protected Object getDefault(Class<?> type)

      Return the default value for conversions to the specified type.
      Overrides:
        `getDefault` in class `AbstractConverter`
      Parameters:
        `type` - Data type to which this value should be converted.
      Returns:
        The default value for the specified type.

    - #### toString

          public String toString()

      Provide a String representation of this array converter.
      Overrides:
        `toString` in class `AbstractConverter`
      Returns:
        A String representation of this array converter

Copyright © 2000–2019 The Apache Software Foundation. All rights reserved.