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

org.springframework.core.convert

## Interface ConversionService

- All Known Subinterfaces:
    ConfigurableConversionService
  All Known Implementing Classes:
    DefaultConversionService, DefaultFormattingConversionService, FormattingConversionService, GenericConversionService

      public interface ConversionService

  A service interface for type conversion. This is the entry point into the convert system. Call `convert(Object, Class)` to perform a thread-safe type conversion using this system.
  Since:
    3.0
  Author:
    Keith Donald, Phillip Webb

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 sourceType, TypeDescriptor targetType)` Convert the source to targetType.

- - ### Method Detail

    - #### canConvert

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

      Returns true if objects of sourceType can be converted to targetType. If this method returns true, it means `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.
      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
      Throws:
        `IllegalArgumentException` - if targetType is null

    - #### canConvert

          boolean canConvert(TypeDescriptor sourceType,
                           TypeDescriptor targetType)

      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 `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.
      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
      Throws:
        `IllegalArgumentException` - if targetType is null

    - #### convert

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

      Convert the source to targetType.
      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
      Throws:
        `ConversionException` - if a conversion exception occurred
        `IllegalArgumentException` - if targetType is null

    - #### convert

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

      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.
      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`
      Throws:
        `ConversionException` - if a conversion exception occurred
        `IllegalArgumentException` - if targetType is null
        `IllegalArgumentException` - if sourceType is null but source is not null