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:
null
defaultSize
(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, setDefaultValue
public 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 true
protected Class<?> getDefaultType()
Converter
handles.getDefaultType
in class AbstractConverter
Converter
handles.protected String convertToString(Object value) throws Throwable
convertToString
in class AbstractConverter
value
- 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 AbstractConverter
T
- 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 AbstractConverter
value
- The value to convertprotected 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 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 AbstractConverter
type
- Data type to which this value should be converted.public String toString()
toString
in class AbstractConverter
Copyright © 2000–2016 The Apache Software Foundation. All rights reserved.