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
- 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);
convertArray
protected Object convertArray(Object value)
Returns the value unchanged.
- convertArray in interface AbstractConverter
value
- The value to convert
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 unchangedNumber
, Boolean
and java.util.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.
type
- The type to convert the value tovalue
- value to be converted
convertToString
protected String convertToString(Object value)
throws Throwable
Handles conversion to a String.
- convertToString in interface AbstractConverter
value
- The value to be converted.
- the converted String value.
convertToType
protected Object convertToType(Class type,
Object value)
throws Throwable
Handles conversion to an array of the specified type.
- convertToType in interface AbstractConverter
type
- The type to which this value should be converted.value
- The input value to be converted.
getDefault
protected Object getDefault(Class type)
Return the default value for conversions to the specified
type.
- getDefault in interface AbstractConverter
type
- Data type to which this value should be converted.
- 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.
type
- The type to convert the value tovalue
- String value to be parsed
setAllowedChars
public void setAllowedChars(char[] allowedChars)
Set the allowed characters to be used for parsing a delimited String.
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.
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.
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.
- toString in interface AbstractConverter
- A String representation of this array converter