Package org.apache.sis.internal.converter

Class ConverterRegistry

java.lang.Object
org.apache.sis.internal.converter.ConverterRegistry
Direct Known Subclasses:
SystemRegistry
public class ConverterRegistry extends Object
A collection of ObjectConverter instances. A converter from the given source type to the given target type can be obtained by a call to find(Class, Class). If no converter exists for the given source and target types, then this registry searches for a suitable converter accepting a parent class of the given source type, or returning a sub-class of the given target type.

New instances of ConverterRegistry are initially empty. Custom converters must be explicitly registered. However, a system-wide registry initialized with default converters is provided by the SystemRegistry.INSTANCE constant.

Note about conversions from interfaces

ConverterRegistry is primarily designed for handling converters from classes to other classes. Handling of interfaces are not prohibited (and actually sometimes supported), but their behavior may be more ambiguous than in the case of classes because of multi-inheritance in interface hierarchy.

Thread safety

This base class is thread-safe. Subclasses shall make sure that any overridden methods remain safe to call from multiple threads.
Since:
0.3
Version:
0.8
Author:
Martin Desruisseaux (Geomatys)

  • Constructor Summary

    Constructors
    Constructor
    Description
    ConverterRegistry()
    Creates an initially empty set of object converters.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Removes all converters from this registry and set this ServiceRegistry state to uninitialized.
    protected <S, T> ObjectConverter<S,T>
    createConverter(Class<S> sourceClass, Class<T> targetClass)
    Creates a new converter for the given source and target types, or null if none.
    <S, T> ObjectConverter<? super S,? extends T>
    find(Class<S> sourceClass, Class<T> targetClass)
    Returns a converter suitable for the given source and target classes.
    <S, T> ObjectConverter<S,T>
    findExact(Class<S> sourceClass, Class<T> targetClass)
    Returns a converter for exactly the given source and target classes.
    protected void
    initialize()
    Invoked when this ConverterRegistry needs to be initialized.
    <S, T> void
    register(ObjectConverter<S,T> converter)
    Registers a new converter.
    String
    toString()
    Returns a string representation of registered converters for debugging purpose.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ConverterRegistry

      public ConverterRegistry()
      Creates an initially empty set of object converters.

  • Method Details

    • initialize

      protected void initialize()
      Invoked when this ConverterRegistry needs to be initialized. This method is automatically invoked the first time that register(ObjectConverter) or find(Class, Class) is invoked.

      The default implementation does nothing. Subclasses can override this method in order to register a default set of converters. For example, a subclass could fetch the ObjectConverter instances from the META-INF/services directories as below:

    • clear

      public void clear()
      Removes all converters from this registry and set this ServiceRegistry state to uninitialized. The initialize() method will be invoked again when first needed.

    • register

      public <S, T> void register(ObjectConverter<S,T> converter)
      Registers a new converter. This method should be invoked only once for a given converter, for example in class static initializer. For example if a Angle class is defined, the static initializer of that class could register a converter from Angle to Double.

      This method registers the converter for the target class, some parents of the target class (see below) and every interfaces except Cloneable which are implemented by the target class and not by the source class. For example, a converter producing Double can be used for clients that just ask for a Number.

      Which super-classes of the target class are registered

      Consider a converter from class S to class T where the two classes are related in a hierarchy as below: Invoking this method will register the given converter for all the following cases:
      • S → T
      • S → C4
      No S → C2 or S → C1 converter will be registered, because an identity converter would be sufficient for those cases.

      Which sub-classes of the source class are registered

      Sub-classes of the source class will be registered on a case-by-case basis when the find(Class, Class) is invoked, because we cannot know the set of all sub-classes in advance (and would not necessarily want to register all of them anyway).
      Type Parameters:
      S - the class of source value.
      T - the class of target (converted) values.
      Parameters:
      converter - the converter to register.

    • findExact

      public <S, T> ObjectConverter<S,T> findExact(Class<S> sourceClass, Class<T> targetClass) throws UnconvertibleObjectException
      Returns a converter for exactly the given source and target classes. The default implementation invokes find(Class, Class), then ensures that the converter source and target classes are the same ones than the classes given in argument to this method.
      Type Parameters:
      S - the source class.
      T - the target class.
      Parameters:
      sourceClass - the source class.
      targetClass - 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 for the given classes.

    • find

      public <S, T> ObjectConverter<? super S,? extends T> find(Class<S> sourceClass, Class<T> targetClass) throws UnconvertibleObjectException
      Returns a converter suitable for the given source and target classes. This method may return a converter accepting more generic sources or converting to more specific targets.
      Type Parameters:
      S - the source class.
      T - the target class.
      Parameters:
      sourceClass - the source class.
      targetClass - 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 for the given classes.

    • createConverter

      protected <S, T> ObjectConverter<S,T> createConverter(Class<S> sourceClass, Class<T> targetClass)
      Creates a new converter for the given source and target types, or null if none. This method is invoked by find(source, target) when no registered converter were found for the given types.

      The default implementation checks for the trivial case where an identity converter would fit, and returns null in all other cases. Subclasses can override this method in order to generate some converters dynamically.

      Type Parameters:
      S - the source class.
      T - the target class.
      Parameters:
      sourceClass - the source class.
      targetClass - the target class, or Object.class for any.
      Returns:
      a newly generated converter from the specified source class to the target class, or null if none.

    • toString

      public String toString()
      Returns a string representation of registered converters for debugging purpose. The converters are show in a tree where all real converters are leafs. Parents of those leafs are FallbackConverters which delegate their work to the leafs.
      Overrides:
      toString in class Object
      Returns:
      a string representation of registered converters.