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$
  • Field Details

    • defaultType

      private final Class<?> defaultType
    • elementConverter

      private final Converter elementConverter
    • defaultSize

      private int defaultSize
    • delimiter

      private char delimiter
    • allowedChars

      private char[] allowedChars
    • onlyFirstToString

      private boolean onlyFirstToString
  • Constructor Details

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

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

      private List<String> parseElements(Class<?> type, String value)

      Parse an incoming String of the form similar to an array initializer in the Java language into a List individual Strings for each element, according to the following rules.

      • The string is expected to be a comma-separated list of values.
      • The string may optionally have matching '{' and '}' delimiters around the list.
      • Whitespace before and after each element is stripped.
      • Elements in the list may be delimited by single or double quotes. Within a quoted elements, the normal Java escape sequences are valid.
      Parameters:
      type - The type to convert the value to
      value - String value to be parsed
      Returns:
      List of parsed elements.
      Throws:
      ConversionException - if the syntax of svalue is not syntactically valid
      NullPointerException - if svalue is null