/*
 *    GeoTools - OpenSource mapping toolkit
 *    http://geotools.org
 *    (C) 2004-2006, GeoTools Project Managment Committee (PMC)
 *    (C) 2004, Institut de Recherche pour le Développement
 *   
 *    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.referencing.operation;

// J2SE dependencies and extensions
import java.util.Collection;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import javax.units.Unit;

// OpenGIS dependencies
import org.opengis.metadata.citation.Citation;
import org.opengis.parameter.GeneralParameterDescriptor;
import org.opengis.parameter.GeneralParameterValue;
import org.opengis.parameter.InvalidParameterCardinalityException;
import org.opengis.parameter.InvalidParameterNameException;
import org.opengis.parameter.InvalidParameterValueException;
import org.opengis.parameter.ParameterDescriptor;
import org.opengis.parameter.ParameterDescriptorGroup;
import org.opengis.parameter.ParameterNotFoundException;
import org.opengis.parameter.ParameterValue;
import org.opengis.parameter.ParameterValueGroup;
import org.opengis.referencing.FactoryException;
import org.opengis.referencing.IdentifiedObject;
import org.opengis.referencing.ReferenceIdentifier;
import org.opengis.referencing.operation.MathTransform;
import org.opengis.referencing.operation.OperationMethod;
import org.opengis.referencing.operation.Operation;
import org.opengis.referencing.operation.Projection;
import org.opengis.util.GenericName;

// Geotools dependencies
import org.geotools.metadata.iso.citation.Citations;
import org.geotools.parameter.DefaultParameterDescriptor;
import org.geotools.parameter.DefaultParameterDescriptorGroup;
import org.geotools.resources.Utilities;
import org.geotools.resources.XArray;
import org.geotools.resources.i18n.Errors;
import org.geotools.resources.i18n.ErrorKeys;
import org.geotools.referencing.wkt.Formatter;
import org.geotools.referencing.operation.transform.MathTransformProxy;


/**
 * An {@linkplain DefaultOperationMethod operation method} capable to creates a
 * {@linkplain MathTransform math transform} from set of
 * {@linkplain GeneralParameterValue parameter values}.
 * Implementations of this class should be listed in the following file:
 *
 * <blockquote>
 * <P>{@code META-INF/services/org.geotools.referencing.operation.MathTransformProvider}</P>
 * </blockquote>
 * <P>
 * The {@linkplain DefaultMathTransformFactory math transform factory} will parse this file in order
 * to gets all available providers on a system. If this file is bundle in many JAR files, the
 * {@linkplain DefaultCoordinateOperationFactory math transform factory} will read all of them.
 *
 * @since 2.0
 * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/referencing/src/main/java/org/geotools/referencing/operation/MathTransformProvider.java $
 * @version $Id: MathTransformProvider.java 25262 2007-04-23 21:11:16Z desruisseaux $
 * @author Martin Desruisseaux
 */
public abstract class MathTransformProvider extends DefaultOperationMethod {
    /**
     * Serial number for interoperability with different versions.
     */
    private static final long serialVersionUID = 7530475536803158473L;

    /**
     * Constructs a math transform provider from a set of parameters. The provider
     * {@linkplain #getIdentifiers identifiers} will be the same than the parameter
     * ones.
     *
     * @param sourceDimensions Number of dimensions in the source CRS of this operation method.
     * @param targetDimensions Number of dimensions in the target CRS of this operation method.
     * @param parameters The set of parameters (never {@code null}).
     */
    public MathTransformProvider(final int sourceDimensions,
                                 final int targetDimensions,
                                 final ParameterDescriptorGroup parameters)
    {
        this(toMap(parameters), sourceDimensions, targetDimensions, parameters);
    }

