Class ConvertUtilsBean
- Direct Known Subclasses:
ConvertUtilsBean2
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:
- java.lang.BigDecimal (no default value)
- java.lang.BigInteger (no default value)
- boolean and java.lang.Boolean (default to false)
- byte and java.lang.Byte (default to zero)
- char and java.lang.Character (default to a space)
- java.lang.Class (no default value)
- double and java.lang.Double (default to zero)
- float and java.lang.Float (default to zero)
- int and java.lang.Integer (default to zero)
- long and java.lang.Long (default to zero)
- short and java.lang.Short (default to zero)
- java.lang.String (default to null)
- java.io.File (no default value)
- java.net.URL (no default value)
- java.sql.Date (no default value)
- java.sql.Time (no default value)
- java.sql.Timestamp (no default value)
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
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionConvert the specified value into a String.Convert the value to an object of the specified class (if possible).Convert an array of specified values to an array of objects of the specified class (if possible).Convert the specified value to an object of the specified class (if possible).voidRemove all registeredConverters, and re-establish the standard Converters.voidderegister(Class<?> clazz) Remove any registeredConverterfor the specified destinationClass.booleanDeprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadbyteDeprecated.Register replacement converters for Byte.TYPE and Byte.class insteadcharDeprecated.Register replacement converters for Character.TYPE and Character.class insteaddoubleDeprecated.Register replacement converters for Double.TYPE and Double.class insteadfloatDeprecated.Register replacement converters for Float.TYPE and Float.class insteadintDeprecated.Register replacement converters for Integer.TYPE and Integer.class insteadlongDeprecated.Register replacement converters for Long.TYPE and Long.class insteadshortDeprecated.Register replacement converters for Short.TYPE and Short.class insteadprotected static ConvertUtilsBeanGet singleton instanceLook up and return any registeredConverterfor the specified destination class; if there is no registered Converter, returnnull.Look up and return any registeredConverterfor the specified source and destination class; if there is no registered Converter, returnnull.voidregister(boolean throwException, boolean defaultNull, int defaultArraySize) Register the provided converters with the specified defaults.voidRegister a customConverterfor the specified destinationClass, replacing any previously registered Converter.voidsetDefaultBoolean(boolean newDefaultBoolean) Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadvoidsetDefaultByte(byte newDefaultByte) Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadvoidsetDefaultCharacter(char newDefaultCharacter) Deprecated.Register replacement converters for Character.TYPE and Character.class insteadvoidsetDefaultDouble(double newDefaultDouble) Deprecated.Register replacement converters for Double.TYPE and Double.class insteadvoidsetDefaultFloat(float newDefaultFloat) Deprecated.Register replacement converters for Float.TYPE and Float.class insteadvoidsetDefaultInteger(int newDefaultInteger) Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadvoidsetDefaultLong(long newDefaultLong) Deprecated.Register replacement converters for Long.TYPE and Long.class insteadvoidsetDefaultShort(short newDefaultShort) Deprecated.Register replacement converters for Short.TYPE and Short.class instead
-
Constructor Details
-
ConvertUtilsBean
public ConvertUtilsBean()Construct a bean with standard converters registered
-
-
Method Details
-
getInstance
Get singleton instance- Returns:
- The singleton instance
-
convert
Convert the specified value into a String. If the specified value is an array, the first element (converted to a String) will be returned. The registeredConverterfor thejava.lang.Stringclass will be used, which allows applications to customize Object to String conversions (the default implementation simply uses toString()).- Parameters:
value- Value to be converted (may be null)- Returns:
- The converted String value or null if value is null
-
convert
Convert the value to an object of the specified class (if possible). If no converter for the desired target type is registered, the passed in object is returned unchanged.- Parameters:
value- Value to be converted (may be null)targetType- Class of the value to be converted to (must not be null)- Returns:
- The converted value
- Throws:
ConversionException- if thrown by an underlying Converter
-
convert
Convert the specified value to an object of the specified class (if possible). Otherwise, return a String representation of the value.- Parameters:
value- Value to be converted (may be null)clazz- Java class to be converted to (must not be null)- Returns:
- The converted value
- Throws:
ConversionException- if thrown by an underlying Converter
-
convert
Convert an array of specified values to an array of objects of the specified class (if possible). If the specified Java class is itself an array class, this class will be the type of the returned value. Otherwise, an array will be constructed whose component type is the specified class.- Parameters:
values- Array of values to be convertedclazz- Java array or element class to be converted to (must not be null)- Returns:
- The converted value
- Throws:
ConversionException- if thrown by an underlying Converter
-
deregister
Remove all registeredConverters, and re-establish the standard Converters. -
deregister
Remove any registeredConverterfor the specified destinationClass.- Parameters:
clazz- Class for which to remove a registered Converter
-
getDefaultBoolean
Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadGets the default value for Boolean conversions.- Returns:
- The default Boolean value
-
getDefaultByte
Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadGets the default value for Byte conversions.- Returns:
- The default Byte value
-
getDefaultCharacter
Deprecated.Register replacement converters for Character.TYPE and Character.class insteadGets the default value for Character conversions.- Returns:
- The default Character value
-
getDefaultDouble
Deprecated.Register replacement converters for Double.TYPE and Double.class insteadGets the default value for Double conversions.- Returns:
- The default Double value
-
getDefaultFloat
Deprecated.Register replacement converters for Float.TYPE and Float.class insteadGets the default value for Float conversions.- Returns:
- The default Float value
-
getDefaultInteger
Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadGets the default value for Integer conversions.- Returns:
- The default Integer value
-
getDefaultLong
Deprecated.Register replacement converters for Long.TYPE and Long.class insteadGets the default value for Long conversions.- Returns:
- The default Long value
-
getDefaultShort
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadGets the default value for Short conversions.- Returns:
- The default Short value
-
lookup
Look up and return any registeredConverterfor the specified destination class; if there is no registered Converter, returnnull.- Parameters:
clazz- Class for which to return a registered Converter- Returns:
- The registered
Converterornullif not found
-
lookup
Look up and return any registeredConverterfor the specified source and destination class; if there is no registered Converter, returnnull.- Parameters:
sourceType- Class of the value being convertedtargetType- Class of the value to be converted to- Returns:
- The registered
Converterornullif not found
-
register
Register the provided converters with the specified defaults.- Parameters:
throwException-trueif the converters should throw an exception when a conversion error occurs, otherwisefalseif a default value should be used.defaultNull-trueif the standard converters (seeregisterStandard(boolean, boolean)) should use a default value ofnull, otherwisefalse. This values is ignored ifthrowExceptionistruedefaultArraySize- The size of the default array value for array converters (This values is ignored ifthrowExceptionistrue). Specifying a value less than zero causes anullvalue to be used for the default.
-
register
Register a customConverterfor the specified destinationClass, replacing any previously registered Converter.- Parameters:
converter- Converter to be registeredclazz- Destination class for conversions performed by this Converter
-
setDefaultBoolean
Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadSets the default value for Boolean conversions.- Parameters:
newDefaultBoolean- The default Boolean value
-
setDefaultByte
Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadSets the default value for Byte conversions.- Parameters:
newDefaultByte- The default Byte value
-
setDefaultCharacter
Deprecated.Register replacement converters for Character.TYPE and Character.class insteadSets the default value for Character conversions.- Parameters:
newDefaultCharacter- The default Character value
-
setDefaultDouble
Deprecated.Register replacement converters for Double.TYPE and Double.class insteadSets the default value for Double conversions.- Parameters:
newDefaultDouble- The default Double value
-
setDefaultFloat
Deprecated.Register replacement converters for Float.TYPE and Float.class insteadSets the default value for Float conversions.- Parameters:
newDefaultFloat- The default Float value
-
setDefaultInteger
Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadSets the default value for Integer conversions.- Parameters:
newDefaultInteger- The default Integer value
-
setDefaultLong
Deprecated.Register replacement converters for Long.TYPE and Long.class insteadSets the default value for Long conversions.- Parameters:
newDefaultLong- The default Long value
-
setDefaultShort
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadSets the default value for Short conversions.- Parameters:
newDefaultShort- The default Short value
-