org.apache.commons.beanutils
Class ConvertUtilsBean

java.lang.Object
  extended by 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, 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: 687089 $ $Date: 2008-08-19 17:33:30 +0100 (Tue, 19 Aug 2008) $
Author:
Craig R. McClanahan, Ralph Schaer, Chris Audley, James Strachan

Field Summary
private  WeakFastHashMap converters
          The set of Converters 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 instead
private  java.lang.Byte defaultByte
          Deprecated. Register replacement converters for Byte.TYPE and Byte.class instead
private  java.lang.Character defaultCharacter
          Deprecated. Register replacement converters for Character.TYPE and Character.class instead
private  java.lang.Double defaultDouble
          Deprecated. Register replacement converters for Double.TYPE and Double.class instead
private  java.lang.Float defaultFloat
          Deprecated. Register replacement converters for Float.TYPE and Float.class instead
private  java.lang.Integer defaultInteger
          Deprecated. Register replacement converters for Integer.TYPE and Integer.class instead
private  java.lang.Long defaultLong
          Deprecated. Register replacement converters for Long.TYPE and Long.class instead
private static java.lang.Short defaultShort
          Deprecated. Register replacement converters for Short.TYPE and Short.class instead
private  org.apache.commons.logging.Log log
          The Log instance for this class.
private static java.lang.Character SPACE
           
private static java.lang.Integer ZERO
           
 
Constructor Summary
ConvertUtilsBean()
          Construct a bean with standard converters registered
 
Method Summary
 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 registered Converters, and re-establish the standard Converters.
 void deregister(java.lang.Class clazz)
          Remove any registered Converter for the specified destination Class.
 boolean getDefaultBoolean()
          Deprecated. Register replacement converters for Boolean.TYPE and Boolean.class instead
 byte getDefaultByte()
          Deprecated. Register replacement converters for Byte.TYPE and Byte.class instead
 char getDefaultCharacter()
          Deprecated. Register replacement converters for Character.TYPE and Character.class instead
 double getDefaultDouble()
          Deprecated. Register replacement converters for Double.TYPE and Double.class instead
 float getDefaultFloat()
          Deprecated. Register replacement converters for Float.TYPE and Float.class instead
 int getDefaultInteger()
          Deprecated. Register replacement converters for Integer.TYPE and Integer.class instead
 long getDefaultLong()
          Deprecated. Register replacement converters for Long.TYPE and Long.class instead
 short getDefaultShort()
          Deprecated. Register replacement converters for Short.TYPE and Short.class instead