    /**
     * Constructs a math transform provider from a set of properties.
     * The properties map is given unchanged to the
     * {@linkplain DefaultOperationMethod#DefaultOperationMethod(Map,int,int,ParameterDescriptorGroup)
     * super-class constructor}.
     *
     * @param properties Set of properties. Should contains at least <code>"name"</code>.
     * @param sourceDimensions Number of dimensions in the source CRS of this operation method.
     * @param targetDimensions Number of dimensions in the target CRS of this operation method.
     * @param parameters The set of parameters (never {@code null}).
     */
    public MathTransformProvider(final Map properties,
                                 final int sourceDimensions,
                                 final int targetDimensions,
                                 final ParameterDescriptorGroup parameters)
    {
        super(properties, sourceDimensions, targetDimensions, parameters);        
    }

    /**
     * Work around for RFE #4093999 in Sun's bug database
     * ("Relax constraint on placement of this()/super() call in constructors").
     */
    private static Map toMap(final IdentifiedObject parameters) {
        ensureNonNull("parameters", parameters);
        final Map properties = new HashMap(4);
        properties.put(NAME_KEY,        parameters.getName());
        properties.put(IDENTIFIERS_KEY, parameters.getIdentifiers().toArray(EMPTY_IDENTIFIER_ARRAY));
        properties.put(ALIAS_KEY,       parameters.getAlias()      .toArray(EMPTY_ALIAS_ARRAY));
        return properties;
    }

    /**
     * Returns the operation type. It may be
     * <code>{@linkplain org.opengis.referencing.operation.Operation}.class</code>,
     * <code>{@linkplain org.opengis.referencing.operation.Conversion}.class</code>,
     * <code>{@linkplain org.opengis.referencing.operation.Projection}.class</code>,
     * <cite>etc</cite>.
     *
     * The default implementation returns {@code Operation.class}.
     * Subclass should overrides this methods and returns the appropriate
     * OpenGIS interface type (<strong>not</strong> the implementation type).
     */
    public Class getOperationType() {
        return Operation.class;
    }

    /**
     * Creates a math transform from the specified group of parameter values.
     * Subclasses can implements this method as in the example below:
     *
     * <blockquote><pre>
     * double semiMajor = values.parameter("semi_major").doubleValue(SI.METER);
     * double semiMinor = values.parameter("semi_minor").doubleValue(SI.METER);
     * // etc...
     * return new MyTransform(semiMajor, semiMinor, ...);
     * </pre></blockquote>
     *
     * @param  values The group of parameter values.
     * @return The created math transform.
     * @throws InvalidParameterNameException if the values contains an unknow parameter.
     * @throws ParameterNotFoundException if a required parameter was not found.
     * @throws InvalidParameterValueException if a parameter has an invalid value.
     * @throws FactoryException if the math transform can't be created for some other reason
     *         (for example a required file was not found).
     *
     * @see MathTransformProvider.Delegate
     */
    protected abstract MathTransform createMathTransform(ParameterValueGroup values)
            throws InvalidParameterNameException,
                   ParameterNotFoundException,
                   InvalidParameterValueException,
                   FactoryException;

    /**
     * Constructs a parameter descriptor from a set of alias. The parameter is
     * identified by codes provided by one or more authorities. Common authorities are
     * {@link Citations#OGC OGC} and {@link Citations#EPSG EPSG} for example.
     *
     * <P>The first entry in the {@code identifiers} array is both the
     * {@linkplain ParameterDescriptor#getName main name} and the
     * {@linkplain ParameterDescriptor#getIdentifiers identifiers}.
     * All others are {@linkplain ParameterDescriptor#getAlias aliases}.</P>
     *
     * @param identifiers  The parameter identifiers. Most contains at least one entry.
     * @param defaultValue The default value for the parameter, or {@link Double#NaN} if none.
     * @param minimum The minimum parameter value, or {@link Double#NEGATIVE_INFINITY} if none.
     * @param maximum The maximum parameter value, or {@link Double#POSITIVE_INFINITY} if none.
     * @param unit    The unit for default, minimum and maximum values.
     */
    protected static ParameterDescriptor createDescriptor(final ReferenceIdentifier[] identifiers,
            final double defaultValue, final double minimum, final double maximum, final Unit unit)
    {
        return new DefaultParameterDescriptor(toMap(identifiers), defaultValue,
                                              minimum, maximum, unit, true);
    }

