ArrayConverter

Class Overview

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:

• 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 - its 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);
 

Summary

Public Constructors
	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.

Public Methods
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.

Protected Methods
Object	convertArray(Object value) Returns the value unchanged.
Collection	convertToCollection(Class type, Object value) Converts non-array values to a Collection prior to being converted either to an array or a String.
String	convertToString(Object value) Handles conversion to a String.
Object	convertToType(Class type, Object value) Handles conversion to an array of the specified type.
Object	getDefault(Class type) Return the default value for conversions to the specified type.
Class	getDefaultType() Return the default type this Converter handles.

[Expand] Inherited Methods
From class org.apache.commons.beanutils.converters.AbstractConverter Object convert(Class type, Object value) Convert the input object into an output object of the specified type. Object convertArray(Object value) Return the first element from an Array (or Collection) or the value unchanged if not an Array (or Collection). String convertToString(Object value) Convert the input object into a String. abstract Object convertToType(Class type, Object value) Convert the input object into an output object of the specified type. Object getDefault(Class type) Return the default value for conversions to the specified type. abstract Class getDefaultType() Return the default type this Converter handles. Object handleError(Class type, Object value, Throwable cause) Handle Conversion Errors. Object handleMissing(Class type) Handle missing values. boolean isUseDefault() Indicates whether a default value will be returned or exception thrown in the event of a conversion error. void setDefaultValue(Object defaultValue) Set the default value, converting as required. String toString() Provide a String representation of this converter.
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait() final void wait(long arg0, int arg1) final void wait(long arg0)
From interface org.apache.commons.beanutils.Converter abstract Object convert(Class type, Object value) Convert the specified input object into an output object of the specified type.