GenericConversionService (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.core.convert.support

## Class GenericConversionService

- java.lang.Object
- - org.springframework.core.convert.support.GenericConversionService

- All Implemented Interfaces:
    ConversionService, ConverterRegistry, ConfigurableConversionService
  Direct Known Subclasses:
    DefaultConversionService, FormattingConversionService

      public class GenericConversionService
      extends Object
      implements ConfigurableConversionService

  Base `ConversionService` implementation suitable for use in most environments. Indirectly implements `ConverterRegistry` as registration API through the `ConfigurableConversionService` interface.
  Since:
    3.0
  Author:
    Keith Donald, Juergen Hoeller, Chris Beams, Phillip Webb

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GenericConversionService()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConverter(Class<?> sourceType, Class<?> targetType, Converter<?,?> converter)` Add a plain converter to this registry.
    `void` | `addConverter(Converter<?,?> converter)` Add a plain converter to this registry.
    `void` | `addConverter(GenericConverter converter)` Add a generic converter to this registry.
    `void` | `addConverterFactory(ConverterFactory<?,?> converterFactory)` Add a ranged converter factory to this registry.
    `boolean` | `canBypassConvert(TypeDescriptor sourceType, TypeDescriptor targetType)` Returns true if conversion between the sourceType and targetType can be bypassed.
    `boolean` | `canConvert(Class<?> sourceType, Class<?> targetType)` Returns true if objects of sourceType can be converted to targetType.
    `boolean` | `canConvert(TypeDescriptor sourceType, TypeDescriptor targetType)` Returns true if objects of sourceType can be converted to the targetType.
    `<T> T` | `convert(Object source, Class<T> targetType)` Convert the source to targetType.
    `Object` | `convert(Object source, TypeDescriptor targetType)` Convenience operation for converting a source object to the specified targetType, where the targetType is a descriptor that provides additional conversion context.
    `Object` | `convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType)` Convert the source to targetType.
    `protected Object` | `convertNullSource(TypeDescriptor sourceType, TypeDescriptor targetType)` Template method to convert a null source.
    `protected GenericConverter` | `getConverter(TypeDescriptor sourceType, TypeDescriptor targetType)` Hook method to lookup the converter for a given sourceType/targetType pair.
    `protected GenericConverter` | `getDefaultConverter(TypeDescriptor sourceType, TypeDescriptor targetType)` Return the default converter if no converter is found for the given sourceType/targetType pair.
    `void` | `removeConvertible(Class<?> sourceType, Class<?> targetType)` Remove any converters from sourceType to targetType.
    `String` | `toString()`

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

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

- - ### Constructor Detail

    - #### GenericConversionService

          public GenericConversionService()

  - ### Method Detail

    - #### addConverter

          public void addConverter(Converter<?,?> converter)

      Description copied from interface: `ConverterRegistry`
      Add a plain converter to this registry. The convertible sourceType/targetType pair is derived from the Converter's parameterized types.
      Specified by:
        `addConverter` in interface `ConverterRegistry`

    - #### addConverter

          public void addConverter(Class<?> sourceType,
                          Class<?> targetType,
                          Converter<?,?> converter)

      Description copied from interface: `ConverterRegistry`
      Add a plain converter to this registry. The convertible sourceType/targetType pair is specified explicitly. Allows for a Converter to be reused for multiple distinct pairs without having to create a Converter class for each pair.
      Specified by:
        `addConverter` in interface `ConverterRegistry`

    - #### addConverter

          public void addConverter(GenericConverter converter)

      Description copied from interface: `ConverterRegistry`
      Add a generic converter to this registry.
      Specified by:
        `addConverter` in interface `ConverterRegistry`

    - #### addConverterFactory

          public void addConverterFactory(ConverterFactory<?,?> converterFactory)

      Description copied from interface: `ConverterRegistry`
      Add a ranged converter factory to this registry. The convertible sourceType/rangeType pair is derived from the ConverterFactory's parameterized types.
      Specified by:
        `addConverterFactory` in interface `ConverterRegistry`

    - #### removeConvertible

          public void removeConvertible(Class<?> sourceType,
                               Class<?> targetType)

      Description copied from interface: `ConverterRegistry`
      Remove any converters from sourceType to targetType.
      Specified by:
        `removeConvertible` in interface `ConverterRegistry`
      Parameters:
        `sourceType` - the source type
        `targetType` - the target type

    - #### canConvert

          public boolean canConvert(Class<?> sourceType,
                           Class<?> targetType)

      Description copied from interface: `ConversionService`
      Returns true if objects of sourceType can be converted to targetType. If this method returns true, it means `ConversionService.convert(Object, Class)` is capable of converting an instance of sourceType to targetType. Special note on collections, arrays, and maps types: For conversion between collection, array, and map types, this method will return 'true' even though a convert invocation may still generate a `ConversionException` if the underlying elements are not convertible. Callers are expected to handle this exceptional case when working with collections and maps.
      Specified by:
        `canConvert` in interface `ConversionService`
      Parameters:
        `sourceType` - the source type to convert from (may be null if source is null)
        `targetType` - the target type to convert to (required)
      Returns:
        true if a conversion can be performed, false if not

    - #### canConvert

          public boolean canConvert(TypeDescriptor sourceType,
                           TypeDescriptor targetType)

      Description copied from interface: `ConversionService`
      Returns true if objects of sourceType can be converted to the targetType. The TypeDescriptors provide additional context about the source and target locations where conversion would occur, often object fields or property locations. If this method returns true, it means `ConversionService.convert(Object, TypeDescriptor, TypeDescriptor)` is capable of converting an instance of sourceType to targetType. Special note on collections, arrays, and maps types: For conversion between collection, array, and map types, this method will return 'true' even though a convert invocation may still generate a `ConversionException` if the underlying elements are not convertible. Callers are expected to handle this exceptional case when working with collections and maps.
      Specified by:
        `canConvert` in interface `ConversionService`
      Parameters:
        `sourceType` - context about the source type to convert from (may be null if source is null)
        `targetType` - context about the target type to convert to (required)
      Returns:
        true if a conversion can be performed between the source and target types, false if not

    - #### canBypassConvert

          public boolean canBypassConvert(TypeDescriptor sourceType,
                                 TypeDescriptor targetType)

      Returns true if conversion between the sourceType and targetType can be bypassed. More precisely this method will return true if objects of sourceType can be converted to the targetType by returning the source object unchanged.
      Parameters:
        `sourceType` - context about the source type to convert from (may be null if source is null)
        `targetType` - context about the target type to convert to (required)
      Returns:
        true if conversion can be bypassed
      Throws:
        `IllegalArgumentException` - if targetType is null
      Since:
        3.2

    - #### convert

          public <T> T convert(Object source,
                      Class<T> targetType)

      Description copied from interface: `ConversionService`
      Convert the source to targetType.
      Specified by:
        `convert` in interface `ConversionService`
      Parameters:
        `source` - the source object to convert (may be null)
        `targetType` - the target type to convert to (required)
      Returns:
        the converted object, an instance of targetType

    - #### convert

          public Object convert(Object source,
                       TypeDescriptor sourceType,
                       TypeDescriptor targetType)

      Description copied from interface: `ConversionService`
      Convert the source to targetType. The TypeDescriptors provide additional context about the source and target locations where conversion will occur, often object fields or property locations.
      Specified by:
        `convert` in interface `ConversionService`
      Parameters:
        `source` - the source object to convert (may be null)
        `sourceType` - context about the source type converting from (may be null if source is null)
        `targetType` - context about the target type to convert to (required)
      Returns:
        the converted object, an instance of `targetType`

    - #### convert

          public Object convert(Object source,
                       TypeDescriptor targetType)

      Convenience operation for converting a source object to the specified targetType, where the targetType is a descriptor that provides additional conversion context. Simply delegates to `convert(Object, TypeDescriptor, TypeDescriptor)` and encapsulates the construction of the sourceType descriptor using `TypeDescriptor.forObject(Object)`.
      Parameters:
        `source` - the source object
        `targetType` - the target type
      Returns:
        the converted value
      Throws:
        `ConversionException` - if a conversion exception occurred
        `IllegalArgumentException` - if targetType is null, or sourceType is null but source is not null

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### convertNullSource

          protected Object convertNullSource(TypeDescriptor sourceType,
                                 TypeDescriptor targetType)

      Template method to convert a null source.

      Default implementation returns `null`. Subclasses may override to return custom null objects for specific target types.

      Parameters:
        `sourceType` - the sourceType to convert from
        `targetType` - the targetType to convert to
      Returns:
        the converted null object

    - #### getConverter

          protected GenericConverter getConverter(TypeDescriptor sourceType,
                                      TypeDescriptor targetType)

      Hook method to lookup the converter for a given sourceType/targetType pair. First queries this ConversionService's converter cache. On a cache miss, then performs an exhaustive search for a matching converter. If no converter matches, returns the default converter. Subclasses may override.
      Parameters:
        `sourceType` - the source type to convert from
        `targetType` - the target type to convert to
      Returns:
        the generic converter that will perform the conversion, or `null` if no suitable converter was found
      See Also:
        `getDefaultConverter(TypeDescriptor, TypeDescriptor)`

    - #### getDefaultConverter

          protected GenericConverter getDefaultConverter(TypeDescriptor sourceType,
                                             TypeDescriptor targetType)

      Return the default converter if no converter is found for the given sourceType/targetType pair. Returns a NO_OP Converter if the sourceType is assignable to the targetType. Returns `null` otherwise, indicating no suitable converter could be found. Subclasses may override.
      Parameters:
        `sourceType` - the source type to convert from
        `targetType` - the target type to convert to
      Returns:
        the default generic converter that will perform the conversion