    /**
     * Constructs an optional parameter descriptor from a set of alias.
     * The parameter is identified as with {@link #createDescriptor}.
     *
     * @param identifiers The parameter identifiers. Most contains at least one entry.
     * @param minimum The minimum parameter value, or {@link Double#NEGATIVE_INFINITY} if none.
     * @param maximum The maximum parameter value, or {@link Double#POSITIVE_INFINITY} if none.
     * @param unit    The unit for default, minimum and maximum values.
     */
    protected static ParameterDescriptor createOptionalDescriptor(
            final ReferenceIdentifier[] identifiers,
            final double minimum, final double maximum, final Unit unit)
    {
        return new DefaultParameterDescriptor(toMap(identifiers), Double.NaN,
                                              minimum, maximum, unit, false);
    }

    /**
     * Constructs a parameter group from a set of alias. The parameter group is
     * identified by codes provided by one or more authorities. Common authorities are
     * {@link Citations#OGC OGC} and {@link Citations#EPSG EPSG} for example.
     * <P>
     * Special rules:
     * <ul>
     *   <li>The first entry in the {@code identifiers} array is the
     *       {@linkplain ParameterDescriptorGroup#getName primary name}.</li>
     *   <li>If a an entry do not implements the {@link GenericName} interface, it is
     *       an {@linkplain ParameterDescriptorGroup#getIdentifiers identifiers}.</li>
     *   <li>All others are {@linkplain ParameterDescriptorGroup#getAlias aliases}.</li>
     * </ul>
     *
     * @param identifiers  The operation identifiers. Most contains at least one entry.
     * @param parameters   The set of parameters, or {@code null} or an empty array if none.
     */
    protected static ParameterDescriptorGroup createDescriptorGroup(
            final ReferenceIdentifier[] identifiers, final GeneralParameterDescriptor[] parameters)
    {
        return new DefaultParameterDescriptorGroup(toMap(identifiers), parameters);
    }

    /**
     * Put the identifiers into a properties map suitable for {@link IdentifiedObject}
     * constructor.
     */
    private static Map toMap(final ReferenceIdentifier[] identifiers) {
        ensureNonNull("identifiers", identifiers);
        if (identifiers.length == 0) {
            throw new IllegalArgumentException(Errors.format(ErrorKeys.EMPTY_ARRAY));
        }
        int idCount    = 0;
        int aliasCount = 0;
        ReferenceIdentifier[] id = new ReferenceIdentifier[identifiers.length];
        GenericName[]      alias = new GenericName        [identifiers.length];
        for (int i=0; i<identifiers.length; i++) {
            final ReferenceIdentifier candidate = identifiers[i];
            if (candidate instanceof GenericName) {
                alias[aliasCount++] = (GenericName) candidate;
            } else {
                id[idCount++] = candidate;
            }
        }
        id    = (ReferenceIdentifier[]) XArray.resize(id,       idCount);
        alias = (GenericName[])         XArray.resize(alias, aliasCount);
        final Map properties = new HashMap(4, 0.8f);
        properties.put(NAME_KEY,        identifiers[0]);
        properties.put(IDENTIFIERS_KEY, id);
        properties.put(ALIAS_KEY,       alias);
        return properties;
    }