protected static ConvertUtilsBean getInstance()
          Get singleton instance
 Converter lookup(java.lang.Class clazz)
          Look up and return any registered Converter for the specified destination class; if there is no registered Converter, return null.
 Converter lookup(java.lang.Class sourceType, java.lang.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.
private  void register(java.lang.Class clazz, Converter converter)
          strictly for convenience since it has same parameter order as Map.put
 void register(Converter converter, java.lang.Class clazz)
          Register a custom Converter for the specified destination Class, 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 instead
 void setDefaultByte(byte newDefaultByte)
          Deprecated. Register replacement converters for Byte.TYPE and Byte.class instead
 void setDefaultCharacter(char newDefaultCharacter)
          Deprecated. Register replacement converters for Character.TYPE and Character.class instead
 void setDefaultDouble(double newDefaultDouble)
          Deprecated. Register replacement converters for Double.TYPE and Double.class instead
 void setDefaultFloat(float newDefaultFloat)
          Deprecated. Register replacement converters for Float.TYPE and Float.class instead
 void setDefaultInteger(int newDefaultInteger)
          Deprecated. Register replacement converters for Integer.TYPE and Integer.class instead
 void setDefaultLong(long newDefaultLong)
          Deprecated. Register replacement converters for Long.TYPE and Long.class instead
 void setDefaultShort(short newDefaultShort)
          Deprecated. Register replacement converters for Short.TYPE and Short.class instead
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ZERO

private static final java.lang.Integer ZERO

SPACE

private static final java.lang.Character SPACE

converters

private WeakFastHashMap converters
The set of Converters that can be used to convert Strings into objects of a specified Class, keyed by the destination Class.


log

private org.apache.commons.logging.Log log
The Log instance for this class.


defaultBoolean

private java.lang.Boolean defaultBoolean
Deprecated. Register replacement converters for Boolean.TYPE and Boolean.class instead
The default value for Boolean conversions.


defaultByte

private java.lang.Byte defaultByte
Deprecated. Register replacement converters for Byte.TYPE and Byte.class instead
The default value for Byte conversions.


defaultCharacter

private java.lang.Character defaultCharacter
Deprecated. Register replacement converters for Character.TYPE and Character.class instead
The default value for Character conversions.


defaultDouble

private java.lang.Double defaultDouble
Deprecated. Register replacement converters for Double.TYPE and Double.class instead
The default value for Double conversions.


defaultFloat

private java.lang.Float defaultFloat
Deprecated. Register replacement converters for Float.TYPE and Float.class instead
The default value for Float conversions.


defaultInteger

private java.lang.Integer defaultInteger
Deprecated. Register replacement converters for Integer.TYPE and Integer.class instead
The default value for Integer conversions.


defaultLong

private java.lang.Long defaultLong
Deprecated. Register replacement converters for Long.TYPE and Long.class instead
The default value for Long conversions.


defaultShort

private static java.lang.Short defaultShort
Deprecated. Register replacement converters for Short.TYPE and Short.class instead
The default value for Short conversions.

Constructor Detail

ConvertUtilsBean

public ConvertUtilsBean()
Construct a bean with standard converters registered

Method Detail

getInstance

protected static ConvertUtilsBean getInstance()
Get singleton instance

Returns:
The singleton instance

getDefaultBoolean

public boolean getDefaultBoolean()
Deprecated. Register replacement converters for Boolean.TYPE and Boolean.class instead

Gets the default value for Boolean conversions.

Returns:
The default Boolean value

setDefaultBoolean

public void setDefaultBoolean(boolean newDefaultBoolean)
Deprecated. Register replacement converters for Boolean.TYPE and Boolean.class instead

Sets the default value for Boolean conversions.

Parameters:
newDefaultBoolean - The default Boolean value

getDefaultByte

public byte getDefaultByte()
Deprecated. Register replacement converters for Byte.TYPE and Byte.class instead

Gets the default value for Byte conversions.

Returns:
The default Byte value

setDefaultByte

public void setDefaultByte(byte newDefaultByte)
Deprecated. Register replacement converters for Byte.TYPE and Byte.class instead

Sets the default value for Byte conversions.

Parameters:
newDefaultByte - The default Byte value

getDefaultCharacter

public char getDefaultCharacter()
Deprecated. Register replacement converters for Character.TYPE and Character.class instead

Gets the default value for Character conversions.

Returns:
The default Character value

setDefaultCharacter

public void setDefaultCharacter(char newDefaultCharacter)
Deprecated. Register replacement converters for Character.TYPE and Character.class instead

Sets the default value for Character conversions.

Parameters:
newDefaultCharacter - The default Character value

getDefaultDouble

public double getDefaultDouble()
Deprecated. Register replacement converters for Double.TYPE and Double.class instead

Gets the default value for Double conversions.

Returns:
The default Double value

setDefaultDouble

public void setDefaultDouble(double newDefaultDouble)
Deprecated. Register replacement converters for Double.TYPE and Double.class instead

Sets the default value for Double conversions.

Parameters:
newDefaultDouble - The default Double value

getDefaultFloat

public float getDefaultFloat()
Deprecated. Register replacement converters for Float.TYPE and Float.class instead

Gets the default value for Float conversions.

Returns:
The default Float value

setDefaultFloat

public void setDefaultFloat(float newDefaultFloat)
Deprecated. Register replacement converters for Float.TYPE and Float.class instead

Sets the default value for Float conversions.

Parameters:
newDefaultFloat - The default Float value

getDefaultInteger

public int getDefaultInteger()
Deprecated. Register replacement converters for Integer.TYPE and Integer.class instead

Gets the default value for Integer conversions.

Returns:
The default Integer value

setDefaultInteger

public void setDefaultInteger(int newDefaultInteger)
Deprecated. Register replacement converters for Integer.TYPE and Integer.class instead

Sets the default value for Integer conversions.

Parameters:
newDefaultInteger - The default Integer value

getDefaultLong

public long getDefaultLong()
Deprecated. Register replacement converters for Long.TYPE and Long.class instead

Gets the default value for Long conversions.

Returns:
The default Long value

setDefaultLong

public void setDefaultLong(long newDefaultLong)
Deprecated. Register replacement converters for Long.TYPE and Long.class instead

Sets the default value for Long conversions.

Parameters:
newDefaultLong - The default Long value

getDefaultShort

public short getDefaultShort()
Deprecated. Register replacement converters for Short.TYPE and Short.class instead

Gets the default value for Short conversions.

Returns:
The default Short value

setDefaultShort

public void setDefaultShort(short newDefaultShort)
Deprecated. Register replacement converters for Short.TYPE and Short.class instead

Sets the default value for Short conversions.

Parameters:
newDefaultShort - The default Short value

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 registered Converter for the 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

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
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 converted
clazz - Java array or element class to be converted to
Returns:
The converted value
Throws:
ConversionException - if thrown by an underlying Converter

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).

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

