Package org.apache.commons.beanutils2.converters

# Class AbstractConverter<D>

java.lang.Object
org.apache.commons.beanutils2.converters.AbstractConverter<D>

Type Parameters:
  `D` - The default value type.

All Implemented Interfaces:
  `Converter<D>`

Direct Known Subclasses:
  `ArrayConverter`, `BooleanConverter`, `CharacterConverter`, `ClassConverter`, `ColorConverter`, `DateTimeConverter`, `DimensionConverter`, `DurationConverter`, `EnumConverter`, `FileConverter`, `InetAddressConverter`, `LocaleConverter`, `LocalTimeConverter`, `MonthDayConverter`, `NumberConverter`, `OffsetTimeConverter`, `PathConverter`, `PatternConverter`, `PeriodConverter`, `PointConverter`, `StringConverter`, `URIConverter`, `URLConverter`, `UUIDConverter`, `YearConverter`, `YearMonthConverter`, `ZoneIdConverter`, `ZoneOffsetConverter`

public abstract class AbstractConverter<D> extends Object implements Converter<D>
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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractConverter()`
  Constructs a Converter that throws a `ConversionException` if an error occurs.
  `AbstractConverter(D defaultValue)`
  Constructs a Converter that returns a default value if an error occurs.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected ConversionException`
  `conversionException(Class<?> type, Object value)`
  Creates a standard conversion exception with a message indicating that the passed in value cannot be converted to the desired target type.
  `<R> R`
  `convert(Class<R> type, Object value)`
  Converts the input object into an output object of the specified type.
  `protected Object`
  `convertArray(Object value)`
  Returns the first element from an Array (or Collection) or the value unchanged if not an Array (or Collection).
  `protected String`
  `convertToString(Object value)`
  Converts the input object into a String.
  `protected abstract <R> R`
  `convertToType(Class<R> type, Object value)`
  Converts the input object into an output object of the specified type.
  `protected Object`
  `getDefault(Class<?> type)`
  Gets the default value for conversions to the specified type.
  `protected abstract Class<D>`
  `getDefaultType()`
  Gets the default type this `Converter` handles.
  `protected <T> T`
  `handleError(Class<T> type, Object value, Throwable cause)`
  Handles Conversion Errors.
  `protected <T> T`
  `handleMissing(Class<T> type)`
  Handles missing values.
  `boolean`
  `isUseDefault()`
  Tests whether a default value will be returned or exception thrown in the event of a conversion error.
  `protected void`
  `setDefaultValue(D defaultValue)`
  Sets the default value, converting as required.
  `protected static String`
  `toLowerCase(Object value)`
  Converts the given object to a lower-case string.
  `String`
  `toString()`
  Converts this instance to a String.
  `protected static String`
  `toString(Object value)`
  Converts the given object to a lower-case string.
  `protected static String`
  `toTrim(Object value)`
  Converts the given object to a lower-case string.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### AbstractConverter

    public AbstractConverter()
    Constructs a Converter that throws a `ConversionException` if an error occurs.

  - ### AbstractConverter

    public AbstractConverter(D defaultValue)
    Constructs 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 Details

  - ### toLowerCase

    protected static String toLowerCase(Object value)
    Converts the given object to a lower-case string.
    Parameters:
      `value` - the input string.
    Returns:
      the given string trimmed and converter to lower-case.

  - ### toString

    protected static String toString(Object value)
    Converts the given object to a lower-case string.
    Parameters:
      `value` - the input string.
    Returns:
      the given string trimmed and converter to lower-case.

  - ### toTrim

    protected static String toTrim(Object value)
    Converts the given object to a lower-case string.
    Parameters:
      `value` - the input string.
    Returns:
      the given string trimmed and converter to lower-case.

  - ### conversionException

    protected ConversionException conversionException(Class<?> type, Object value)
    Creates 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 <R> R convert(Class<R> type, Object value)
    Converts the input object into an output object of the specified type.
    Specified by:
      `convert` in interface `Converter<D>`
    Type Parameters:
      `R` - the result type.
    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 Object convertArray(Object value)
    Returns the first element from an Array (or Collection) or the value unchanged if not an Array (or Collection). N.B. This needs to be overridden 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)

  - ### convertToString

    protected String convertToString(Object value)
    Converts the input object into a String.

    N.B.This implementation simply uses the value's `toString()` method and should be overridden 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:
      `IllegalArgumentException` - if an error occurs converting to a String

  - ### convertToType

    protected abstract <R> R convertToType(Class<R> type, Object value) throws Throwable
    Converts the input object into an output object of the specified type.

    Typical implementations will provide a minimum of `String --&gt; type` conversion.

    Type Parameters:
      `R` - 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:
      `Throwable` - if an error occurs converting to the specified type

  - ### getDefault

    protected Object getDefault(Class<?> type)
    Gets 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 Class<D> getDefaultType()
    Gets the default type this `Converter` handles.
    Returns:
      The default type this `Converter` handles.

  - ### handleError

    protected <T> T handleError(Class<T> type, Object value, Throwable cause)
    Handles 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(Class<T> type)
    Handles 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()
    Tests 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.

  - ### setDefaultValue

    protected void setDefaultValue(D defaultValue)
    Sets 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 String toString()
    Converts this instance to a String.
    Overrides:
      `toString` in class `Object`
    Returns:
      A String representation of this converter