/*
* 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.beanutils.converters;
import java.util.Collections;
import java.util.List;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.Collection;
import java.io.StreamTokenizer;
import java.io.StringReader;
import java.io.IOException;
import java.lang.reflect.Array;
import org.apache.commons.beanutils.ConversionException;
import org.apache.commons.beanutils.Converter;
/**
* Generic {@link Converter} implementaion that handles conversion
* to and from <b>array</b> objects.
* <p>
* Can be configured to either return a <i>default value</i> or throw a
* <code>ConversionException</code> if a conversion error occurs.
* <p>
* The main features of this implementation are:
* <ul>
* <li><b>Element Conversion</b> - 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 specifc
* array type converters.</li>
* <li><b>Arrays or Collections</b> - can convert from either arrays or
* Collections to an array, limited only by the capability
* of the delegate {@link Converter}.</li>
* <li><b>Delimited Lists</b> - can Convert <b>to</b> and <b>from</b> a
* delimited list in String format.</li>
* <li><b>Conversion to String</b> - converts an array to a
* <code>String</code> in one of two ways: as a <i>delimited list</i>
* or by converting the first element in the array to a String - this
* is controlled by the {@link ArrayConverter#setOnlyFirstToString(boolean)}
* parameter.</li>
* <li><b>Multi Dimensional Arrays</b> - its possible to convert a <code>String</code>
* to a multi-dimensional arrays, by embedding {@link ArrayConverter}
* within each other - see example below.</li>
* <li><b>Default Value</b></li>
* <ul>
* <li><b><i>No Default</b></i> - 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><b><i>Default values</b></i> - use the
* {@link ArrayConverter#ArrayConverter(Class, Converter, int)}
* constructor to create a converter which returns a <i>default
* value</i>. The <i>defaultSize</i> parameter controls the
* <i>default value</i> in the following way:</li>
* <ul>
* <li><i>defaultSize < 0</i> - default is <code>null</code></li>
* <li><i>defaultSize = 0</i> - default is an array of length zero</li>
* <li><i>defaultSize > 0</i> - default is an array with a
* length specified by <code>defaultSize</code> (N.B. elements
* in the array will be <code>null</code>)</li>
* </ul>
* </ul>
* </ul>
*
* <h3>Parsing Delimited Lists</h3>
* This implementation can convert a delimited list in <code>String</code> 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)</code> - allows the character used as
* the delimiter to be configured [default is a comma].</li>
* <li><code>setAllowedChars(char[])</code> - adds additional characters
* (to the default alphabetic/numeric) to those considered to be
* valid token characters.
* </ul>
*
* <h3>Multi Dimensional Arrays</h3>
* It is possible to convert a <code>String</code> to mulit-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</code> 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 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);
* </pre>
*
* @version $Revision: 640131 $ $Date: 2008-03-23 02:10:31 +0000 (Sun, 23 Mar 2008) $
* @since 1.8.0
*/
public class ArrayConverter extends AbstractConverter {
private Object defaultTypeInstance;
private Converter elementConverter;
private int defaultSize;
private char delimiter = ',';
private char[] allowedChars = new char[] {'.', '-'};
private boolean onlyFirstToString = true;
// ----------------------------------------------------------- Constructors
/**
* Construct an <b>array</b> <code>Converter</code> with the specified
* <b>component</b> <code>Converter</code> that throws a
* <code>ConversionException</code> if an error occurs.
*
* @param defaultType The default array type this
* <code>Converter</code> handles
* @param elementConverter Converter used to convert
* individual array elements.
*/
public ArrayConverter(Class defaultType, Converter elementConverter) {
super();
if (defaultType == null) {
throw new IllegalArgumentException("Default type is missing");
}
if (!defaultType.isArray()) {
throw new IllegalArgumentException("Default type must be an array.");
}
if (elementConverter == null) {
throw new IllegalArgumentException("Component Converter is missing.");
}
this.defaultTypeInstance = Array.newInstance(defaultType.getComponentType(), 0);
this.elementConverter = elementConverter;
}
/**
* Construct an <b>array</b> <code>Converter</code> with the specified
* <b>component</b> <code>Converter</code> that returns a default
* array of the specified size (or <code>null</code>) if an error occurs.
*
* @param defaultType The default array type this
* <code>Converter</code> 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</code> default value should be used.
*/
public ArrayConverter(Class defaultType, Converter elementConverter, int defaultSize) {
this(defaultType, elementConverter);
this.defaultSize = defaultSize;
Object defaultValue = null;
if (defaultSize >= 0) {
defaultValue = Array.newInstance(defaultType.getComponentType(), defaultSize);
}
setDefaultValue(defaultValue);
}
/**
* Set the delimiter to be used for parsing a delimited String.
*
* @param delimiter The delimiter [default ',']
*/
public void setDelimiter(char delimiter) {
this.delimiter = delimiter;
}
/**
* Set 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(char[] allowedChars) {
this.allowedChars = allowedChars;
}
/**
* Indicates whether converting to a String should create
* a delimited list or just convert the first value.
*
* @param onlyFirstToString <code>true</code> converts only
* the first value in the array to a String, <code>false</code>
* converts all values in the array into a delimited list (default
* is <code>true</code>
*/
public void setOnlyFirstToString(boolean onlyFirstToString) {
this.onlyFirstToString = onlyFirstToString;
}
/**
* Return the default type this <code>Converter</code> handles.
*
* @return The default type this <code>Converter</code> handles.
*/
protected Class getDefaultType() {
return defaultTypeInstance.getClass();
}
/**
* Handles conversion to a String.
*
* @param value The value to be converted.
* @return the converted String value.
* @throws Throwable if an error occurs converting to a String
*/
protected String convertToString(Object value) throws Throwable {
int size = 0;
Iterator iterator = null;
Class type = value.getClass();
if (type.isArray()) {
size = Array.getLength(value);
} else {
Collection collection = convertToCollection(type, value);
size = collection.size();
iterator = collection.iterator();
}
if (size == 0) {
return (String)getDefault(String.class);
}
if (onlyFirstToString) {
size = 1;
}
// Create a StringBuffer containing a delimited list of the values
StringBuffer buffer = new StringBuffer();
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 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
*/
protected Object convertToType(Class type, Object value) throws Throwable {
if (!type.isArray()) {
throw new ConversionException(toString(getClass())
+ " cannot handle conversion to '"
+ toString(type) + "' (not an array).");
}
// Handle the source
int size = 0;
Iterator iterator = null;
if (value.getClass().isArray()) {
size = Array.getLength(value);
} else {
Collection collection = convertToCollection(type, value);
size = collection.size();
iterator = collection.iterator();
}
// Allocate a new Array
Class componentType = type.getComponentType();
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);
}
return newArray;
}
/**
* Returns the value unchanged.
*
* @param value The value to convert
* @return The value unchanged
*/
protected Object convertArray(Object value) {
return value;
}
/**
* Converts non-array values to a Collection prior
* to being converted either to an array or a String.
* </p>
* <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
* <i>non-array</i> types.
*
* @param type The type to convert the value to
* @param value value to be converted
* @return Collection elements.
*/
protected Collection convertToCollection(Class type, Object value) {
if (value instanceof Collection) {
return (Collection)value;
}
if (value instanceof Number ||
value instanceof Boolean ||
value instanceof java.util.Date) {
List list = new ArrayList(1);
list.add(value);
return list;
}
return parseElements(type, value.toString());
}
/**
* Return 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.
*/
protected Object getDefault(Class type) {
if (type.equals(String.class)) {
return null;
}
Object defaultValue = super.getDefault(type);
if (defaultValue == null) {
return null;
}
if (defaultValue.getClass().equals(type)) {
return defaultValue;
} else {
return Array.newInstance(type.getComponentType(), defaultSize);
}
}
/**
* Provide a String representation of this array converter.
*
* @return A String representation of this array converter
*/
public String toString() {
StringBuffer buffer = new StringBuffer();
buffer.append(toString(getClass()));
buffer.append("[UseDefault=");
buffer.append(isUseDefault());
buffer.append(", ");
buffer.append(elementConverter.toString());
buffer.append(']');
return buffer.toString();
}
/**
* <p>Parse an incoming String of the form similar to an array initializer
* in the Java language into a <code>List</code> 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 type The type to convert the value to
* @param value String value to be parsed
* @return List of parsed elements.
*
* @throws ConversionException if the syntax of <code>svalue</code>
* is not syntactically valid
* @throws NullPointerException if <code>svalue</code>
* is <code>null</code>
*/
private List parseElements(Class type, String value) {
if (log().isDebugEnabled()) {
log().debug("Parsing elements, delimiter=[" + delimiter + "], value=[" + value + "]");
}
// Trim any matching '{' and '}' delimiters
value = value.trim();
if (value.startsWith("{") && value.endsWith("}")) {
value = value.substring(1, value.length() - 1);
}
try {
// Set up a StreamTokenizer on the characters in this String
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 (int i = 0; i < allowedChars.length; i++) {
st.ordinaryChars(allowedChars[i], allowedChars[i]);
st.wordChars(allowedChars[i], allowedChars[i]);
}
// Split comma-delimited tokens into a List
List list = null;
while (true) {
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 new ConversionException("Encountered token of type "
+ ttype + " parsing elements to '" + toString(type) + ".");
}
}
if (list == null) {
list = Collections.EMPTY_LIST;
}
if (log().isDebugEnabled()) {
log().debug(list.size() + " elements parsed");
}
// Return the completed list
return (list);
} catch (IOException e) {
throw new ConversionException("Error converting from String to '"
+ toString(type) + "': " + e.getMessage(), e);
}
}
}