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

      Fields 
      Modifier and Type Field Description
      private static java.lang.String DEFAULT_CONFIG_MSG
      Debug logging message to indicate default value configuration
      private java.lang.Object defaultValue
      The default value specified to our Constructor, if any.
      private org.apache.commons.logging.Log log
      Logging for this instance.
      private static java.lang.String PACKAGE
      Current package name
      private boolean useDefault
      Should we return the default value on conversion errors?
    • 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).
      private <T> T convertToDefaultType​(java.lang.Class<T> targetClass, java.lang.Object value)
      Performs a conversion to the default type.
      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.
      (package private) org.apache.commons.logging.Log log()
      Accessor method for Log instance.
      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.
      (package private) java.lang.String toString​(java.lang.Class<?> type)
      Provide a String representation of a java.lang.Class.
      • Methods inherited from class java.lang.Object

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

      • DEFAULT_CONFIG_MSG

        private static final java.lang.String DEFAULT_CONFIG_MSG
        Debug logging message to indicate default value configuration
        See Also:
        Constant Field Values
      • PACKAGE

        private static final java.lang.String PACKAGE
        Current package name
        See Also:
        Constant Field Values
      • log

        private transient org.apache.commons.logging.Log log
        Logging for this instance.
      • useDefault

        private boolean useDefault
        Should we return the default value on conversion errors?
      • defaultValue

        private java.lang.Object defaultValue
        The default value specified to our Constructor, if any.
    • 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

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

        private <T> T convertToDefaultType​(java.lang.Class<T> targetClass,
                                           java.lang.Object value)
        Performs a conversion to the default type. This method is called if we do not have a target class. In this case, the T parameter is not set. Therefore, we can cast to it (which is required to fulfill the contract of the method signature).
        Type Parameters:
        T - the type of the result object
        Parameters:
        targetClass - the target class of the conversion
        value - the value to be converted
        Returns:
        the converted value
      • 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 to 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
      • 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.
      • getDefaultType

        protected abstract java.lang.Class<?> getDefaultType()
        Return the default type this Converter handles.
        Returns:
        The default type this Converter handles.
      • 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.
      • 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.
      • log

        org.apache.commons.logging.Log log()
        Accessor method for Log instance.

        The Log instance variable is transient and accessing it through this method ensures it is re-initialized when this instance is de-serialized.

        Returns:
        The Log instance.
      • 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
      • 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
      • toString

        java.lang.String toString​(java.lang.Class<?> type)
        Provide a String representation of a java.lang.Class.
        Parameters:
        type - The java.lang.Class.
        Returns:
        The String representation.