    /**
     * Ensures that the given set of parameters contains only valid values.
     * This method compares all parameter names against the names declared in the
     * {@linkplain #getParameters operation method parameter descriptor}. If an unknow
     * parameter name is found, then an {@link InvalidParameterNameException} is thrown.
     * This method also ensures that all values are assignable to the
     * {@linkplain ParameterDescriptor#getValueClass expected class}, are between the
     * {@linkplain ParameterDescriptor#getMinimumValue minimum} and
     * {@linkplain ParameterDescriptor#getMaximumValue maximum} values and are one of the
     * {@linkplain ParameterDescriptor#getValidValues set of valid values}.
     * If the value fails any of those tests, then an
     * {@link InvalidParameterValueException} is thrown.
     *
     * @param  values The parameters values to check.
     * @return The parameter values to use for {@linkplain MathTransform math transform}
     *         construction. May be different than the supplied {@code values}
     *         argument if some missing values needed to be filled with default values.
     * @throws InvalidParameterNameException if a parameter name is unknow.
     * @throws InvalidParameterValueException if a parameter has an invalid value.
     */
    protected ParameterValueGroup ensureValidValues(final ParameterValueGroup values)
            throws InvalidParameterNameException, InvalidParameterValueException
    {
        final ParameterDescriptorGroup parameters = getParameters();
        final GeneralParameterDescriptor descriptor = values.getDescriptor();
        if (parameters.equals(descriptor)) {
            /*
             * Since the "official" parameter descriptor was used, the descriptor should
             * have already enforced argument validity. Consequently, there is no need to
             * performs the check and we will avoid it as a performance enhancement.
             */
            return values;
        }
        /*
         * Copy the all values from the user-supplied group to the provider-supplied group.
         * The provider group should performs all needed checks. Furthermore, it is suppliers
         * responsability to know about alias (e.g. OGC, EPSG, ESRI), while the user will
         * probably use the name from only one authority. With a copy, we gives a chances to
         * the provider-supplied parameters to uses its alias for understanding the user
         * parameter names.
         */
        final ParameterValueGroup copy = (ParameterValueGroup) parameters.createValue();
        copy(values, copy);
        return copy;
    }

    /**
     * Implementation of {@code ensureValidValues}, to be invoked recursively
     * if the specified values contains sub-groups of values. This method copy all
     * values from the user-supplied parameter values into the provider-supplied
     * one. The provider one should understand alias, and performs name conversion
     * as well as argument checking on the fly.
     *
     * @param  values The parameters values to copy.
     * @param  copy   The parameters values where to put the copy.
     * @throws InvalidParameterNameException if a parameter name is unknow.
     * @throws InvalidParameterValueException if a parameter has an invalid value.
     */
    private static void copy(final ParameterValueGroup values,
                             final ParameterValueGroup copy)
            throws InvalidParameterNameException, InvalidParameterValueException
    {
        for (final Iterator it=values.values().iterator(); it.hasNext();) {
            final GeneralParameterValue value = (GeneralParameterValue) it.next();
            final String name = value.getDescriptor().getName().getCode();
            if (value instanceof ParameterValueGroup) {
                /*
                 * Contains sub-group - invokes 'copy' recursively.
                 */
                final GeneralParameterDescriptor descriptor;
                descriptor = ((ParameterDescriptorGroup) copy.getDescriptor()).descriptor(name);
                if (descriptor instanceof ParameterDescriptorGroup) {
                    final ParameterValueGroup groups = (ParameterValueGroup) descriptor.createValue();
                    copy((ParameterValueGroup) value, groups);
                    values.groups(name).add(groups);
                    continue;
                } else {
                    throw new InvalidParameterNameException(Errors.format(
                              ErrorKeys.UNEXPECTED_PARAMETER_$1, name), name);
                }
            }
            /*
             * Single parameter - copy the value, with special care for value with units.
             */
            final ParameterValue source = (ParameterValue) value;
            final ParameterValue target;
            try {
                target = copy.parameter(name);
            } catch (ParameterNotFoundException cause) {
                final InvalidParameterNameException exception =
                      new InvalidParameterNameException(Errors.format(
                          ErrorKeys.UNEXPECTED_PARAMETER_$1, name), name);
                exception.initCause(cause);
                throw exception;
            }
            final Object v  = source.getValue();
            final Unit unit = source.getUnit();
            if (unit == null) {
                target.setValue(v);
            } else if (v instanceof Number) {
                target.setValue(((Number) v).doubleValue(), unit);
            } else if (v instanceof double[]) {
                target.setValue((double[]) v, unit);
            } else {
                throw new InvalidParameterValueException(Errors.format(
                          ErrorKeys.ILLEGAL_ARGUMENT_$2, name, v), name, v);
            }
        }
    }

