Class ConvertUtilsBean
- java.lang.Object
-
- org.apache.commons.beanutils.ConvertUtilsBean
-
- Direct Known Subclasses:
ConvertUtilsBean2
public class ConvertUtilsBean extends java.lang.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, standardConverter
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
-
-
Field Summary
Fields Modifier and Type Field Description private WeakFastHashMap<java.lang.Class<?>,Converter>
converters
The set ofConverter
s that can be used to convert Strings into objects of a specified Class, keyed by the destination Class.private java.lang.Boolean
defaultBoolean
Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadprivate java.lang.Byte
defaultByte
Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadprivate java.lang.Character
defaultCharacter
Deprecated.Register replacement converters for Character.TYPE and Character.class insteadprivate java.lang.Double
defaultDouble
Deprecated.Register replacement converters for Double.TYPE and Double.class insteadprivate java.lang.Float
defaultFloat
Deprecated.Register replacement converters for Float.TYPE and Float.class insteadprivate java.lang.Integer
defaultInteger
Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadprivate java.lang.Long
defaultLong
Deprecated.Register replacement converters for Long.TYPE and Long.class insteadprivate static java.lang.Short
defaultShort
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadprivate org.apache.commons.logging.Log
log
TheLog
instance for this class.private static java.lang.Character
SPACE
private static java.lang.Integer
ZERO
-
Constructor Summary
Constructors Constructor Description ConvertUtilsBean()
Construct a bean with standard converters registered
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description java.lang.String
convert(java.lang.Object value)
Convert the specified value into a String.java.lang.Object
convert(java.lang.Object value, java.lang.Class<?> targetType)
Convert the value to an object of the specified class (if possible).java.lang.Object
convert(java.lang.String[] values, java.lang.Class<?> clazz)
Convert an array of specified values to an array of objects of the specified class (if possible).java.lang.Object
convert(java.lang.String value, java.lang.Class<?> clazz)
Convert the specified value to an object of the specified class (if possible).void
deregister()
Remove all registeredConverter
s, and re-establish the standard Converters.void
deregister(java.lang.Class<?> clazz)
Remove any registeredConverter
for the specified destinationClass
.boolean
getDefaultBoolean()
Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadbyte
getDefaultByte()
Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadchar
getDefaultCharacter()
Deprecated.Register replacement converters for Character.TYPE and Character.class insteaddouble
getDefaultDouble()
Deprecated.Register replacement converters for Double.TYPE and Double.class insteadfloat
getDefaultFloat()
Deprecated.Register replacement converters for Float.TYPE and Float.class insteadint
getDefaultInteger()
Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadlong
getDefaultLong()
Deprecated.Register replacement converters for Long.TYPE and Long.class insteadshort
getDefaultShort()
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadprotected static ConvertUtilsBean
getInstance()
Get singleton instanceConverter
lookup(java.lang.Class<?> clazz)
Look up and return any registeredConverter
for the specified destination class; if there is no registered Converter, returnnull
.Converter
lookup(java.lang.Class<?> sourceType, java.lang.Class<?> targetType)
Look up and return any registeredConverter
for the specified source and destination class; if there is no registered Converter, returnnull
.void
register(boolean throwException, boolean defaultNull, int defaultArraySize)
Register the provided converters with the specified defaults.private void
register(java.lang.Class<?> clazz, Converter converter)
strictly for convenience since it has same parameter order as Map.putvoid
register(Converter converter, java.lang.Class<?> clazz)
Register a customConverter
for the specified destinationClass
, replacing any previously registered Converter.private void
registerArrayConverter(java.lang.Class<?> componentType, Converter componentConverter, boolean throwException, int defaultArraySize)
Register a new ArrayConverter with the specified element delegate converter that returns a default array of the specified size in the event of conversion errors.private void
registerArrays(boolean throwException, int defaultArraySize)
Register array converters.private void
registerOther(boolean throwException)
Register the converters for other types.private void
registerPrimitives(boolean throwException)
Register the converters for primitive types.private void
registerStandard(boolean throwException, boolean defaultNull)
Register the converters for standard types.void
setDefaultBoolean(boolean newDefaultBoolean)
Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadvoid
setDefaultByte(byte newDefaultByte)
Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadvoid
setDefaultCharacter(char newDefaultCharacter)
Deprecated.Register replacement converters for Character.TYPE and Character.class insteadvoid
setDefaultDouble(double newDefaultDouble)
Deprecated.Register replacement converters for Double.TYPE and Double.class insteadvoid
setDefaultFloat(float newDefaultFloat)
Deprecated.Register replacement converters for Float.TYPE and Float.class insteadvoid
setDefaultInteger(int newDefaultInteger)
Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadvoid
setDefaultLong(long newDefaultLong)
Deprecated.Register replacement converters for Long.TYPE and Long.class insteadvoid
setDefaultShort(short newDefaultShort)
Deprecated.Register replacement converters for Short.TYPE and Short.class instead
-
-
-
Field Detail
-
ZERO
private static final java.lang.Integer ZERO
-
SPACE
private static final java.lang.Character SPACE
-
defaultShort
@Deprecated private static java.lang.Short defaultShort
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadThe default value for Short conversions.
-
converters
private final WeakFastHashMap<java.lang.Class<?>,Converter> converters
The set ofConverter
s that can be used to convert Strings into objects of a specified Class, keyed by the destination Class.
-
log
private final org.apache.commons.logging.Log log
TheLog
instance for this class.
-
defaultBoolean
@Deprecated private java.lang.Boolean defaultBoolean
Deprecated.Register replacement converters for Boolean.TYPE and Boolean.class insteadThe default value for Boolean conversions.
-
defaultByte
@Deprecated private java.lang.Byte defaultByte
Deprecated.Register replacement converters for Byte.TYPE and Byte.class insteadThe default value for Byte conversions.
-
defaultCharacter
@Deprecated private java.lang.Character defaultCharacter
Deprecated.Register replacement converters for Character.TYPE and Character.class insteadThe default value for Character conversions.
-
defaultDouble
@Deprecated private java.lang.Double defaultDouble
Deprecated.Register replacement converters for Double.TYPE and Double.class insteadThe default value for Double conversions.
-
defaultFloat
@Deprecated private java.lang.Float defaultFloat
Deprecated.Register replacement converters for Float.TYPE and Float.class insteadThe default value for Float conversions.
-
defaultInteger
@Deprecated private java.lang.Integer defaultInteger
Deprecated.Register replacement converters for Integer.TYPE and Integer.class insteadThe default value for Integer conversions.
-
defaultLong
@Deprecated private java.lang.Long defaultLong
Deprecated.Register replacement converters for Long.TYPE and Long.class insteadThe default value for Long conversions.
-
-
Method Detail
-
getInstance
protected static ConvertUtilsBean getInstance()
Get singleton instance- Returns:
- The singleton instance
-
convert
public java.lang.String convert(java.lang.Object value)
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 registeredConverter
for thejava.lang.String
class 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
public java.lang.Object convert(java.lang.Object value, java.lang.Class<?> targetType)
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
public java.lang.Object convert(java.lang.String value, java.lang.Class<?> clazz)
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
public java.lang.Object convert(java.lang.String[] values, java.lang.Class<?> clazz)
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
public void deregister()
Remove all registeredConverter
s, and re-establish the standard Converters.
-
deregister
public void deregister(java.lang.Class<?> clazz)
Remove any registeredConverter
for the specified destinationClass
.- Parameters:
clazz
- Class for which to remove a registered Converter
-
getDefaultBoolean
@Deprecated public boolean 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 public byte 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 public char 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 public double 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 public float 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 public int 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 public long 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 public short getDefaultShort()
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadGets the default value for Short conversions.- Returns:
- The default Short value
-
lookup
public Converter lookup(java.lang.Class<?> clazz)
Look up and return any registeredConverter
for the specified destination class; if there is no registered Converter, returnnull
.- Parameters:
clazz
- Class for which to return a registered Converter- Returns:
- The registered
Converter
ornull
if not found
-
lookup
public Converter lookup(java.lang.Class<?> sourceType, java.lang.Class<?> targetType)
Look up and return any registeredConverter
for 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
Converter
ornull
if not found
-
register
public void register(boolean throwException, boolean defaultNull, int defaultArraySize)
Register the provided converters with the specified defaults.- Parameters:
throwException
-true
if the converters should throw an exception when a conversion error occurs, otherwisefalse
if a default value should be used.defaultNull
-true
if the standard converters (seeregisterStandard(boolean, boolean)
) should use a default value ofnull
, otherwisefalse
. This values is ignored ifthrowException
istrue
defaultArraySize
- The size of the default array value for array converters (This values is ignored ifthrowException
istrue
). Specifying a value less than zero causes anull
value to be used for the default.
-
register
private void register(java.lang.Class<?> clazz, Converter converter)
strictly for convenience since it has same parameter order as Map.put
-
register
public void register(Converter converter, java.lang.Class<?> clazz)
Register a customConverter
for the specified destinationClass
, replacing any previously registered Converter.- Parameters:
converter
- Converter to be registeredclazz
- Destination class for conversions performed by this Converter
-
registerArrayConverter
private void registerArrayConverter(java.lang.Class<?> componentType, Converter componentConverter, boolean throwException, int defaultArraySize)
Register a new ArrayConverter with the specified element delegate converter that returns a default array of the specified size in the event of conversion errors.- Parameters:
componentType
- The component type of the arraycomponentConverter
- The converter to delegate to for the array elementsthrowException
- Whether a conversion exception should be thrown or a default value used in the event of a conversion errordefaultArraySize
- The size of the default array
-
registerArrays
private void registerArrays(boolean throwException, int defaultArraySize)
Register array converters.- Parameters:
throwException
-true
if the converters should throw an exception when a conversion error occurs, otherwisefalse
if a default value should be used.defaultArraySize
- The size of the default array value for array converters (This values is ignored ifthrowException
istrue
). Specifying a value less than zero causes anull
value to be used for the default.
-
registerOther
private void registerOther(boolean throwException)
Register the converters for other types. This method registers the following converters:Class.class
-ClassConverter
java.util.Date.class
-DateConverter
java.util.Calendar.class
-CalendarConverter
File.class
-FileConverter
java.sql.Date.class
-SqlDateConverter
java.sql.Time.class
-SqlTimeConverter
java.sql.Timestamp.class
-SqlTimestampConverter
URL.class
-URLConverter
- Parameters:
throwException
-true
if the converters should throw an exception when a conversion error occurs, otherwisefalse
if a default value should be used.
-
registerPrimitives
private void registerPrimitives(boolean throwException)
Register the converters for primitive types. This method registers the following converters:Boolean.TYPE
-BooleanConverter
Byte.TYPE
-ByteConverter
Character.TYPE
-CharacterConverter
Double.TYPE
-DoubleConverter
Float.TYPE
-FloatConverter
Integer.TYPE
-IntegerConverter
Long.TYPE
-LongConverter
Short.TYPE
-ShortConverter
- Parameters:
throwException
-true
if the converters should throw an exception when a conversion error occurs, otherwisefalse
if a default value should be used.
-
registerStandard
private void registerStandard(boolean throwException, boolean defaultNull)
Register the converters for standard types. This method registers the following converters:BigDecimal.class
-BigDecimalConverter
BigInteger.class
-BigIntegerConverter
Boolean.class
-BooleanConverter
Byte.class
-ByteConverter
Character.class
-CharacterConverter
Double.class
-DoubleConverter
Float.class
-FloatConverter
Integer.class
-IntegerConverter
Long.class
-LongConverter
Short.class
-ShortConverter
String.class
-StringConverter
- Parameters:
throwException
-true
if the converters should throw an exception when a conversion error occurs, otherwisefalse
if a default value should be used.defaultNull
-true
if the standard converters (seeregisterStandard(boolean, boolean)
) should use a default value ofnull
, otherwisefalse
. This values is ignored ifthrowException
istrue
-
setDefaultBoolean
@Deprecated public void setDefaultBoolean(boolean newDefaultBoolean)
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 public void setDefaultByte(byte newDefaultByte)
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 public void setDefaultCharacter(char newDefaultCharacter)
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 public void setDefaultDouble(double newDefaultDouble)
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 public void setDefaultFloat(float newDefaultFloat)
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 public void setDefaultInteger(int newDefaultInteger)
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 public void setDefaultLong(long newDefaultLong)
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 public void setDefaultShort(short newDefaultShort)
Deprecated.Register replacement converters for Short.TYPE and Short.class insteadSets the default value for Short conversions.- Parameters:
newDefaultShort
- The default Short value
-
-