Package org.apache.commons.beanutils.converters

## Class AbstractConverter

- java.lang.Object
- - org.apache.commons.beanutils.converters.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$

### Constructor Summary

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