org.jbeans
Interface TypeConverter

All Known Implementing Classes:

BaseTypeConverter

public interface TypeConverter

TypeConverters are used to convert objects from one type to another, convert strings to objects and to convert from objects and strings to arrays of objects. The way that this is setup is that a TypeConverter implementation is registered with the TypeConverterManager. The manager can then be queried for a particular TypeConveter (see TypeConveterManager for more information about retrieval). Next, the TypeConverter can be used for conversions using one of four methods described below. Any given TypeConverter may be used to convert to many different types because of the way that the TypeConverterManager searches for TypeConverters. Because of this flexibility when converting, the TypeConverter must be told what type to convert to. This is the reason for the second convertTo parameter on all of the convert methods.

Author:

Brian Pontarelli

Method Summary

Object	convert(Object value, Class convertTo) Converts the given object to the given type.
Object	convertArray(Object[] values, Class convertTo) Converts the given array to an object.
Object[]	convertArrayToArray(Object[] values, Class convertTo) Converts the array to an array of the given type.
Object	convertString(String value, Class convertTo) Converts the given String to the given type.
Object[]	convertStringToArray(String value, String delimiter, Class convertTo) Converts the String to an array of objects of the given type (normally by using a StringTokenizer and converting each token to the correct type).
Object[]	convertToArray(Object value, Class convertTo) Converts the given object to an array of objects of the given type.

Method Detail

convert

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

Converts the given object to the given type. The type can be any type that is support by the TypeConverter, but generally is a type that is the type or a sub-type of the type the converter is registered for. For example, let's say the converter is registered to java.lang.Number, then the converter should be able to convert Integer, Long, Double, etc; unless a converter is registered for each one of these. So, we could call the converter with ("0.5", Double.class) in order to convert the string to a Double object.
It is common practice to call the convertString method from this method passing it value.toString and convertTo. Ofcourse this is not required and is up to the implementing class to determine how best to convert the value to the given type.
It is also common practice to handle array types in this method by checking if the convertTo type is an array and then calling convertToArray correctly. This reduces the amount of work necessary for clients to convert values. See the java.lang.Class#isArray() method for more information
Lastly, it is common practice in this method to handle the case where the convertTo is not an array and the value is an array. In this case it is common to call the convertArray method in order to handle converting the value array to an object.

Parameters:

value - The value to convert

convertTo - The type to convert the value to

Returns:

The converted value

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

Converts the given String to the given type. The type can be any type that is support by the TypeConverter, but generally is a type that is the type or a sub-type of the type the converter is registered for. For example, let's say the converter is registered to java.lang.Number, then this converter should be able to convert Integer, Long, Double, etc. unless a converter is registered for each one of these. So, we could call the converter with ("0.5", Double.class) in order to convert the string to a Double object.
It is also common practice to handle array types in this method by checking if the convertTo type is an array and then calling convertStringToArray correctly. This reduces the amount of work necessary for clients to convert values. See the java.lang.Class#isArray() method for more information

Parameters:

value - The String value to convert

convertTo - The type to convert the value to

Returns:

The converted value

Throws:

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

convertArray

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

Converts the given array to an object. This method is mostly used to take an array of length 1 and convert the 0th index object to the given type. The type can be any type, but normally is the type or a sub-type of the type the converter is registered for.
It is also common practice to handle array types in this method by checking if the convertTo type is an array and then calling the convertArrayToArray method.

Parameters:

values - The array to convert to an object

convertTo - The type to convert the values to

Returns:

The converted value

Throws:

TypeConversionException - If there was a problem converting the given array to an Obejct

convertArrayToArray

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

Converts the array to an array of the given type. The given type can be either an array or object, for this method to succeed. If the given type is an array this method should retrieve the component type of the array and construct a new array of the component type. It could then convert each array position in the value array to the given type (or the component type if convertTo is an array).

Parameters:

values - The array to convert to an array

convertTo - Either the array type of the component type for the array being converted to

Returns:

The converted array

Throws:

TypeConversionException - If there was a problem converting the given array to an array

convertToArray

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

Converts the given object to an array of objects of the given type. This method should also take care to check if the convertTo type is an array. If it is, it is should retrieve the component type and use that when constructing the return array and also when converting the value. Of course it is up to the implementing method to determine how best to convert the value to an array. This class should be able to handle convertTo types that are both objects and arrays. So, if the converter is registered for the java.lang.Double class, this method could be called with either Double.class or Double[].class for the convertTo type and should return an instance of Double[].

Parameters:

value - The value to convert to an array

convertTo - The componenet type of the array being converted to

Returns:

The converted array

Throws:

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

convertStringToArray

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

Converts the String to an array of objects of the given type (normally by using a StringTokenizer and converting each token to the correct type). This method should also take care to check if the convertTo type is an array. If it is, it is should retrieve the component type and use that when constructing the return array and also when converting the value. Of course it is up to the implementing method to determine how best to convert the value to an array. This class should be able to handle convertTo types that are both objects and arrays. So, if the converter is registered for the java.lang.Double class, this method could be called with either Double.class or Double[].class for the convertTo type and should return an instance of Double[].

Parameters:

value - The String value to convert to an array

convertTo - The componenet type of the array being converted to

Returns:

The converted array

Throws:

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