org.apache.commons.beanutils.converters

Class ArrayConverter

Implemented Interfaces:
Converter

public class ArrayConverter
extends AbstractConverter

Generic Converter implementaion 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:

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:

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);
 
Version:
$Revision: 555824 $ $Date: 2007-07-13 01:27:15 +0100 (Fri, 13 Jul 2007) $
Since:
1.8.0

Field Summary

private char[]
allowedChars
private int
defaultSize
private char
delimiter
private Converter
elementConverter
private boolean
onlyFirstToString

Fields inherited from class org.apache.commons.beanutils.converters.AbstractConverter

DEFAULT_CONFIG_MSG, PACKAGE, defaultType, defaultValue, log, useDefault

Constructor Summary

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

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 Object
convertToType(Class 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.
private List
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.
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

convert, convertArray, convertToString, convertToType, getDefault, getDefaultType, handleError, handleMissing, isUseDefault, log, primitive, setDefaultValue, toString, toString

Field Details

allowedChars

private char[] allowedChars

defaultSize

private int defaultSize

delimiter

private char delimiter

elementConverter

private Converter elementConverter

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

convertArray

protected Object convertArray(Object value)
Returns the value unchanged.
Overrides:
convertArray in interface AbstractConverter
Parameters:
value - The value to convert
Returns:
The value unchanged

convertToCollection

protected Collection convertToCollection(Class type,
                                         Object value)
Parameters:
type - The type to convert the value to
value - value to be converted
Returns:
Collection elements.

convertToString

protected String convertToString(Object value)
            throws Throwable
Handles conversion to a String.
Overrides:
convertToString in interface AbstractConverter
Parameters:
value - The value to be converted.
Returns:
the converted String value.

convertToType

protected Object convertToType(Class type,
                               Object value)
            throws Throwable
Handles conversion to an array of the specified type.
Overrides:
convertToType in interface AbstractConverter
Parameters:
type - The type to which this value should be converted.
value - The input value to be converted.
Returns:
The converted value.

getDefault

protected Object getDefault(Class type)
Return the default value for conversions to the specified type.
Overrides:
getDefault in interface AbstractConverter
Parameters:
type - Data type to which this value should be converted.
Returns:
The default value for the specified type.

parseElements

private List 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.

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 '-']

setDelimiter

public void setDelimiter(char delimiter)
Set the delimiter to be used for parsing a delimited String.
Parameters:
delimiter - The delimiter [default ',']

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

toString

public String toString()
Provide a String representation of this array converter.
Overrides:
toString in interface AbstractConverter
Returns:
A String representation of this array converter

Copyright (c) 2001-2007 - Apache Software Foundation