Module org.apache.sis.util
Package org.apache.sis.util

# Class ObjectConverters

Object
Static
ObjectConverters

public final class ObjectConverters extends Static
Static methods for creating `ObjectConverter` instances or collection views based on converters. Converters are created by the following methods:

- `identity(Class)`
- `find(Class, Class)`

Converters can be used for creating derived collections by the following methods:

- `derivedSet(Set, ObjectConverter)`
- `derivedMap(Map, ObjectConverter, ObjectConverter)`
- `derivedKeys(Map, ObjectConverter, Class)`
- `derivedValues(Map, Class, ObjectConverter)`

## Example

the following code converts instances in a collection from type `S` to type `T`, where the types are unknown at compile-time. Note that the converter is obtained only once before to be applied to every elements in the loop.

    Class<S> sourceType = ...
    Class<T> targetType = ...
    Collection<S> sources = ...;
    Collection<T> targets = ...;
    ObjectConverter<S,T> converter = ObjectConverters.find(sourceType, targetType);
    for (S source : sources) {
        targets.add(converter.apply(source));
    }

Since:
  0.3
See Also:
  - `ObjectConverter`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> T`
  `convert(Object value, Class<T> target)`
  Converts the given value to the given type.
  `static <SK, K, V> Map<K,V>`
  `derivedKeys(Map<SK,V> storage, ObjectConverter<SK,K> keyConverter, Class<V> valueType)`
  Returns a map whose keys are derived on-the-fly from the given map.
  `static <SK, SV, K, V>
  Map<K,V>`
  `derivedMap(Map<SK,SV> storage, ObjectConverter<SK,K> keyConverter, ObjectConverter<SV,V> valueConverter)`
  Returns a map whose keys and values are derived on-the-fly from the given map.
  `static <S, E> Set<E>`
  `derivedSet(Set<S> storage, ObjectConverter<S,E> converter)`
  Returns a set whose elements are derived on-the-fly from the given set.
  `static <K, SV, V> Map<K,V>`
  `derivedValues(Map<K,SV> storage, Class<K> keyType, ObjectConverter<SV,V> valueConverter)`
  Returns a map whose values are derived on-the-fly from the given map.
  `static <S, T> ObjectConverter<? super S,? extends T>`
  `find(Class<S> source, Class<T> target)`
  Returns a converter for the specified source and target classes.
  `static <T> ObjectConverter<T,T>`
  `identity(Class<T> type)`
  Returns an identity converter for objects of the given type.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### identity

    public static <T> ObjectConverter<T,T> identity(Class<T> type)
    Returns an identity converter for objects of the given type.
    Type Parameters:
      `T` - the object type.
    Parameters:
      `type` - the object type.
    Returns:
      an identity converter for objects of the given type.

  - ### find

    public static <S, T> ObjectConverter<? super S,? extends T> find(Class<S> source, Class<T> target) throws UnconvertibleObjectException
    Returns a converter for the specified source and target classes.
    Type Parameters:
      `S` - the source class.
      `T` - the target class.
    Parameters:
      `source` - the source class.
      `target` - the target class, or `Object​.class` for any.
    Returns:
      the converter from the specified source class to the target class.
    Throws:
      `UnconvertibleObjectException` - if no converter is found.

  - ### convert

    public static <T> T convert(Object value, Class<T> target) throws UnconvertibleObjectException
    Converts the given value to the given type. This convenience method shall be used only for rare conversions. For converting many instances between the same source and target classes, consider invoking `find(Class, Class)` instead in order to reuse the same converter for all values to convert.
    Type Parameters:
      `T` - the type of the `target` class.
    Parameters:
      `value` - the value to convert, or `null`.
      `target` - the target class.
    Returns:
      the converted value (may be `null`).
    Throws:
      `UnconvertibleObjectException` - if the given value cannot be converted.

  - ### derivedSet

    public static <S, E> Set<E> derivedSet(Set<S> storage, ObjectConverter<S,E> converter)
    Returns a set whose elements are derived on-the-fly from the given set. Conversions from the original elements to the derived elements are performed when needed by invoking the `ObjectConverter​.apply(Object)` method on the given converter.

    This convenience method delegates to `Containers​.derivedSet(…)`. See the javadoc of the above method for more information.

    Type Parameters:
      `S` - the type of elements in the storage (original) set.
      `E` - the type of elements in the derived set.
    Parameters:
      `storage` - the storage set containing the original elements, or `null`.
      `converter` - the converter from the elements in the storage set to the elements in the derived set.
    Returns:
      a view over the `storage` set containing all elements converted by the given converter, or `null` if `storage` was null.
    See Also:
      - `Containers​.derivedSet(Set, ObjectConverter)`

  - ### derivedMap

    public static <SK, SV, K, V> Map<K,V> derivedMap(Map<SK,SV> storage, ObjectConverter<SK,K> keyConverter, ObjectConverter<SV,V> valueConverter)
    Returns a map whose keys and values are derived on-the-fly from the given map. Conversions from the original entries to the derived entries are performed when needed by invoking the `ObjectConverter​.apply(Object)` method on the given converters.

    This convenience method delegates to `Containers​.derivedMap(…)`. See the javadoc of the above method for more information.

    Type Parameters:
      `SK` - the type of keys in the storage map.
      `SV` - the type of values in the storage map.
      `K` - the type of keys in the derived map.
      `V` - the type of values in the derived map.
    Parameters:
      `storage` - the storage map containing the original entries, or `null`.
      `keyConverter` - the converter from the keys in the storage map to the keys in the derived map.
      `valueConverter` - the converter from the values in the storage map to the values in the derived map.
    Returns:
      a view over the `storage` map containing all entries converted by the given converters, or `null` if `storage` was null.
    See Also:
      - `Containers​.derivedMap(Map, ObjectConverter, ObjectConverter)`

  - ### derivedKeys

    public static <SK, K, V> Map<K,V> derivedKeys(Map<SK,V> storage, ObjectConverter<SK,K> keyConverter, Class<V> valueType)
    Returns a map whose keys are derived on-the-fly from the given map. Conversions from the original keys to the derived keys are performed when needed by invoking the `ObjectConverter​.apply(Object)` method on the given converter.

    This convenience method delegates to `Containers​.derivedMap(…)`. See the javadoc of the above method for more information.

    Type Parameters:
      `SK` - the type of keys in the storage map.
      `K` - the type of keys in the derived map.
      `V` - the type of values in the storage and derived map.
    Parameters:
      `storage` - the storage map containing the original entries, or `null`.
      `keyConverter` - the converter from the keys in the storage map to the keys in the derived map.
      `valueType` - the type of values in the storage and derived map.
    Returns:
      a view over the `storage` map containing all entries with the keys converted by the given converter, or `null` if `storage` was null.
    See Also:
      - `Containers​.derivedMap(Map, ObjectConverter, ObjectConverter)`

  - ### derivedValues

    public static <K, SV, V> Map<K,V> derivedValues(Map<K,SV> storage, Class<K> keyType, ObjectConverter<SV,V> valueConverter)
    Returns a map whose values are derived on-the-fly from the given map. Conversions from the original values to the derived values are performed when needed by invoking the `ObjectConverter​.apply(Object)` method on the given converter.

    This convenience method delegates to `Containers​.derivedMap(…)`. See the javadoc of the above method for more information.

    Type Parameters:
      `K` - the type of keys in the storage and derived map.
      `SV` - the type of values in the storage map.
      `V` - the type of values in the derived map.
    Parameters:
      `storage` - the storage map containing the original entries, or `null`.
      `keyType` - the type of keys in the storage and derived map.
      `valueConverter` - the converter from the values in the storage map to the values in the derived map.
    Returns:
      a view over the `storage` map containing all entries with the values converted by the given converter, or `null` if `storage` was null.
    See Also:
      - `Containers​.derivedMap(Map, ObjectConverter, ObjectConverter)`