Java Doc for ConvertUtilsBean.java in  » Library » Apache-commons-beanutils-1.8.0-BETA-src » org » apache » commons » beanutils » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

Convert the value to an object of the specified class (if possible).