    /**
     * Returns the parameter value for the specified operation parameter.
     * This convenience method is used by subclasses for initializing
     * {@linkplain MathTransform math transform} from a set of parameters.
     *
     * @param  param The parameter to look for.
     * @param  group The parameter value group to search into.
     * @return The requested parameter value.
     * @throws ParameterNotFoundException if the parameter is not found.
     */
    private static ParameterValue getParameter(final ParameterDescriptor param,
                                               final ParameterValueGroup group)
            throws ParameterNotFoundException
    {
        /*
         * Search for an identifier matching the group's authority, if any.
         * This is needed if the parameter values group was created from an
         * EPSG database for example: we need to use the EPSG names instead
         * of the OGC ones.
         */
        String name = getName(param, group.getDescriptor().getName().getAuthority());
        if (name == null) {
            name = param.getName().getCode();
        }
        if (param.getMinimumOccurs() != 0) {
            return group.parameter(name);
        }
        /*
         * The parameter is optional. We don't want to invokes 'parameter(name)', because we don't
         * want to create a new parameter is the user didn't supplied one. Search the parameter
         * ourself (so we don't create any), and returns null if we don't find any.
         *
         * TODO: A simplier solution would be to add a 'isDefined' method in GeoAPI,
         *       or something similar.
         */
        final GeneralParameterDescriptor search;
        search = ((ParameterDescriptorGroup) group.getDescriptor()).descriptor(name);
        if (search instanceof ParameterDescriptor) {
            for (final Iterator it=group.values().iterator(); it.hasNext();) {
                final GeneralParameterValue candidate = (GeneralParameterValue) it.next();
                if (search.equals(candidate.getDescriptor())) {
                    return (ParameterValue) candidate;
                }
            }        
        }
        return null;
    }

    /**
     * Returns the parameter value for the specified operation parameter.
     * This convenience method is used by subclasses for initializing
     * {@linkplain MathTransform math transform} from a set of parameters.
     *
     * @param  param The parameter to look for.
     * @param  group The parameter value group to search into.
     * @return The requested parameter value, or {@code null} if {@code param} is
     *         {@linkplain #createOptionalDescriptor optional} and the user didn't
     *         provided any value.
     * @throws ParameterNotFoundException if the parameter is not found.
     *
     * @todo Move to the {@link org.geotools.parameter.Parameters} class.
     */
    protected static Object value(final ParameterDescriptor param,
                                  final ParameterValueGroup group)
            throws ParameterNotFoundException
    {
        final ParameterValue value = getParameter(param, group);
        return (value!=null) ? value.getValue() : null;
    }

    /**
     * Returns the parameter value for the specified operation parameter.
     * This convenience method is used by subclasses for initializing
     * {@linkplain MathTransform math transform} from a set of parameters.
     *
     * @param  param The parameter to look for.
     * @param  group The parameter value group to search into.
     * @return The requested parameter value, or {@code null} if {@code param} is
     *         {@linkplain #createOptionalDescriptor optional} and the user didn't
     *         provided any value.
     * @throws ParameterNotFoundException if the parameter is not found.
     *
     * @todo Move to the {@link org.geotools.parameter.Parameters} class.
     */
    protected static String stringValue(final ParameterDescriptor param,
                                        final ParameterValueGroup group)
            throws ParameterNotFoundException
    {
        final ParameterValue value = getParameter(param, group);
        return (value!=null) ? value.stringValue() : null;
    }

    /**
     * Returns the parameter value for the specified operation parameter.
     * This convenience method is used by subclasses for initializing
     * {@linkplain MathTransform math transform} from a set of parameters.
     *
     * @param  param The parameter to look for.
     * @param  group The parameter value group to search into.
     * @return The requested parameter value, or {@code 0} if {@code param} is
     *         {@linkplain #createOptionalDescriptor optional} and the user didn't
     *         provided any value.
     * @throws ParameterNotFoundException if the parameter is not found.
     *
     * @todo Move to the {@link org.geotools.parameter.Parameters} class.
     */
    protected static int intValue(final ParameterDescriptor param,
                                  final ParameterValueGroup group)
            throws ParameterNotFoundException
    {
        final ParameterValue value = getParameter(param, group);
        return (value!=null) ? value.intValue() : 0;
    }

