Class ArrayConverter<C>
java.lang.Object
org.apache.commons.beanutils2.converters.AbstractConverter<C>
org.apache.commons.beanutils2.converters.ArrayConverter<C>
- Type Parameters:
- C- The converter type.
- All Implemented Interfaces:
- Converter<C>
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 specific 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 Stringin 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 Stringto a multi-dimensional arrays, by embeddingArrayConverterwithin each other - see example below.
- Default Value
 - No Default - use the ArrayConverter(Class, Converter)constructor to create a converter which throws aConversionExceptionif 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(elements in the array will benull)
 
- defaultSize < 0 - default is 
 
- No Default - use the 
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 multi-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.
 // 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 preceding ArrayConverter as the element Converter.
 // Uses a semicolon (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
- 
Constructor SummaryConstructorsConstructorDescriptionArrayConverter(Class<C> defaultType, Converter elementConverter) Constructs an arrayConverterwith the specified componentConverterthat throws aConversionExceptionif an error occurs.ArrayConverter(Class<C> defaultType, Converter elementConverter, int defaultSize) Constructs an arrayConverterwith the specified componentConverterthat returns a default array of the specified size (ornull) if an error occurs.
- 
Method SummaryModifier and TypeMethodDescriptionprotected ObjectconvertArray(Object value) Returns the value unchanged.protected Collection<?> convertToCollection(Object value) Converts non-array values to a Collection prior to being converted either to an array or a String.protected StringconvertToString(Object value) Handles conversion to a String.protected <T> TconvertToType(Class<T> type, Object value) Handles conversion to an array of the specified type.protected ObjectgetDefault(Class<?> type) Gets the default value for conversions to the specified type.Gets the default type thisConverterhandles.voidsetAllowedChars(char[] allowedChars) Sets the allowed characters to be used for parsing a delimited String.voidsetDelimiter(char delimiter) Sets the delimiter to be used for parsing a delimited String.voidsetOnlyFirstToString(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.beanutils2.converters.AbstractConverterconversionException, convert, handleError, handleMissing, isUseDefault, setDefaultValue, toLowerCase, toString, toTrim
- 
Constructor Details- 
ArrayConverterConstructs an arrayConverterwith the specified componentConverterthat throws aConversionExceptionif an error occurs.- Parameters:
- defaultType- The default array type this- Converterhandles
- elementConverter- Converter used to convert individual array elements.
 
- 
ArrayConverterConstructs an arrayConverterwith the specified componentConverterthat returns a default array of the specified size (ornull) if an error occurs.- Parameters:
- defaultType- The default array type this- Converterhandles
- elementConverter- Converter used to convert individual array elements.
- defaultSize- Specifies the size of the default array value or if less than zero indicates that a- nulldefault value should be used.
 
 
- 
- 
Method Details- 
convertArrayReturns the value unchanged.- Overrides:
- convertArrayin class- AbstractConverter<C>
- Parameters:
- value- The value to convert
- Returns:
- The value unchanged
 
- 
convertToCollectionConverts non-array values to a Collection prior to being converted either to an array or a String.- Collectionvalues are returned unchanged
- Number,- Booleanand- Datevalues 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:
- value- value to be converted
- Returns:
- Collection elements.
 
- 
convertToStringHandles conversion to a String.- Overrides:
- convertToStringin class- AbstractConverter<C>
- Parameters:
- value- The value to be converted.
- Returns:
- the converted String value.
- Throws:
- IllegalArgumentException- if an error occurs converting to a String
 
- 
convertToTypeHandles conversion to an array of the specified type.- Specified by:
- convertToTypein class- AbstractConverter<C>
- 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
 
- 
getDefaultGets the default value for conversions to the specified type.- Overrides:
- getDefaultin class- AbstractConverter<C>
- Parameters:
- type- Data type to which this value should be converted.
- Returns:
- The default value for the specified type.
 
- 
getDefaultTypeGets the default type thisConverterhandles.- Specified by:
- getDefaultTypein class- AbstractConverter<C>
- Returns:
- The default type this Converterhandles.
 
- 
setAllowedCharsSets 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 '-']
 
- 
setDelimiterSets the delimiter to be used for parsing a delimited String.- Parameters:
- delimiter- The delimiter [default ',']
 
- 
setOnlyFirstToStringIndicates whether converting to a String should create a delimited list or just convert the first value.- Parameters:
- onlyFirstToString-- trueconverts only the first value in the array to a String,- falseconverts all values in the array into a delimited list (default is- true
 
- 
toStringProvide a String representation of this array converter.- Overrides:
- toStringin class- AbstractConverter<C>
- Returns:
- A String representation of this array converter
 
 
-