Class ArrayConverter
java.lang.Object
org.apache.commons.beanutils.converters.AbstractConverter
org.apache.commons.beanutils.converters.ArrayConverter
- All Implemented Interfaces:
Converter
Generic
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:
- 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 thesetOnlyFirstToString(boolean)
parameter. - Multi Dimensional Arrays - it is possible to convert a
String
to a multi-dimensional arrays, by embeddingArrayConverter
within each other - see example below. - Default Value
- No Default - use the
ArrayConverter(Class, Converter)
constructor to create a converter which throws aConversionException
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 benull
)
Parsing Delimited Lists
This implementation can convert a delimited list inString
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 aString
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);
- Since:
- 1.8.0
- Version:
- $Id$
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionArrayConverter
(Class<?> defaultType, Converter elementConverter) Construct an arrayConverter
with the specified componentConverter
that throws aConversionException
if an error occurs.ArrayConverter
(Class<?> defaultType, Converter elementConverter, int defaultSize) Construct an arrayConverter
with the specified componentConverter
that returns a default array of the specified size (ornull
) if an error occurs. -
Method Summary
Modifier and TypeMethodDescriptionprotected 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
<?> Return the default type thisConverter
handles.parseElements
(Class<?> type, String value) Parse an incoming String of the form similar to an array initializer in the Java language into aList
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.toString()
Provide a String representation of this array converter.Methods inherited from class org.apache.commons.beanutils.converters.AbstractConverter
conversionException, convert, handleError, handleMissing, isUseDefault, log, setDefaultValue, toString
-
Field Details
-
defaultType
-
elementConverter
-
defaultSize
private int defaultSize -
delimiter
private char delimiter -
allowedChars
private char[] allowedChars -
onlyFirstToString
private boolean onlyFirstToString
-
-
Constructor Details
-
ArrayConverter
Construct an arrayConverter
with the specified componentConverter
that throws aConversionException
if an error occurs.- Parameters:
defaultType
- The default array type thisConverter
handleselementConverter
- Converter used to convert individual array elements.
-
ArrayConverter
Construct an arrayConverter
with the specified componentConverter
that returns a default array of the specified size (ornull
) if an error occurs.- Parameters:
defaultType
- The default array type thisConverter
handleselementConverter
- Converter used to convert individual array elements.defaultSize
- Specifies the size of the default array value or if less than zero indicates that anull
default value should be used.
-
-
Method Details
-
setDelimiter
public void setDelimiter(char delimiter) Set the delimiter to be used for parsing a delimited String.- Parameters:
delimiter
- The delimiter [default ',']
-
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 '-']
-
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 istrue
-
getDefaultType
Return the default type thisConverter
handles.- Specified by:
getDefaultType
in classAbstractConverter
- Returns:
- The default type this
Converter
handles.
-
convertToString
Handles conversion to a String.- Overrides:
convertToString
in classAbstractConverter
- Parameters:
value
- The value to be converted.- Returns:
- the converted String value.
- Throws:
Throwable
- if an error occurs converting to a String
-
convertToType
Handles conversion to an array of the specified type.- Specified by:
convertToType
in classAbstractConverter
- Type Parameters:
T
- Target type of the conversion.- Parameters:
type
- The type to which this value should be converted.value
- The input value to be converted.- Returns:
- The converted value.
- Throws:
Throwable
- if an error occurs converting to the specified type
-
convertArray
Returns the value unchanged.- Overrides:
convertArray
in classAbstractConverter
- Parameters:
value
- The value to convert- Returns:
- The value unchanged
-
convertToCollection
Converts non-array values to a Collection prior to being converted either to an array or a String.Collection
values are returned unchangedNumber
,Boolean
andDate
values returned as a the only element in a List.- All other types are converted to a String and parsed as a delimited list.
convertToType(Class, Object)
andconvertToString(Object)
methods for non-array types.- Parameters:
type
- The type to convert the value tovalue
- value to be converted- Returns:
- Collection elements.
-
getDefault
Return the default value for conversions to the specified type.- Overrides:
getDefault
in classAbstractConverter
- Parameters:
type
- Data type to which this value should be converted.- Returns:
- The default value for the specified type.
-
toString
Provide a String representation of this array converter.- Overrides:
toString
in classAbstractConverter
- Returns:
- A String representation of this array converter
-
parseElements
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 tovalue
- String value to be parsed- Returns:
- List of parsed elements.
- Throws:
ConversionException
- if the syntax ofsvalue
is not syntactically validNullPointerException
- ifsvalue
isnull
-