public class ArrayConverter extends AbstractConverter
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:
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.Converter.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.String
to a multi-dimensional arrays, by embedding ArrayConverter
within each other - see example below.ArrayConverter(Class, Converter)
constructor to create a converter which throws a
ConversionException if the value is missing or
invalid.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:nulldefaultSize (N.B. elements
in the array will be null)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.
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);
| 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. |
| 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.
|
conversionException, convert, handleError, handleMissing, isUseDefault, setDefaultValuepublic ArrayConverter(Class<?> defaultType, Converter elementConverter)
Converter with the specified
component Converter that throws a
ConversionException if an error occurs.defaultType - The default array type this
Converter handleselementConverter - Converter used to convert
individual array elements.public ArrayConverter(Class<?> defaultType, Converter elementConverter, int defaultSize)
Converter with the specified
component Converter that returns a default
array of the specified size (or null) if an error occurs.defaultType - The default array type this
Converter handleselementConverter - 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.public void setDelimiter(char delimiter)
delimiter - The delimiter [default ',']public void setAllowedChars(char[] allowedChars)
allowedChars - Characters which are to be considered as part of
the tokens when parsing a delimited String [default is '.' and '-']public void setOnlyFirstToString(boolean onlyFirstToString)
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 trueprotected Class<?> getDefaultType()
Converter handles.getDefaultType in class AbstractConverterConverter handles.protected String convertToString(Object value) throws Throwable
convertToString in class AbstractConvertervalue - The value to be converted.Throwable - if an error occurs converting to a Stringprotected <T> T convertToType(Class<T> type, Object value) throws Throwable
convertToType in class AbstractConverterT - Target type of the conversion.type - The type to which this value should be converted.value - The input value to be converted.Throwable - if an error occurs converting to the specified typeprotected Object convertArray(Object value)
convertArray in class AbstractConvertervalue - The value to convertprotected Collection<?> convertToCollection(Class<?> type, Object value)
Collection values are returned unchangedNumber, Boolean and Date
values returned as a the only element in a List.convertToType(Class, Object) and
convertToString(Object) methods for
non-array types.type - The type to convert the value tovalue - value to be convertedprotected Object getDefault(Class<?> type)
getDefault in class AbstractConvertertype - Data type to which this value should be converted.public String toString()
toString in class AbstractConverterCopyright © 2000–2014 The Apache Software Foundation. All rights reserved.