ArrayConverter.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.beanutils2.converters;
import java.io.IOException;
import java.io.StreamTokenizer;
import java.io.StringReader;
import java.lang.reflect.Array;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Date;
import java.util.Iterator;
import java.util.List;
import java.util.Objects;
import org.apache.commons.beanutils2.ConversionException;
import org.apache.commons.beanutils2.Converter;
/**
* Generic {@link Converter} implementation that handles conversion to and from <strong>array</strong> objects.
* <p>
* Can be configured to either return a <em>default value</em> or throw a {@code ConversionException} if a conversion error occurs.
* <p>
* The main features of this implementation are:
* <ul>
* <li><strong>Element Conversion</strong> - delegates to a {@link 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.</li>
* <li><strong>Arrays or Collections</strong> - can convert from either arrays or Collections to an array, limited only by the capability of the delegate
* {@link Converter}.</li>
* <li><strong>Delimited Lists</strong> - can Convert <strong>to</strong> and <strong>from</strong> a delimited list in String format.</li>
* <li><strong>Conversion to String</strong> - converts an array to a {@code String} in one of two ways: as a <em>delimited list</em> or by converting the first
* element in the array to a String - this is controlled by the {@link ArrayConverter#setOnlyFirstToString(boolean)} parameter.</li>
* <li><strong>Multi Dimensional Arrays</strong> - it is possible to convert a {@code String} to a multi-dimensional arrays, by embedding {@link ArrayConverter}
* within each other - see example below.</li>
* <li><strong>Default Value</strong>
* <ul>
* <li><strong><em>No Default</em></strong> - use the {@link ArrayConverter#ArrayConverter(Class, Converter)} constructor to create a converter which throws a
* {@link ConversionException} if the value is missing or invalid.</li>
* <li><strong><em>Default values</em></strong> - use the {@link ArrayConverter#ArrayConverter(Class, Converter, int)} constructor to create a converter which
* returns a <em>default value</em>. The <em>defaultSize</em> parameter controls the <em>default value</em> in the following way:
* <ul>
* <li><em>defaultSize < 0</em> - default is {@code null}</li>
* <li><em>defaultSize = 0</em> - default is an array of length zero</li>
* <li><em>defaultSize > 0</em> - default is an array with a length specified by {@code defaultSize} (N.B. elements in the array will be {@code null})</li>
* </ul>
* </li>
* </ul>
* </li>
* </ul>
*
* <h2>Parsing Delimited Lists</h2> This implementation can convert a delimited list in {@code 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:
* <ul>
* <li>{@code setDelimiter(char)} - allows the character used as the delimiter to be configured [default is a comma].</li>
* <li>{@code setAllowedChars(char[])} - adds additional characters (to the default alphabetic/numeric) to those considered to be valid token characters.
* </ul>
*
* <h2>Multi Dimensional Arrays</h2> It is possible to convert a {@code String} to multi-dimensional arrays by using {@link ArrayConverter} as the element
* {@link Converter} within another {@link ArrayConverter}.
* <p>
* For example, the following code demonstrates how to construct a {@link Converter} to convert a delimited {@code String} into a two dimensional integer array:
* </p>
*
* <pre>
* // 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 preceding ArrayConverter as the element Converter.
* // N.B. 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);
* </pre>
*
* @param <C> The converter type.
* @since 1.8.0
*/
public class ArrayConverter<C> extends AbstractConverter<C> {
private final Class<C> defaultType;
private final Converter elementConverter;
private int defaultSize;
private char delimiter = ',';
private char[] allowedChars = { '.', '-' };
private boolean onlyFirstToString = true;
/**
* Constructs an <strong>array</strong> {@code Converter} with the specified <strong>component</strong> {@code Converter} that throws a
* {@code ConversionException} if an error occurs.
*
* @param defaultType The default array type this {@code Converter} handles
* @param elementConverter Converter used to convert individual array elements.
*/
public ArrayConverter(final Class<C> defaultType, final Converter elementConverter) {
Objects.requireNonNull(defaultType, "defaultType");
if (!defaultType.isArray()) {
throw new IllegalArgumentException("Default type must be an array.");
}
this.elementConverter = Objects.requireNonNull(elementConverter, "elementConverter");
this.defaultType = defaultType;
}
/**
* Constructs an <strong>array</strong> {@code Converter} with the specified <strong>component</strong> {@code Converter} that returns a default array of
* the specified size (or {@code null}) if an error occurs.
*
* @param defaultType The default array type this {@code Converter} handles
* @param elementConverter Converter used to convert individual array elements.
* @param defaultSize Specifies the size of the default array value or if less than zero indicates that a {@code null} default value should be used.
*/
public ArrayConverter(final Class<C> defaultType, final Converter elementConverter, final int defaultSize) {
this(defaultType, elementConverter);
this.defaultSize = defaultSize;
C defaultValue = null;
if (defaultSize >= 0) {
defaultValue = (C) Array.newInstance(defaultType.getComponentType(), defaultSize);
}
setDefaultValue(defaultValue);
}
/**
* Returns the value unchanged.
*
* @param value The value to convert
* @return The value unchanged
*/
@Override
protected Object convertArray(final Object value) {
return value;
}
/**
* Converts non-array values to a Collection prior to being converted either to an array or a String.
* <ul>
* <li>{@link Collection} values are returned unchanged</li>
* <li>{@link Number}, {@link Boolean} and {@link java.util.Date} values returned as a the only element in a List.</li>
* <li>All other types are converted to a String and parsed as a delimited list.</li>
* </ul>
*
* <strong>N.B.</strong> The method is called by both the {@link ArrayConverter#convertToType(Class, Object)} and
* {@link ArrayConverter#convertToString(Object)} methods for <em>non-array</em> types.
*
* @param value value to be converted
* @return Collection elements.
*/
protected Collection<?> convertToCollection(final Object value) {
if (value instanceof Collection) {
return (Collection<?>) value;
}
if (value instanceof Number || value instanceof Boolean || value instanceof Date) {
final List<Object> list = new ArrayList<>(1);
list.add(value);
return list;
}
return parseElements(value.toString());
}
/**
* Handles conversion to a String.
*
* @param value The value to be converted.
* @return the converted String value.
* @throws IllegalArgumentException if an error occurs converting to a String
*/
@Override
protected String convertToString(final Object value) {
int size = 0;
Iterator<?> iterator = null;
final Class<?> type = value.getClass();
if (type.isArray()) {
size = Array.getLength(value);
} else {
final Collection<?> collection = convertToCollection(value);
size = collection.size();
iterator = collection.iterator();
}
if (size == 0) {
return (String) getDefault(String.class);
}
if (onlyFirstToString) {
size = 1;
}
// Create a StringBuilder containing a delimited list of the values
final StringBuilder buffer = new StringBuilder();
for (int i = 0; i < size; i++) {
if (i > 0) {
buffer.append(delimiter);
}
Object element = iterator == null ? Array.get(value, i) : iterator.next();
element = elementConverter.convert(String.class, element);
if (element != null) {
buffer.append(element);
}
}
return buffer.toString();
}
/**
* Handles conversion to an array of the specified type.
*
* @param <T> Target type of the conversion.
* @param type The type to which this value should be converted.
* @param value The input value to be converted.
* @return The converted value.
* @throws Throwable if an error occurs converting to the specified type
*/
@Override
protected <T> T convertToType(final Class<T> type, final Object value) throws Throwable {
if (!type.isArray()) {
throw ConversionException.format("%s cannot handle conversion to '%s' (not an array).", toString(getClass()), toString(type));
}
// Handle the source
int size = 0;
Iterator<?> iterator = null;
if (value.getClass().isArray()) {
size = Array.getLength(value);
} else {
final Collection<?> collection = convertToCollection(value);
size = collection.size();
iterator = collection.iterator();
}
// Allocate a new Array
final Class<?> componentType = type.getComponentType();
final Object newArray = Array.newInstance(componentType, size);
// Convert and set each element in the new Array
for (int i = 0; i < size; i++) {
Object element = iterator == null ? Array.get(value, i) : iterator.next();
// TODO - probably should catch conversion errors and throw
// new exception providing better info back to the user
element = elementConverter.convert(componentType, element);
Array.set(newArray, i, element);
}
// This is safe because T is an array type and newArray is an array of
// T's component type
return (T) newArray;
}
/**
* Gets the default value for conversions to the specified type.
*
* @param type Data type to which this value should be converted.
* @return The default value for the specified type.
*/
@Override
protected Object getDefault(final Class<?> type) {
if (type.equals(String.class)) {
return null;
}
final Object defaultValue = super.getDefault(type);
if (defaultValue == null) {
return null;
}
if (defaultValue.getClass().equals(type)) {
return defaultValue;
}
return Array.newInstance(type.getComponentType(), defaultSize);
}
/**
* Gets the default type this {@code Converter} handles.
*
* @return The default type this {@code Converter} handles.
*/
@Override
protected Class<C> getDefaultType() {
return defaultType;
}
/**
* <p>
* Parse an incoming String of the form similar to an array initializer in the Java language into a {@code List} individual Strings for each element,
* according to the following rules.
* </p>
* <ul>
* <li>The string is expected to be a comma-separated list of values.</li>
* <li>The string may optionally have matching '{' and '}' delimiters around the list.</li>
* <li>Whitespace before and after each element is stripped.</li>
* <li>Elements in the list may be delimited by single or double quotes. Within a quoted elements, the normal Java escape sequences are valid.</li>
* </ul>
*
* @param value String value to be parsed
* @return List of parsed elements.
* @throws ConversionException if the syntax of {@code value} is not syntactically valid
* @throws NullPointerException if {@code value} is {@code null}
*/
private List<String> parseElements(String value) {
if (log().isDebugEnabled()) {
log().debug("Parsing elements, delimiter=[" + delimiter + "], value=[" + value + "]");
}
// Trim any matching '{' and '}' delimiters
value = toTrim(value);
if (value.startsWith("{") && value.endsWith("}")) {
value = value.substring(1, value.length() - 1);
}
final String typeName = toString(String.class);
try {
// Set up a StreamTokenizer on the characters in this String
final StreamTokenizer st = new StreamTokenizer(new StringReader(value));
st.whitespaceChars(delimiter, delimiter); // Set the delimiters
st.ordinaryChars('0', '9'); // Needed to turn off numeric flag
st.wordChars('0', '9'); // Needed to make part of tokens
for (final char allowedChar : allowedChars) {
st.ordinaryChars(allowedChar, allowedChar);
st.wordChars(allowedChar, allowedChar);
}
// Split comma-delimited tokens into a List
List<String> list = null;
while (true) {
final int ttype = st.nextToken();
if (ttype == StreamTokenizer.TT_WORD || ttype > 0) {
if (st.sval != null) {
if (list == null) {
list = new ArrayList<>();
}
list.add(st.sval);
}
} else if (ttype == StreamTokenizer.TT_EOF) {
break;
} else {
throw ConversionException.format("Encountered token of type %s parsing elements to '%s'.", ttype, typeName);
}
}
if (list == null) {
list = Collections.emptyList();
}
if (log().isDebugEnabled()) {
log().debug(list.size() + " elements parsed");
}
// Return the completed list
return list;
} catch (final IOException e) {
throw new ConversionException("Error converting from String to '" + typeName + "': " + e.getMessage(), e);
}
}
/**
* Sets the allowed characters to be used for parsing a delimited String.
*
* @param allowedChars Characters which are to be considered as part of the tokens when parsing a delimited String [default is '.' and '-']
*/
public void setAllowedChars(final char[] allowedChars) {
this.allowedChars = Objects.requireNonNull(allowedChars, "allowedChars").clone();
}
/**
* Sets the delimiter to be used for parsing a delimited String.
*
* @param delimiter The delimiter [default ',']
*/
public void setDelimiter(final char delimiter) {
this.delimiter = delimiter;
}
/**
* Indicates whether converting to a String should create a delimited list or just convert the first value.
*
* @param onlyFirstToString {@code true} converts only the first value in the array to a String, {@code false} converts all values in the array into a
* delimited list (default is {@code true}
*/
public void setOnlyFirstToString(final boolean onlyFirstToString) {
this.onlyFirstToString = onlyFirstToString;
}
/**
* Provide a String representation of this array converter.
*
* @return A String representation of this array converter
*/
@Override
public String toString() {
final StringBuilder buffer = new StringBuilder();
buffer.append(toString(getClass()));
buffer.append("[UseDefault=");
buffer.append(isUseDefault());
buffer.append(", ");
buffer.append(elementConverter.toString());
buffer.append(']');
return buffer.toString();
}
}