Class AbstractConverter

  • All Implemented Interfaces:
    Converter
    Direct Known Subclasses:
    ArrayConverter, BooleanConverter, CharacterConverter, ClassConverter, DateTimeConverter, FileConverter, NumberConverter, StringConverter, URLConverter

    public abstract class AbstractConverter
    extends java.lang.Object
    implements Converter
    Base Converter implementation that provides the structure for handling conversion to and from a specified type.

    This implementation provides the basic structure for converting to/from a specified type optionally using a default value or throwing a ConversionException if a conversion error occurs.

    Implementations should provide conversion to the specified type and from the specified type to a String value by implementing the following methods:

    • convertToString(value) - convert to a String (default implementation uses the objects toString() method).
    • convertToType(Class, value) - convert to the specified type

    The default value has to be compliant to the default type of this converter - which is enforced by the generic type parameter. If a conversion is not possible and a default value is set, the converter tries to transform the default value to the requested target type. If this fails, a ConversionException if thrown.

    Since:
    1.8.0
    Version:
    $Id: AbstractConverter.java 1632171 2014-10-15 20:15:17Z ggregory $
    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractConverter()
      Construct a Converter that throws a ConversionException if an error occurs.
      AbstractConverter​(java.lang.Object defaultValue)
      Construct a Converter that returns a default value if an error occurs.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected ConversionException conversionException​(java.lang.Class<?> type, java.lang.Object value)
      Generates a standard conversion exception with a message indicating that the passed in value cannot be converted to the desired target type.
      <T> T convert​(java.lang.Class<T> type, java.lang.Object value)
      Convert the input object into an output object of the specified type.
      protected java.lang.Object convertArray​(java.lang.Object value)
      Return the first element from an Array (or Collection) or the value unchanged if not an Array (or Collection).
      protected java.lang.String convertToString​(java.lang.Object value)
      Convert the input object into a String.
      protected abstract <T> T convertToType​(java.lang.Class<T> type, java.lang.Object value)
      Convert the input object into an output object of the specified type.
      protected java.lang.Object getDefault​(java.lang.Class<?> type)
      Return the default value for conversions to the specified type.
      protected abstract java.lang.Class<?> getDefaultType()
      Return the default type this Converter handles.
      protected <T> T handleError​(java.lang.Class<T> type, java.lang.Object value, java.lang.Throwable cause)
      Handle Conversion Errors.
      protected <T> T handleMissing​(java.lang.Class<T> type)
      Handle missing values.
      boolean isUseDefault()
      Indicates whether a default value will be returned or exception thrown in the event of a conversion error.
      protected void setDefaultValue​(java.lang.Object defaultValue)
      Set the default value, converting as required.
      java.lang.String toString()
      Provide a String representation of this converter.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • AbstractConverter

        public AbstractConverter()
        Construct a Converter that throws a ConversionException if an error occurs.
      • AbstractConverter

        public AbstractConverter​(java.lang.Object defaultValue)
        Construct a Converter that returns a default value if an error occurs.
        Parameters:
        defaultValue - The default value to be returned if the value to be converted is missing or an error occurs converting the value.
    • Method Detail

      • isUseDefault

        public boolean isUseDefault()
        Indicates whether a default value will be returned or exception thrown in the event of a conversion error.
        Returns:
        true if a default value will be returned for conversion errors or false if a ConversionException will be thrown.
      • convert

        public <T> T convert​(java.lang.Class<T> type,
                             java.lang.Object value)
        Convert the input object into an output object of the specified type.
        Specified by:
        convert in interface Converter
        Type Parameters:
        T - the target type of the conversion
        Parameters:
        type - Data type to which this value should be converted
        value - The input value to be converted
        Returns:
        The converted value.
        Throws:
        ConversionException - if conversion cannot be performed successfully and no default is specified.
      • convertToString

        protected java.lang.String convertToString​(java.lang.Object value)
                                            throws java.lang.Throwable
        Convert the input object into a String.

        N.B.This implementation simply uses the value's toString() method and should be overriden if a more sophisticated mechanism for conversion to a String is required.

        Parameters:
        value - The input value to be converted.
        Returns:
        the converted String value.
        Throws:
        java.lang.Throwable - if an error occurs converting to a String
      • convertToType

        protected abstract <T> T convertToType​(java.lang.Class<T> type,
                                               java.lang.Object value)
                                        throws java.lang.Throwable
        Convert the input object into an output object of the specified type.

        Typical implementations will provide a minimum of String --> type conversion.

        Type Parameters:
        T - Target type of the conversion.
        Parameters:
        type - Data type to which this value should be converted.
        value - The input value to be converted.
        Returns:
        The converted value.
        Throws:
        java.lang.Throwable - if an error occurs converting to the specified type
      • convertArray

        protected java.lang.Object convertArray​(java.lang.Object value)
        Return the first element from an Array (or Collection) or the value unchanged if not an Array (or Collection). N.B. This needs to be overriden for array/Collection converters.
        Parameters:
        value - The value to convert
        Returns:
        The first element in an Array (or Collection) or the value unchanged if not an Array (or Collection)
      • handleError

        protected <T> T handleError​(java.lang.Class<T> type,
                                    java.lang.Object value,
                                    java.lang.Throwable cause)
        Handle Conversion Errors.

        If a default value has been specified then it is returned otherwise a ConversionException is thrown.

        Type Parameters:
        T - Target type of the conversion.
        Parameters:
        type - Data type to which this value should be converted.
        value - The input value to be converted
        cause - The exception thrown by the convert method
        Returns:
        The default value.
        Throws:
        ConversionException - if no default value has been specified for this Converter.
      • handleMissing

        protected <T> T handleMissing​(java.lang.Class<T> type)
        Handle missing values.

        If a default value has been specified, then it is returned (after a cast to the desired target class); otherwise a ConversionException is thrown.

        Type Parameters:
        T - the desired target type
        Parameters:
        type - Data type to which this value should be converted.
        Returns:
        The default value.
        Throws:
        ConversionException - if no default value has been specified for this Converter.
      • setDefaultValue

        protected void setDefaultValue​(java.lang.Object defaultValue)
        Set the default value, converting as required.

        If the default value is different from the type the Converter handles, it will be converted to the handled type.

        Parameters:
        defaultValue - The default value to be returned if the value to be converted is missing or an error occurs converting the value.
        Throws:
        ConversionException - if an error occurs converting the default value
      • getDefaultType

        protected abstract java.lang.Class<?> getDefaultType()
        Return the default type this Converter handles.
        Returns:
        The default type this Converter handles.
      • getDefault

        protected java.lang.Object getDefault​(java.lang.Class<?> type)
        Return the default value for conversions to the specified type.
        Parameters:
        type - Data type to which this value should be converted.
        Returns:
        The default value for the specified type.
      • toString

        public java.lang.String toString()
        Provide a String representation of this converter.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A String representation of this converter
      • conversionException

        protected ConversionException conversionException​(java.lang.Class<?> type,
                                                          java.lang.Object value)
        Generates a standard conversion exception with a message indicating that the passed in value cannot be converted to the desired target type.
        Parameters:
        type - the target type
        value - the value to be converted
        Returns:
        a ConversionException with a standard message
        Since:
        1.9