org.apache.commons.beanutils
public class ConvertUtilsBean extends Object
Utility methods for converting String scalar values to objects of the specified Class, String arrays to arrays of the specified Class. The actual Converter instance to be used can be registered for each possible destination Class. Unless you override them, standard Converter instances are provided for all of the following destination Classes:
For backwards compatibility, the standard Converters for primitive types (and the corresponding wrapper classes) return a defined default value when a conversion error occurs. If you prefer to have a ConversionException thrown instead, replace the standard Converter instances with instances created with the zero-arguments constructor. For example, to cause the Converters for integers to throw an exception on conversion errors, you could do this:
// No-args constructor gets the version that throws exceptions Converter myConverter = new org.apache.commons.beanutils.converter.IntegerConverter(); ConvertUtils.register(myConverter, Integer.TYPE); // Native type ConvertUtils.register(myConverter, Integer.class); // Wrapper class
Converters generally treat null input as if it were invalid input, ie they return their default value if one was specified when the converter was constructed, and throw an exception otherwise. If you prefer nulls to be preserved for converters that are converting to objects (not primitives) then register a converter as above, passing a default value of null to the converter constructor (and of course registering that converter only for the .class target).
When a converter is listed above as having no default value, then that converter will throw an exception when passed null or an invalid value as its input. In particular, by default the BigInteger and BigDecimal converters have no default (and are therefore somewhat inconsistent with the other numerical converters which all have zero as their default).
Converters that generate arrays of each of the primitive types are also automatically configured (including String[]). When passed null or invalid input, these return an empty array (not null). See class AbstractArrayConverter for the supported input formats for these converters.
Since: 1.7
Version: $Revision: 745079 $ $Date: 2009-02-17 14:04:10 +0000 (Tue, 17 Feb 2009) $
Constructor Summary | |
---|---|
ConvertUtilsBean() Construct a bean with standard converters registered |
Method Summary | |
---|---|
String | convert(Object value)
Convert the specified value into a String. |
Object | convert(String value, Class clazz)
Convert the specified value to an object of the specified class (if
possible). |
Object | convert(String[] values, Class clazz)
Convert an array of specified values to an array of objects of the
specified class (if possible). |
Object | convert(Object value, Class targetType) Convert the value to an object of the specified class (if possible). |
void | deregister()
Remove all registered Converters, and re-establish the
standard Converters. |
void | deregister(Class clazz)
Remove any registered Converter for the specified destination
Class .
|
boolean | getDefaultBoolean()
Gets the default value for Boolean conversions. |
byte | getDefaultByte()
Gets the default value for Byte conversions. |
char | getDefaultCharacter()
Gets the default value for Character conversions. |
double | getDefaultDouble()
Gets the default value for Double conversions. |
float | getDefaultFloat()
Gets the default value for Float conversions. |
int | getDefaultInteger()
Gets the default value for Integer conversions. |
long | getDefaultLong()
Gets the default value for Long conversions. |
short | getDefaultShort()
Gets the default value for Short conversions. |
protected static ConvertUtilsBean | getInstance()
Get singleton instance |
Converter | lookup(Class clazz)
Look up and return any registered Converter for the specified
destination class; if there is no registered Converter, return
null .
|
Converter | lookup(Class sourceType, Class targetType)
Look up and return any registered Converter for the specified
source and destination class; if there is no registered Converter,
return null .
|
void | register(boolean throwException, boolean defaultNull, int defaultArraySize)
Register the provided converters with the specified defaults.
|
void | register(Converter converter, Class clazz)
Register a custom Converter for the specified destination
Class , replacing any previously registered Converter.
|
void | setDefaultBoolean(boolean newDefaultBoolean)
Sets the default value for Boolean conversions. |
void | setDefaultByte(byte newDefaultByte)
Sets the default value for Byte conversions. |
void | setDefaultCharacter(char newDefaultCharacter)
Sets the default value for Character conversions. |
void | setDefaultDouble(double newDefaultDouble)
Sets the default value for Double conversions. |
void | setDefaultFloat(float newDefaultFloat)
Sets the default value for Float conversions. |
void | setDefaultInteger(int newDefaultInteger)
Sets the default value for Integer conversions. |
void | setDefaultLong(long newDefaultLong)
Sets the default value for Long conversions. |
void | setDefaultShort(short newDefaultShort)
Sets the default value for Short conversions. |
java.lang.String
class will be used, which allows
applications to customize Object->String conversions (the default
implementation simply uses toString()).
Parameters: value Value to be converted (may be null)
Returns: The converted String value
Parameters: value Value to be converted (may be null) clazz Java class to be converted to
Returns: The converted value
Throws: ConversionException if thrown by an underlying Converter
Parameters: values Array of values to be converted clazz Java array or element class to be converted to
Returns: The converted value
Throws: ConversionException if thrown by an underlying Converter
Convert the value to an object of the specified class (if possible).
Parameters: value Value to be converted (may be null) targetType Class of the value to be converted to
Returns: The converted value
Throws: ConversionException if thrown by an underlying Converter
Class
.
Parameters: clazz Class for which to remove a registered Converter
Deprecated: Register replacement converters for Boolean.TYPE and Boolean.class instead
Gets the default value for Boolean conversions.Returns: The default Boolean value
Deprecated: Register replacement converters for Byte.TYPE and Byte.class instead
Gets the default value for Byte conversions.Returns: The default Byte value
Deprecated: Register replacement converters for Character.TYPE and Character.class instead
Gets the default value for Character conversions.Returns: The default Character value
Deprecated: Register replacement converters for Double.TYPE and Double.class instead
Gets the default value for Double conversions.Returns: The default Double value
Deprecated: Register replacement converters for Float.TYPE and Float.class instead
Gets the default value for Float conversions.Returns: The default Float value
Deprecated: Register replacement converters for Integer.TYPE and Integer.class instead
Gets the default value for Integer conversions.Returns: The default Integer value
Deprecated: Register replacement converters for Long.TYPE and Long.class instead
Gets the default value for Long conversions.Returns: The default Long value
Deprecated: Register replacement converters for Short.TYPE and Short.class instead
Gets the default value for Short conversions.Returns: The default Short value
Returns: The singleton instance
null
.
Parameters: clazz Class for which to return a registered Converter
Returns: The registered Converter or null
if not found
null
.
Parameters: sourceType Class of the value being converted targetType Class of the value to be converted to
Returns: The registered Converter or null
if not found
Parameters: throwException true
if the converters should
throw an exception when a conversion error occurs, otherwise
defaultNull false
if a default value should be used.true
if the standard converters
(see ConvertUtilsBean)
should use a default value of null
, otherwise false
.
N.B. This values is ignored if throwException
is true
defaultArraySize The size of the default array value for array converters
(N.B. This values is ignored if throwException
is true
).
Specifying a value less than zero causes a null
value to be used for
the default.
Class
, replacing any previously registered Converter.
Parameters: converter Converter to be registered clazz Destination class for conversions performed by this Converter
Deprecated: Register replacement converters for Boolean.TYPE and Boolean.class instead
Sets the default value for Boolean conversions.Parameters: newDefaultBoolean The default Boolean value
Deprecated: Register replacement converters for Byte.TYPE and Byte.class instead
Sets the default value for Byte conversions.Parameters: newDefaultByte The default Byte value
Deprecated: Register replacement converters for Character.TYPE and Character.class instead
Sets the default value for Character conversions.Parameters: newDefaultCharacter The default Character value
Deprecated: Register replacement converters for Double.TYPE and Double.class instead
Sets the default value for Double conversions.Parameters: newDefaultDouble The default Double value
Deprecated: Register replacement converters for Float.TYPE and Float.class instead
Sets the default value for Float conversions.Parameters: newDefaultFloat The default Float value
Deprecated: Register replacement converters for Integer.TYPE and Integer.class instead
Sets the default value for Integer conversions.Parameters: newDefaultInteger The default Integer value
Deprecated: Register replacement converters for Long.TYPE and Long.class instead
Sets the default value for Long conversions.Parameters: newDefaultLong The default Long value
Deprecated: Register replacement converters for Short.TYPE and Short.class instead
Sets the default value for Short conversions.Parameters: newDefaultShort The default Short value