Package org.apache.commons.beanutils

Class 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:

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

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

      • defaultShort

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

      • converters

        private final WeakFastHashMap<java.lang.Class<?>,​Converter> 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 final org.apache.commons.logging.Log log
        The Log instance for this class.

      • defaultBoolean

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

      • defaultByte

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

      • defaultCharacter

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

      • defaultDouble

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

      • defaultFloat

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

      • defaultInteger

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

      • defaultLong

        @Deprecated
private java.lang.Long defaultLong
        Deprecated.
        Register replacement converters for Long.TYPE and Long.class instead
        The default value for Long 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

      • 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 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 converted
        clazz - 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 registered Converters, and re-establish the standard Converters.

      • 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

      • getDefaultBoolean

        @Deprecated
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

      • getDefaultByte

        @Deprecated
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

      • getDefaultCharacter

        @Deprecated
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

      • getDefaultDouble

        @Deprecated
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

      • getDefaultFloat

        @Deprecated
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

      • getDefaultInteger

        @Deprecated
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

      • getDefaultLong

        @Deprecated
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

      • getDefaultShort

        @Deprecated
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

      • 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​(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. This values is ignored if throwException is true
        defaultArraySize - The size of the default array value for array converters (This values is ignored if throwException is true). Specifying a value less than zero causes a null 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 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

      • 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

      • 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 (This values is ignored if throwException is true). Specifying a value less than zero causes a null 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:
        Parameters:
        throwException - true if the converters should throw an exception when a conversion error occurs, otherwise false if a default value should be used.

      • setDefaultBoolean

        @Deprecated
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

      • setDefaultByte

        @Deprecated
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

      • setDefaultCharacter

        @Deprecated
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

      • setDefaultDouble

        @Deprecated
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

      • setDefaultFloat

        @Deprecated
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

      • setDefaultInteger

        @Deprecated
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

      • setDefaultLong

        @Deprecated
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

      • setDefaultShort

        @Deprecated
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