ObjectConverter changes for revisions 22626

The idea behind the SIS ObjectConverter interface was originally loosely inspired from the GeoTools Converter interface, which is reported here. Very similar interfaces are also found in Spring (Converter interface) and the Apache Camel project (TypeConverter interface), so it is possible to said that the SIS/Geotk interface is inspired by any of them. Rewriting the interface from scratch (which we did) can only produce something close to any of the above-cited existing interfaces.

The SIS/Geotk interface is very different than the original GeoTools one, and much closer to the Spring one. The GeoTools interface provides the following methods:

• boolean canConvert(Class source, Class target);
• <T> T convert(Object source, Class<T> target) throws Exception;

While SIS/Geotk provides the following methods (among others). Note the similarity with Spring Converter, which defines only the T convert(S object) method.

• Class<? super S> getSourceClass();
• Class<? extends T> getTargetClass();
• T convert(S object) throws UnconvertibleObjectException;

SIS/Geotk has not retained the canConvert method, since it is considered ConverterRegistry job. The convert method lost the Class argument, since the target type is fixed at creation time. The method signature has been changed for enforcing type safety in the object argument.

The GeoTools Converter can be though as both a converter and a factory finding the conversion algorithm for an arbitrary pair of source and target classes. SIS/Geotk takes an other approach, where the two steps (finding the conversion algorithm, then applying the conversion) are separated. The SIS/Geotk ObjectConverter is much more similar to a UnitConverter or a CoordinateOperation in design. Incidentally, this make the SIS/Geotk interface close to identical to the Spring one (ignoring the additional methods).

Command line:

svn cat -r22626 https://svn.osgeo.org/geotools/trunk/modules/library/api/src/main/java/org/geotools/util/Converter.java

/*
 *    GeoTools - OpenSource mapping toolkit
 *    http://geotools.org
 *    (C) 2002-2006, GeoTools Project Managment Committee (PMC)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotools.util;


/**
 * Converts values of one type into another.
 *
 * @author Justin Deoliveira, The Open Planning Project
 *
 */
public interface Converter {
    /**
     * Determines if this converter can convert instances of one type into another.
     *
     * @param source The type being converted from.
     * @param terget The type being converted to.
     *
     * @return <code>true</code> if the conversion can take place with the givem arguments,
     * otherwise <code>false</code>.
     */
    boolean canConvert(Class source, Class target);

    /**
     * Converts an object to an object of another type.
     * <p>
     * This method should not be called unless <code>canConvert( object.getClass(), target )<code>
     * returns <code>true</code>.
     * </p>
     *
     * @param source The original object, never <code>null</code>
     * @param target The type of the converted object.
     *
     * @return An instance of target, or <code>null</code> if the conversion could not take place.
     */
    Object convert(Object source, Class target) throws Exception;
}