Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.beanutils
Class ConvertUtilsBean

    java.lang.Object
      org.apache.commons.beanutils.ConvertUtilsBean

Direct Known Subclasses:
  ConvertUtilsBean2

    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:

- 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
Version:
  $Revision: 745079 $ $Date: 2009-02-17 14:04:10 +0000 (Tue, 17 Feb 2009) $
Author:
  Craig R. McClanahan, Ralph Schaer, Chris Audley, James Strachan

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(Object value, Class targetType)` Convert the 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(String value, Class clazz)` Convert the specified value to an object of the specified class (if possible).
`void` | `deregister()` Remove all registered `Converter`s, and re-establish the standard Converters.
`void` | `deregister(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(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)` 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`

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 String convert(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 Object convert(String value,
                          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 Object convert(String[] values,
                          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 Object convert(Object value,
                          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 `Converter`s, 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` - `true`if 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.``

### deregister

    public void deregister(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(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(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`.

  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,
                         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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2009 The Apache Software Foundation. All Rights Reserved.