deregister

public void deregister()
Remove all registered Converters, and re-establish the standard Converters.


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, otherwise false if a default value should be used.
defaultNull - trueif the standard converters (see registerStandard(boolean, boolean)) 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.

registerPrimitives

private void registerPrimitives(boolean throwException)
Register the converters for primitive types.

This method registers the following converters:

Parameters:
throwException - true if the converters should throw an exception when a conversion error occurs, otherwise false 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:

Parameters:
throwException - true if the converters should throw an exception when a conversion error occurs, otherwise false if a default value should be used.
defaultNull - trueif the standard converters (see registerStandard(boolean, boolean)) should use a default value of null, otherwise false. N.B. This values is ignored if throwException is true

registerOther

private void registerOther(boolean throwException)
Register the converters for other types.

This method registers the following converters:

Parameters:
throwException - true if the converters should throw an exception when a conversion error occurs, otherwise false if a default value should be used.

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, otherwise false if a default value should be used.
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.

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 array
componentConverter - The converter to delegate to for the array elements
throwException - Whether a conversion exception should be thrown or a default value used in the event of a conversion error
defaultArraySize - The size of the default array

register

private void register(java.lang.Class clazz,
                      Converter converter)
strictly for convenience since it has same parameter order as Map.put


deregister

public void deregister(java.lang.Class clazz)
Remove any registered Converter for the specified destination Class.

Parameters:
clazz - Class for which to remove a registered Converter

lookup

public Converter lookup(java.lang.Class clazz)
Look up and return any registered Converter for the specified destination class; if there is no registered Converter, return null.

Parameters:
clazz - Class for which to return a registered Converter
Returns:
The registered Converter or null if not found

lookup

public Converter lookup(java.lang.Class sourceType,
                        java.lang.Class targetType)
Look up and return any registered Converter for the specified source and destination class; if there is no registered Converter, return 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

register

public void register(Converter converter,
                     java.lang.Class clazz)
Register a custom Converter for the specified destination Class, replacing any previously registered Converter.

Parameters:
converter - Converter to be registered
clazz - Destination class for conversions performed by this Converter


Copyright (c) 2000-2008 - Apache Software Foundation