    /**
     * Returns the parameter value for the specified operation parameter.
     * Values are automatically converted into the standard units specified
     * by the supplied {@code param} argument.
     * This convenience method is used by subclasses for initializing
     * {@linkplain MathTransform math transform} from a set of parameters.
     *
     * @param  param The parameter to look for.
     * @param  group The parameter value group to search into.
     * @return The requested parameter value, or {@code NaN} if {@code param} is
     *         {@linkplain #createOptionalDescriptor optional} and the user didn't
     *         provided any value.
     * @throws ParameterNotFoundException if the parameter is not found.
     *
     * @todo Move to the {@link org.geotools.parameter.Parameters} class.
     */
    protected static double doubleValue(final ParameterDescriptor param,
                                        final ParameterValueGroup group)
            throws ParameterNotFoundException
    {
        final Unit unit = param.getUnit();
        final ParameterValue value = getParameter(param, group);
        return (value==null) ? Double.NaN :
                (unit!=null) ? value.doubleValue(unit) : value.doubleValue();
    }

    /**
     * Format the inner part of a
     * <A HREF="http://geoapi.sourceforge.net/snapshot/javadoc/org/opengis/referencing/doc-files/WKT.html"><cite>Well
     * Known Text</cite> (WKT)</A> element.
     *
     * @param  formatter The formatter to use.
     * @return The WKT element name.
     */
    protected String formatWKT(final Formatter formatter) {
        final Class type = getOperationType();
        if (Projection.class.isAssignableFrom(type)) {
            return super.formatWKT(formatter);
        }
        formatter.setInvalidWKT(OperationMethod.class);
        return "OperationMethod";
    }

    /**
     * The result of a call to {@link MathTransformProvider#createMathTransform createMathTransform}.
     * This class encapsulates a reference to the {@linkplain #method originating provider}
     * as well as the {@linkplain #transform created math transform}. This information is needed
     * when a provider delegates the work to an other provider according the parameter values.
     * For example a generic instance of
     * {@link org.geotools.referencing.operation.transform.ProjectiveTransform.ProviderAffine
     * ProviderAffine} may delegates the creation of an <cite>affine transform</cite> to an other
     * {@code ProviderAffine} instance with <cite>source</cite> and <cite>target</cite> dimensions
     * matching the supplied parameters, because those dimensions determine the set of legal
     * <code>"elt_<var>j</var>_<var>i</var>"</code> parameters.
     * <p>
     * Most {@linkplain MathTransformProvider math transform provider} do not delegate their work
     * to an other one, and consequently do not need this class.
     * <p>
     * Future Geotools version may extends this class for handling more information than just the
     * {@linkplain #transform transform} creator. This class is more convenient than adding new
     * methods right into {@link MathTransformProvider}, because it is sometime difficult for a
     * provider to infer all the conditions prevaling when
     * {@link MathTransformProvider#createMathTransform createMathTransform} was executed.
     * Furthermore, it avoid to pollute {@code MathTransformProvider} with methods unused
     * for the vast majority of providers.
     *
     * @version $Id: MathTransformProvider.java 25262 2007-04-23 21:11:16Z desruisseaux $
     * @author Martin Desruisseaux
     *
     * @since 2.2
     */
    protected static final class Delegate extends MathTransformProxy {
        /**
         * The provider for the {@linkplain #transform transform}.
         */
        public final OperationMethod method;

        /**
         * Encapsulates the math transform created by the specified provider.
         */
        public Delegate(final MathTransform transform, final OperationMethod method) {
            super(transform);
            this.method = method;
            ensureNonNull("transform", transform);
            ensureNonNull("method",    method);
        }
    }
}
