org.jbeans
Class BaseTypeConverter

java.lang.Object
  |
  +--org.jbeans.BaseTypeConverter

All Implemented Interfaces:

TypeConverter

Direct Known Subclasses:

BooleanTypeConverter, CharacterTypeConverter, NumberTypeConverter

public class BaseTypeConverter

extends Object

implements TypeConverter

This class is the base type converter for all the type converters it is also the type converter that handles strings and arrays of strings. This converter contains implementation for all the type converter methods and also includes standard implementations for the convert, convertArray, convertArrayToArray, convertToArray and convertStringToArray. In most cases, these methods do not need to be overridden. See each method for details on what exactly the method does in order to help determine if overriding is necessary.

Author:

Brian Pontarelli

Constructor Summary

BaseTypeConverter()

Method Summary

Object	convert(Object value, Class convertTo) If the convertTo class is an array, this method calls convertToArray passing it the value and the convertTo component type (by calling the getComponentType method of java.lang.Class).
Object	convertArray(Object[] values, Class convertTo) If the convertTo type parameter is an array, this method calls the convertArrayToArray method with the parameters passed to this method.
Object[]	convertArrayToArray(Object[] values, Class convertTo) If the convertTo type is an array, this method uses the component type for the convertTo type.
Object	convertString(String value, Class convertTo) This method is usually the only method that needs to be overridden in sub-classes This is where a String value is converted to the correct type.
Object[]	convertStringToArray(String value, String delimiter, Class convertTo) If the delimiter parameter is not empty or null it is used.
Object[]	convertToArray(Object value, Class convertTo) If the value is an instanceof an array, then this method calls the convertArrayToArray method by casting the value to an Object array and passing the convertTo type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BaseTypeConverter

public BaseTypeConverter()

Method Detail

convert

public Object convert(Object value,
                      Class convertTo)
               throws TypeConversionException

If the convertTo class is an array, this method calls convertToArray passing it the value and the convertTo component type (by calling the getComponentType method of java.lang.Class).

If the value is an instanceof an array, this method calls the convertArray method passing it the value, cast to an array and the convertTo type.

Otherwise, this method calls convertString passing it the value toString and the convertTo type.

If the value is null, then null is returned. If the value is an instance of the convertTo type, this returns the value.

Sub-classes should only override this method if they intend to handle conversion between two Object types, both of which are NOT String. For example, if a sub-class wished to convert Integer objects to Long objects, it could do that in this method. It is a good idea however, that sub-classes call this implementation if they do not handle the conversion.

Specified by:

convert in interface TypeConverter

Parameters:

value - The value to convert

convertTo - The type to convert the value to

Returns:

The converted value or null if the value is null. This returns value if value is an instance of the convertTo type

Throws:

TypeConversionException - If there was a problem converting the given value to the given type

convertString

public Object convertString(String value,
                            Class convertTo)
                     throws TypeConversionException

This method is usually the only method that needs to be overridden in sub-classes This is where a String value is converted to the correct type. Normally, it is a good idea to check if the convertTo type is an array and call convertStringToArray passing it the value, null for the delimiter and the component type of the convertTo parameter.

This implementation does the above check passing null for the delimiter parameter (see convertStringToArray for an explaination of this parameter) if the check succeeds. Otherwise, this method returns the value parameter since the value parameter is already a String. If the value is null, empty or whitespace then this returns null.

This is an important distinction because normally empty Strings or whitspace Strings are considered non-null, but this method treats them as nulls.

Specified by:

convertString in interface TypeConverter

Parameters:

value - The String value to convert to the given type

convertTo - The type to convert to

Returns:

Either the value parameter itself or an array version of the String value, if the convertTo type is an array. If the value is null, empty, or whitespace then this returns null

Throws:

TypeConversionException - If the convertTo type is an array and the convertStringToArray method throws an exception

convertArray

public Object convertArray(Object[] values,
                           Class convertTo)
                    throws TypeConversionException

If the convertTo type parameter is an array, this method calls the convertArrayToArray method with the parameters passed to this method. If the values is an array of length 1, it first checks if the array value at index 0 is an instanceof the convertTo type, it returns the value at index 0. If not, it returns the result of calling convert with the value at index 0 and the convertTo type.

Otherwise, this method throws an exception because it is normally not needed to convert an array to an object. If the values array is null, then this method returns null.

Specified by:

convertArray in interface TypeConverter

Parameters:

values - The array of values to convert to the given type

convertTo - The type to convert to

Returns:

Either the result of calling the convertArrayToArray method if the convertTo type is an array, or the convert method if the values array is of length 1. If the values is null, then this returns null. If values length is zero, this returns null. If values is length 1 but the element at index 0 is null, this returns null.

Throws:

TypeConversionException - If either the convertArray or convert method throw an exception (depending on which method is called) or always (see method comment)

convertArrayToArray

public Object[] convertArrayToArray(Object[] values,
                                    Class convertTo)
                             throws TypeConversionException

If the convertTo type is an array, this method uses the component type for the convertTo type. Using the convertTo, a new array is constructed of that type with the same length as the values array. Then, each object in the values array is checked to see if it is an instanceof the convertTo type. If it is, the array position is set to the value at the same position. If it is not, the the value is converted to the convertTo type and stored in the new array. This is done by calling the convert method with each position in the values array. Finally, the fully converted array is returned. If the values array is null or length 0, then this returns null.

Specified by:

convertArrayToArray in interface TypeConverter

Parameters:

values - The array to convert to an array of the given type

convertTo - The type to convert to an array of. if this parameter is an array type, then this method converts to that type. the an array of the type is converted to.

Returns:

The converted array or null if the values array is null or length 0.

Throws:

TypeConversionException - If the convert method throws a TypeConversionException when each of the positions in the values array are converted

convertToArray

public Object[] convertToArray(Object value,
                               Class convertTo)
                        throws TypeConversionException

If the value is an instanceof an array, then this method calls the convertArrayToArray method by casting the value to an Object array and passing the convertTo type. Otherwise, convertStringToArray is called with the value converted to a String using the toString method, the convertTo type and null for the delimiter (see convertStringToArray for an explaination of this parameter). If the value is null, then this returns null.

Specified by:

convertToArray in interface TypeConverter

Parameters:

value - The value to convert to an array of the given type or simply the given type if the given type is an array

convertTo - The type to convert to an array of. If this parameter is an array type, this method converts to that type.

Returns:

The value converted to an array or null if the value is null

Throws:

TypeConversionException - If convertArrayToArray or convertStringToArray throw a TypeConversionException (depending on which one is called)

convertStringToArray

public Object[] convertStringToArray(String value,
                                     String delimiter,
                                     Class convertTo)
                              throws TypeConversionException

If the delimiter parameter is not empty or null it is used. Otherwise a standard set of delimiters are used (comma, semi-colon, tab, and new line).

Using this delimiter, the string is tokenized and each token is passed to the convertString method, along with the convertTo type. The result is added to a new array of the given convertTo type or the convertTo type (if the convertTo type is an array type). This means that the order of the tokens determines the order of the array elements and the array is as long as the number of tokens. If the value is null, then this returns null

Specified by:

convertStringToArray in interface TypeConverter

Parameters:

value - The string to convert to an array

delimiter - The string to use as the delimiter when tokenizing

convertTo - The type to convert the string to. Can either be an array or an object

Returns:

The array generated by the conversion or null if the value is null

Throws:

TypeConversionException - If the call to convertString throws an exception