org.geotoolkit.util.converter
Class ConverterRegistry

Object
  ConverterRegistry

@ThreadSafe
public class ConverterRegistry
extends Object

A collection of Object Converters. A converter from the given source type to the given target type can be obtained by a call to converter(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 system() method.

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 sometime supported), but their behavior may be more ambiguous than in the case of classes because of multi-inheritance in interface hierarchy.

Since:

3.00

Version:

3.17

Author:

Martin Desruisseaux (Geomatys)

Module:

utility/geotk-utility (download)

View source code for this class

Constructor Summary

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

Method Summary

<S,T> ObjectConverter<S,T>	converter(Class<S> source, Class<T> target) Returns a converter for the specified source and target classes.
<T> Class<? extends T>	findCommonTarget(Class<T> base, Class<?>... sources) Returns a target class which is both assignable to the given base and convertible from all the given sources.
void	register(ObjectConverter<?,?> converter) Registers a new converter.
static ConverterRegistry	system() Returns the default system-wide instance.
String	toString() Returns a string representation of registered converters.

Methods inherited from class Object

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

Constructor Detail

ConverterRegistry

public ConverterRegistry()

Creates an initially empty set of object converters.

Method Detail

system

public static ConverterRegistry system()

Returns the default system-wide instance. This register is initialized automatically with conversions between some basic Java and Geotk objects, like conversions between Date and Long. Those conversions are defined for the lifetime of the JVM.

If a temporary set of converters is desired, a new instance of ConverterRegistry should be created explicitly instead.

Adding system-wide converters
Applications can add system-wide custom providers either by explicit call to the register(ObjectConverter) method on the system converter, or by listing the fully qualified classnames of their ObjectConverter instances in the following file (see ServiceLoader for more info about services loading):

META-INF/services/org.geotoolkit.util.converter.ObjectConverter

Returns:

The system-wide registry instance.

register

public void register(ObjectConverter<?,?> converter)

Registers a new converter. This method should be invoked only once for a given converter, typically 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 its 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:

C1
└───C2
    ├───C3
    │   └───S
    └───C4
        └───T

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 converter(Class, Class) is invoked, because we can not know the set of all sub-classes in advance (and would not necessarily want to register all of them anyway).

Parameters:

converter - The converter to register.

converter

public <S,T> ObjectConverter<S,T> converter(Class<S> source,
                                            Class<T> target)
                               throws NonconvertibleObjectException

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:

NonconvertibleObjectException - if no converter is found.

findCommonTarget

public <T> Class<? extends T> findCommonTarget(Class<T> base,
                                               Class<?>... sources)

Returns a target class which is both assignable to the given base and convertible from all the given sources. This method is used mostly for converting two objects of different type to some class implementing the Comparable interface, in order to compare objects that are normally not comparable each other.

Example 1: comparing File with URL
File implements the Comparable interface, while URL does not. Consequently the code below will return unconditionally File no matter the order of sources arguments:

Class<? extends Comparable> target = registry.findCommonTarget(Comparable.class, File.class, URL.class);

Example 2: comparing Date with Long
Both Long and Date implement Comparable, and both types are convertible to the other type. There is no obvious rule for selecting a type instead than the other. In order to keep this method determinist, the code below will prefer the first sources argument assignable to the common target: Long.

Class<? extends Comparable> target = registry.findCommonTarget(Comparable.class, Long.class, Date.class);

Type Parameters:

T - The type represented by the base argument.

Parameters:

base - The base type of the desired target.

sources - The source for which a common target is desired.

Returns:

A target assignable to the given base and convertible from all sources, or null if no suitable target has been found.

Since:

3.01

toString

public String toString()

Returns a string representation of registered converters. Used mostly for debugging purpose.

Overrides:

toString in class Object

Returns:

A string representation of registered converters.