/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.sis.referencing.operation;

import java.util.Map;
import java.util.HashMap;
import java.util.List;
import java.util.Objects;
import java.util.Collections;
import javax.xml.bind.annotation.XmlType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlSchemaType;
import org.opengis.util.InternationalString;
import org.opengis.metadata.citation.Citation;
import org.opengis.referencing.IdentifiedObject;
import org.opengis.referencing.operation.Formula;
import org.opengis.referencing.operation.Conversion;
import org.opengis.referencing.operation.Projection;
import org.opengis.referencing.operation.MathTransform;
import org.opengis.referencing.operation.OperationMethod;
import org.opengis.referencing.operation.SingleOperation;
import org.opengis.referencing.crs.GeneralDerivedCRS;
import org.opengis.parameter.GeneralParameterDescriptor;
import org.opengis.parameter.ParameterDescriptorGroup;
import org.opengis.parameter.ParameterDescriptor;
import org.apache.sis.util.Utilities;
import org.apache.sis.util.Workaround;
import org.apache.sis.util.ComparisonMode;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.resources.Vocabulary;
import org.apache.sis.util.iso.SimpleInternationalString;
import org.apache.sis.internal.referencing.WKTKeywords;
import org.apache.sis.internal.jaxb.gco.StringAdapter;
import org.apache.sis.internal.jaxb.referencing.CC_OperationMethod;
import org.apache.sis.internal.referencing.NilReferencingObject;
import org.apache.sis.internal.referencing.Resources;
import org.apache.sis.internal.metadata.Identifiers;
import org.apache.sis.internal.metadata.MetadataUtilities;
import org.apache.sis.parameter.DefaultParameterDescriptorGroup;
import org.apache.sis.parameter.Parameterized;
import org.apache.sis.referencing.NamedIdentifier;
import org.apache.sis.referencing.IdentifiedObjects;
import org.apache.sis.referencing.AbstractIdentifiedObject;
import org.apache.sis.io.wkt.Formatter;
import org.apache.sis.io.wkt.ElementKind;
import org.apache.sis.io.wkt.FormattableObject;

import static org.apache.sis.util.ArgumentChecks.*;


/**
 * Describes the algorithm and parameters used to perform a coordinate operation. An {@code OperationMethod}
 * is a kind of metadata: it does not perform any coordinate operation (e.g. map projection) by itself, but
 * tells us what is needed in order to perform such operation.
 *
 * <p>The most important parts of an {@code OperationMethod} are its {@linkplain #getName() name} and its
 * {@linkplain #getParameters() group of parameter descriptors}. The parameter descriptors do not contain
 * any value, but tell us what are the expected parameters, together with their units of measurement.</p>
 *
 * <div class="note"><b>Example:</b>
 * An operation method named “<cite>Mercator (variant A)</cite>” (EPSG:9804) expects the following parameters:
 * <ul>
 *   <li>“<cite>Latitude of natural origin</cite>” in degrees. Default value is 0°.</li>
 *   <li>“<cite>Longitude of natural origin</cite>” in degrees. Default value is 0°.</li>
 *   <li>“<cite>Scale factor at natural origin</cite>” as a dimensionless number. Default value is 1.</li>
 *   <li>“<cite>False easting</cite>” in metres. Default value is 0 m.</li>
 *   <li>“<cite>False northing</cite>” in metres. Default value is 0 m.</li>
 * </ul></div>
 *
 * In Apache SIS implementation, the {@linkplain #getName() name} is the only mandatory property. However it is
 * recommended to provide also {@linkplain #getIdentifiers() identifiers} (e.g. “EPSG:9804” in the above example)
 * since names can sometime be ambiguous or be spelled in different ways.
 *
 * <h2>Departure from the ISO 19111 standard</h2>
 * The following properties are mandatory according ISO 19111,
 * but may be missing under some conditions in Apache SIS:
 * <ul>
 *   <li>The {@linkplain #getFormula() formula} if it has not been provided to the
 *     {@linkplain #DefaultOperationMethod(Map, Integer, Integer, ParameterDescriptorGroup) constructor}, or if it
 *     can not be {@linkplain #DefaultOperationMethod(MathTransform) inferred from the given math transform}.</li>
 *   <li>The {@linkplain #getParameters() parameters} if the {@link #DefaultOperationMethod(MathTransform)}
 *     constructor can not infer them.</li>
 * </ul>
 *
 * <h2>Relationship with other classes or interfaces</h2>
 * {@code OperationMethod} describes parameters without providing any value (except sometime default values).
 * When values have been assigned to parameters, the result is a {@link SingleOperation}.
 * Note that there is different kinds of {@code SingleOperation} depending on the nature and accuracy of the
 * coordinate operation. See {@link #getOperationType()} for more information.
 *
 * <p>The interface performing the actual work of taking coordinates in the
 * {@linkplain AbstractCoordinateOperation#getSourceCRS() source CRS} and calculating the new coordinates in the
 * {@linkplain AbstractCoordinateOperation#getTargetCRS() target CRS} is {@link MathTransform}.
 * In order to allow Apache SIS to instantiate those {@code MathTransform}s from given parameter values,
 * {@code DefaultOperationMethod} subclasses should implement the
 * {@link org.apache.sis.referencing.operation.transform.MathTransformProvider} interface.</p>
 *
 * <h2>Immutability and thread safety</h2>
 * This class is immutable and thread-safe if all properties given to the constructor are also immutable and thread-safe.
 * It is strongly recommended for all subclasses to be thread-safe, especially the
 * {@link org.apache.sis.referencing.operation.transform.MathTransformProvider} implementations to be used with
 * {@link org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory}.
 *
 * @author  Martin Desruisseaux (IRD, Geomatys)
 * @version 0.7
 *
 * @see DefaultConversion
 * @see DefaultTransformation
 * @see org.apache.sis.referencing.operation.transform.MathTransformProvider
 *
 * @since 0.5
 * @module
 */
@XmlType(name = "OperationMethodType", propOrder = {
    "formulaCitation",
    "formulaDescription",
    "sourceDimensions",
    "targetDimensions",
    "descriptors"
})
@XmlRootElement(name = "OperationMethod")
public class DefaultOperationMethod extends AbstractIdentifiedObject implements OperationMethod {
    /*
     * NOTE FOR JAVADOC WRITER:
     * The "method" word is ambiguous here, because it can be "Java method" or "coordinate operation method".
     * In this class, we reserve the "method" word for "coordinate operation method" as much as possible.
     */

    /**
     * Serial number for inter-operability with different versions.
     */
    private static final long serialVersionUID = 2870579345991143357L;

    /**
     * Formula(s) or procedure used by this operation method. This may be a reference to a publication.
     * Note that the operation method may not be analytic, in which case this attribute references or
     * contains the procedure, not an analytic formula.
     *
     * <p><b>Consider this field as final!</b>
     * This field is modified only at unmarshalling time by {@link #setFormulaCitation(Citation)}
     * or {@link #setFormulaDescription(String)}.</p>
     */
    private Formula formula;

    /**
     * Number of dimensions in the source CRS of this operation method.
     * May be {@code null} if this method can work with any number of
     * source dimensions (e.g. <cite>Affine Transform</cite>).
     *
     * <p><b>Consider this field as final!</b>
     * This field is modified only at unmarshalling time by {@link #setSourceDimensions(Integer)}</p>
     *
     * @see #getSourceDimensions()
     */
    private Integer sourceDimensions;

    /**
     * Number of dimensions in the target CRS of this operation method.
     * May be {@code null} if this method can work with any number of
     * target dimensions (e.g. <cite>Affine Transform</cite>).
     *
     * <p><b>Consider this field as final!</b>
     * This field is modified only at unmarshalling time by {@link #setTargetDimensions(Integer)}</p>
     *
     * @see #getTargetDimensions()
     */
    private Integer targetDimensions;

    /**
     * The set of parameters, or {@code null} if none.
     *
     * <p><b>Consider this field as final!</b>
     * This field is modified only at unmarshalling time by {@link #setDescriptors(GeneralParameterDescriptor[])}</p>
     */
    private ParameterDescriptorGroup parameters;

    /**
     * Constructs an operation method from a set of properties and a descriptor group. The properties map is given
     * unchanged to the {@linkplain AbstractIdentifiedObject#AbstractIdentifiedObject(Map) super-class constructor}.
     * In addition to the properties documented in the parent constructor,
     * the following properties are understood by this constructor:
     *
     * <table class="sis">
     *   <caption>Recognized properties (non exhaustive list)</caption>
     *   <tr>
     *     <th>Property name</th>
     *     <th>Value type</th>
     *     <th>Returned by</th>
     *   </tr>
     *   <tr>
     *     <td>{@value org.opengis.referencing.operation.OperationMethod#FORMULA_KEY}</td>
     *     <td>{@link Formula}, {@link Citation} or {@link CharSequence}</td>
     *     <td>{@link #getFormula()}</td>
     *   </tr>
     *   <tr>
     *     <th colspan="3" class="hsep">Defined in parent classes (reminder)</th>
     *   </tr>
     *   <tr>
     *     <td>{@value org.opengis.referencing.IdentifiedObject#NAME_KEY}</td>
     *     <td>{@link org.opengis.metadata.Identifier} or {@link String}</td>
     *     <td>{@link #getName()}</td>
     *   </tr>
     *   <tr>
     *     <td>{@value org.opengis.referencing.IdentifiedObject#ALIAS_KEY}</td>
     *     <td>{@link org.opengis.util.GenericName} or {@link CharSequence} (optionally as array)</td>
     *     <td>{@link #getAlias()}</td>
     *   </tr>
     *   <tr>
     *     <td>{@value org.opengis.referencing.IdentifiedObject#IDENTIFIERS_KEY}</td>
     *     <td>{@link org.opengis.metadata.Identifier} (optionally as array)</td>
     *     <td>{@link #getIdentifiers()}</td>
     *   </tr>
     *   <tr>
     *     <td>{@value org.opengis.referencing.IdentifiedObject#REMARKS_KEY}</td>
     *     <td>{@link InternationalString} or {@link String}</td>
     *     <td>{@link #getRemarks()}</td>
     *   </tr>
     * </table>
     *
     * The source and target dimensions may be {@code null} if this method can work
     * with any number of dimensions (e.g. <cite>Affine Transform</cite>).
     *
     * @param  properties        set of properties. Shall contain at least {@code "name"}.
     * @param  sourceDimensions  number of dimensions in the source CRS of this operation method, or {@code null}.
     * @param  targetDimensions  number of dimensions in the target CRS of this operation method, or {@code null}.
     * @param  parameters        description of parameters expected by this operation.
     */
    public DefaultOperationMethod(final Map<String,?> properties,
                                  final Integer sourceDimensions,
                                  final Integer targetDimensions,
                                  final ParameterDescriptorGroup parameters)
    {
        super(properties);
        if (sourceDimensions != null) ensurePositive("sourceDimensions", sourceDimensions);
        if (targetDimensions != null) ensurePositive("targetDimensions", targetDimensions);
        ensureNonNull("parameters", parameters);

        Object value = properties.get(FORMULA_KEY);
        if (value == null || value instanceof Formula) {
            formula = (Formula) value;
        } else if (value instanceof Citation) {
            formula = new DefaultFormula((Citation) value);
        } else if (value instanceof CharSequence) {
            formula = new DefaultFormula((CharSequence) value);
        } else {
            throw new IllegalArgumentException(Errors.getResources(properties)
                    .getString(Errors.Keys.IllegalPropertyValueClass_2, FORMULA_KEY, value.getClass()));
        }
        this.parameters       = parameters;
        this.sourceDimensions = sourceDimensions;
        this.targetDimensions = targetDimensions;
    }

    /**
     * Convenience constructor that creates an operation method from a math transform.
     * The information provided in the newly created object are approximations, and
     * usually acceptable only as a fallback when no other information are available.
     *
     * @param  transform  the math transform to describe.
     */
    public DefaultOperationMethod(final MathTransform transform) {
        super(getProperties(transform));
        sourceDimensions = transform.getSourceDimensions();
        targetDimensions = transform.getTargetDimensions();
        if (transform instanceof Parameterized) {
            parameters = ((Parameterized) transform).getParameterDescriptors();
        } else {
            parameters = null;
        }
        formula = null;
    }

    /**
     * Work around for RFE #4093999 in Sun's bug database
     * ("Relax constraint on placement of this()/super() call in constructors").
     */
    @Workaround(library="JDK", version="1.7")
    private static Map<String,?> getProperties(final MathTransform transform) {
        ensureNonNull("transform", transform);
        if (transform instanceof Parameterized) {
            final ParameterDescriptorGroup parameters = ((Parameterized) transform).getParameterDescriptors();
            if (parameters != null) {
                return getProperties(parameters, null);
            }
        }
        return Collections.singletonMap(NAME_KEY, NilReferencingObject.UNNAMED);
    }

    /**
     * Returns the properties to be given to an identified object derived from the specified one.
     * This method returns the same properties than the supplied argument
     * (as of <code>{@linkplain IdentifiedObjects#getProperties getProperties}(info)</code>),
     * except for the following:
     *
     * <ul>
     *   <li>The {@linkplain IdentifiedObject#getName() name}'s authority is replaced by the specified one.</li>
     *   <li>All {@linkplain IdentifiedObject#getIdentifiers identifiers} are removed, because the new object
     *       to be created is probably not endorsed by the original authority.</li>
     * </ul>
     *
     * This method returns a mutable map. Consequently, callers can add their own identifiers
     * directly to this map if they wish.
     *
     * @param  info       the identified object to view as a properties map.
     * @param  authority  the new authority for the object to be created,
     *                    or {@code null} if it is not going to have any declared authority.
     * @return the identified object properties in a mutable map.
     */
    private static Map<String,Object> getProperties(final IdentifiedObject info, final Citation authority) {
        final Map<String,Object> properties = new HashMap<>(IdentifiedObjects.getProperties(info));
        properties.put(NAME_KEY, new NamedIdentifier(authority, info.getName().getCode()));
        properties.remove(IDENTIFIERS_KEY);
        return properties;
    }

    /**
     * Creates a new operation method with the same values than the specified one.
     * This copy constructor provides a way to convert an arbitrary implementation into a SIS one
     * or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.
     *
     * <p>This constructor performs a shallow copy, i.e. the properties are not cloned.</p>
     *
     * @param  method  the operation method to copy.
     *
     * @see #castOrCopy(OperationMethod)
     */
    protected DefaultOperationMethod(final OperationMethod method) {
        super(method);
        formula          = method.getFormula();
        parameters       = method.getParameters();
        sourceDimensions = method.getSourceDimensions();
        targetDimensions = method.getTargetDimensions();
    }

    /**
     * Returns a SIS operation method implementation with the same values than the given arbitrary implementation.
     * If the given object is {@code null}, then {@code null} is returned.
     * Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged.
     * Otherwise a new SIS implementation is created and initialized to the attribute values of the given object.
     *
     * @param  object  the object to get as a SIS implementation, or {@code null} if none.
     * @return a SIS implementation containing the values of the given object (may be the
     *         given object itself), or {@code null} if the argument was null.
     */
    public static DefaultOperationMethod castOrCopy(final OperationMethod object) {
        return (object == null) || (object instanceof DefaultOperationMethod)
               ? (DefaultOperationMethod) object : new DefaultOperationMethod(object);
    }

    /**
     * Constructs a new operation method with the same values than the specified one except the dimensions.
     * The source and target dimensions may be {@code null} if this method can work with any number of dimensions
     * (e.g. <cite>Affine Transform</cite>).
     *
     * @param  method            the operation method to copy.
     * @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.
     */
    private DefaultOperationMethod(final OperationMethod method,
                                   final Integer sourceDimensions,
                                   final Integer targetDimensions)
    {
        super(method);
        this.formula    = method.getFormula();
        this.parameters = method.getParameters();
        this.sourceDimensions = sourceDimensions;
        this.targetDimensions = targetDimensions;
    }

    /**
     * Returns an operation method with different dimensions, if we are allowed to change dimensionality.
     * This method accepts to change a dimension only if the value specified by the original method
     * is {@code null}. Otherwise an {@link IllegalArgumentException} is thrown.
     *
     * @param  method            the operation method to redimension.
     * @param  sourceDimensions  the desired new source dimensions.
     * @param  methodSource      the current number of source dimensions (may be {@code null}).
     * @param  targetDimensions  the desired new target dimensions.
     * @param  methodTarget      the current number of target dimensions (may be {@code null}).
     * @throws IllegalArgumentException if the given dimensions are illegal for this operation method.
     */
    private static OperationMethod redimension(final OperationMethod method,
            final int sourceDimensions, final Integer methodSource,
            final int targetDimensions, final Integer methodTarget)
    {
        boolean sourceValids = (methodSource != null) && (methodSource == sourceDimensions);
        boolean targetValids = (methodTarget != null) && (methodTarget == targetDimensions);
        if (sourceValids && targetValids) {
            return method;
        }
        sourceValids |= (methodSource == null);
        targetValids |= (methodTarget == null);
        ensurePositive("sourceDimensions", sourceDimensions);
        ensurePositive("targetDimensions", targetDimensions);
        if (!sourceValids || !targetValids) {
            throw new IllegalArgumentException(Resources.format(Resources.Keys.IllegalOperationDimension_3,
                    method.getName().getCode(), sourceDimensions, targetDimensions));
        }
        return new DefaultOperationMethod(method, sourceDimensions, targetDimensions);
    }

    /**
     * Returns an operation method with different dimensions, if we are allowed to change dimensionality.
     * The need to change an {@code OperationMethod} dimensionality may occur in two contexts:
     *
     * <ul class="verbose">
     *   <li>When the original method can work with any number of dimensions. Those methods do not know
     *     in advance the number of dimensions, which is fixed only after the actual {@link MathTransform}
     *     instance has been created.
     *     Example: <cite>Affine</cite> conversion.</li>
     *   <li>When a three-dimensional method can also be used in the two-dimensional case, typically by
     *     assuming that the ellipsoidal height is zero everywhere.
     *     Example: <cite>Molodensky</cite> transform.</li>
     * </ul>
     *
     * This {@code redimension(…)} implementation performs the following choice:
     *
     * <ul class="verbose">
     *   <li>If the given method is an instance of {@code DefaultOperationMethod}, then delegate to
     *     {@link #redimension(int, int)} in order to allow subclasses to defines their own policy.
     *     For example the <cite>Molodensky</cite> method needs to override.</li>
     *   <li>Otherwise for each dimension (<var>source</var> and <var>target</var>):
     *     <ul>
     *       <li>If the corresponding dimension of the given method is {@code null}, then
     *         set that dimension to the given value in a new {@code OperationMethod}.</li>
     *       <li>Otherwise if the given value is not equal to the corresponding dimension
     *         in the given method, throw an {@link IllegalArgumentException}.</li>
     *     </ul>
     *   </li>
     * </ul>
     *
     * @param  method            the operation method to redimension, or {@code null}.
     * @param  sourceDimensions  the desired number of input dimensions.
     * @param  targetDimensions  the desired number of output dimensions.
     * @return the redimensioned operation method, or {@code null} if the given method was null,
     *         or {@code method} if no change is needed.
     * @throws IllegalArgumentException if the given dimensions are illegal for the given operation method.
     */
    public static OperationMethod redimension(OperationMethod method,
            final int sourceDimensions, final int targetDimensions)
    {
        if (method != null) {
            if (method instanceof DefaultOperationMethod) {
                return ((DefaultOperationMethod) method).redimension(sourceDimensions, targetDimensions);
            } else {
                method = redimension(method, sourceDimensions, method.getSourceDimensions(),
                                             targetDimensions, method.getTargetDimensions());
            }
        }
        return method;
    }

    /**
     * Returns this operation method with different dimensions, if we are allowed to change dimensionality.
     * See {@link #redimension(OperationMethod, int, int)} for more information.
     *
     * <p>The default implementation performs the following choice:
     * for each dimension (<var>source</var> and <var>target</var>):</p>
     * <ul>
     *   <li>If the corresponding dimension of the given method is {@code null}, then
     *       set that dimension to the given value in a new {@code OperationMethod}.</li>
     *   <li>Otherwise if the given value is not equal to the corresponding dimension
     *       in the given method, throw an {@link IllegalArgumentException}.</li>
     * </ul>
     *
     * Subclasses should override this method if they can work with different number of dimensions.
     * For example a <cite>Molodensky</cite> transform usually works in a three-dimensional space,
     * but can also work in a two-dimensional space by assuming that the ellipsoidal height is zero
     * everywhere.
     *
     * @param  sourceDimensions  the desired number of input dimensions.
     * @param  targetDimensions  the desired number of output dimensions.
     * @return the redimensioned operation method, or {@code this} if no change is needed.
     * @throws IllegalArgumentException if the given dimensions are illegal for this operation method.
     *
     * @since 0.6
     */
    public OperationMethod redimension(final int sourceDimensions, final int targetDimensions) {
        return redimension(this, sourceDimensions, this.sourceDimensions,
                                 targetDimensions, this.targetDimensions);
    }

    /**
     * Returns the GeoAPI interface implemented by this class.
     * The SIS implementation returns {@code OperationMethod.class}.
     *
     * <div class="note"><b>Note for implementers:</b>
     * Subclasses usually do not need to override this information since GeoAPI does not define {@code OperationMethod}
     * sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their
     * own set of interfaces.</div>
     *
     * @return {@code OperationMethod.class} or a user-defined sub-interface.
     */
    @Override
    public Class<? extends OperationMethod> getInterface() {
        return OperationMethod.class;
    }

    /**
     * Returns the base interface of the {@code CoordinateOperation} instances that use this method.
     * The base {@code CoordinateOperation} interface is usually one of the following subtypes:
     *
     * <ul class="verbose">
     *   <li>{@link org.opengis.referencing.operation.Transformation}
     *     if the coordinate operation has some errors (typically of a few metres) because of the empirical process by
     *     which the operation parameters were determined. Those errors do not depend on the floating point precision
     *     or the accuracy of the implementation algorithm.</li>
     *   <li class="verbose">{@link org.opengis.referencing.operation.Conversion}
     *     if the coordinate operation is theoretically of infinite precision, ignoring the limitations of floating
     *     point arithmetic (including rounding errors) and the approximations implied by finite series expansions.</li>
     *   <li>{@link org.opengis.referencing.operation.Projection}
     *     if the coordinate operation is a conversion (as defined above) converting geodetic latitudes and longitudes
     *     to plane (map) coordinates. This type can optionally be refined with one of the
     *     {@link org.opengis.referencing.operation.CylindricalProjection},
     *     {@link org.opengis.referencing.operation.ConicProjection} or
     *     {@link org.opengis.referencing.operation.PlanarProjection} subtypes.</li>
     * </ul>
     *
     * In case of doubt, {@code getOperationType()} can conservatively return the base type.
     * The default implementation returns {@code SingleOperation.class},
     * which is the most conservative return value.
     *
     * @return interface implemented by all coordinate operations that use this method.
     *
     * @see org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory#getAvailableMethods(Class)
     */
    public Class<? extends SingleOperation> getOperationType() {
        return SingleOperation.class;
    }

    /**
     * Formula(s) or procedure used by this operation method. This may be a reference to a
     * publication. Note that the operation method may not be analytic, in which case this
     * attribute references or contains the procedure, not an analytic formula.
     *
     * <div class="note"><b>Departure from the ISO 19111 standard:</b>
     * this property is mandatory according ISO 19111, but optional in Apache SIS.</div>
     *
     * @return the formula used by this method, or {@code null} if unknown.
     *
     * @see DefaultFormula
     * @see org.apache.sis.referencing.operation.transform.MathTransformProvider
     */
    @Override
    public Formula getFormula() {
        return formula;
    }

    /**
     * Number of dimensions in the source CRS of this operation method.
     * May be null if unknown, as in an <cite>Affine Transform</cite>.
     *
     * @return the dimension of source CRS, or {@code null} if unknown.
     *
     * @see org.apache.sis.referencing.operation.transform.AbstractMathTransform#getSourceDimensions()
     */
    @Override
    @XmlElement(name = "sourceDimensions")
    @XmlSchemaType(name = "positiveInteger")
    public Integer getSourceDimensions() {
        return sourceDimensions;
    }

    /**
     * Number of dimensions in the target CRS of this operation method.
     * May be null if unknown, as in an <cite>Affine Transform</cite>.
     *
     * @return the dimension of target CRS, or {@code null} if unknown.
     *
     * @see org.apache.sis.referencing.operation.transform.AbstractMathTransform#getTargetDimensions()
     */
    @Override
    @XmlElement(name = "targetDimensions")
    @XmlSchemaType(name = "positiveInteger")
    public Integer getTargetDimensions() {
        return targetDimensions;
    }

    /**
     * Returns the set of parameters.
     *
     * <div class="note"><b>Departure from the ISO 19111 standard:</b>
     * this property is mandatory according ISO 19111, but may be null in Apache SIS if the
     * {@link #DefaultOperationMethod(MathTransform)} constructor has been unable to infer it
     * or if this {@code OperationMethod} has been read from an incomplete GML document.</div>
     *
     * @return the parameters, or {@code null} if unknown.
     *
     * @see DefaultConversion#getParameterDescriptors()
     * @see DefaultConversion#getParameterValues()
     */
    @Override
    public ParameterDescriptorGroup getParameters() {
        return parameters;
    }

    /**
     * Compares this operation method with the specified object for equality.
     * If the {@code mode} argument value is {@link ComparisonMode#STRICT STRICT} or
     * {@link ComparisonMode#BY_CONTRACT BY_CONTRACT}, then all available properties
     * are compared including the {@linkplain #getFormula() formula}.
     *
     * @param  object  the object to compare to {@code this}.
     * @param  mode    {@link ComparisonMode#STRICT STRICT} for performing a strict comparison, or
     *                 {@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA} for comparing only
     *                 properties relevant to transformations.
     * @return {@code true} if both objects are equal.
     */
    @Override
    public boolean equals(final Object object, final ComparisonMode mode) {
        if (object == this) {
            return true;                                                // Slight optimization.
        }
        if (super.equals(object, mode)) {
            switch (mode) {
                case STRICT: {
                    // Name and identifiers have been compared by super.equals(object, mode).
                    final DefaultOperationMethod that = (DefaultOperationMethod) object;
                    return Objects.equals(this.formula,          that.formula) &&
                           Objects.equals(this.sourceDimensions, that.sourceDimensions) &&
                           Objects.equals(this.targetDimensions, that.targetDimensions) &&
                           Objects.equals(this.parameters,       that.parameters);
                }
                case BY_CONTRACT: {
                    // Name and identifiers have been compared by super.equals(object, mode).
                    if (!Objects.equals(getFormula(), ((OperationMethod) object).getFormula())) {
                        return false;
                    }
                    break;
                }
                default: {
                    /*
                     * Name and identifiers have been ignored by super.equals(object, mode).
                     * Since they are significant for OperationMethod, we compare them here.
                     *
                     * According ISO 19162 (Well Known Text representation of Coordinate Reference Systems),
                     * identifiers shall have precedence over name at least in the case of operation methods
                     * and parameters.
                     */
                    final OperationMethod that = (OperationMethod) object;
                    final Boolean match = Identifiers.hasCommonIdentifier(getIdentifiers(), that.getIdentifiers());
                    if (match != null) {
                        if (!match) {
                            return false;
                        }
                    } else if (!isHeuristicMatchForName(that.getName().getCode())
                            && !IdentifiedObjects.isHeuristicMatchForName(that, getName().getCode()))
                    {
                        return false;
                    }
                    break;
                }
            }
            final OperationMethod that = (OperationMethod) object;
            return Objects.equals(getSourceDimensions(), that.getSourceDimensions()) &&
                   Objects.equals(getTargetDimensions(), that.getTargetDimensions()) &&
                   Utilities.deepEquals(getParameters(), that.getParameters(), mode);
        }
        return false;
    }

    /**
     * Invoked by {@code hashCode()} for computing the hash code when first needed.
     * See {@link org.apache.sis.referencing.AbstractIdentifiedObject#computeHashCode()}
     * for more information.
     *
     * @return the hash code value. This value may change in any future Apache SIS version.
     */
    @Override
    protected long computeHashCode() {
        return super.computeHashCode() + Objects.hash(sourceDimensions, targetDimensions, parameters);
    }

    /**
     * Formats this operation as a <cite>Well Known Text</cite> {@code Method[…]} element.
     *
     * @return {@code "Method"} (WKT 2) or {@code "Projection"} (WKT 1).
     *
     * @see <a href="http://docs.opengeospatial.org/is/12-063r5/12-063r5.html#118">WKT 2 specification §17.2.3</a>
     */
    @Override
    protected String formatTo(final Formatter formatter) {
        final boolean isWKT1 = formatter.getConvention().majorVersion() == 1;
        /*
         * The next few lines below are basically a copy of the work done by super.formatTo(formatter),
         * which search for the name to write inside METHOD["name"]. The difference is in the fallback
         * executed if we do not find a name for the given authority.
         */
        final Citation authority = formatter.getNameAuthority();
        String name = IdentifiedObjects.getName(this, authority);
        ElementKind kind = ElementKind.METHOD;
        if (name == null) {
            /*
             * No name found for the given authority. We may use the primary name as a fallback.
             * But before doing that, maybe we can find the name that we are looking for in the
             * hard-coded values in the 'org.apache.sis.internal.referencing.provider' package.
             * The typical use case is when this DefaultOperationMethod has been instantiated
             * by the EPSG factory using only the information found in the EPSG database.
             *
             * We can find the hard-coded names by looking at the ParameterDescriptorGroup of the
             * enclosing ProjectedCRS or DerivedCRS. This is because that parameter descriptor was
             * typically provided by the 'org.apache.sis.internal.referencing.provider' package in
             * order to create the MathTransform associated with the enclosing CRS.  The enclosing
             * CRS is either the immediate parent in WKT 1, or the parent of the parent in WKT 2.
             */
            final FormattableObject parent = formatter.getEnclosingElement(isWKT1 ? 1 : 2);
            if (parent instanceof GeneralDerivedCRS) {
                final Conversion conversion = ((GeneralDerivedCRS) parent).getConversionFromBase();
                if (conversion != null) {   // Should never be null, but let be safe.
                    final ParameterDescriptorGroup descriptor;
                    if (conversion instanceof Parameterized) {  // Usual case in SIS implementation.
                        descriptor = ((Parameterized) conversion).getParameterDescriptors();
                    } else {
                        descriptor = conversion.getParameterValues().getDescriptor();
                    }
                    name = IdentifiedObjects.getName(descriptor, authority);
                }
            }
            if (name == null) {
                name = IdentifiedObjects.getName(this, null);
                if (name == null) {
                    name = Vocabulary.getResources(formatter.getLocale()).getString(Vocabulary.Keys.Unnamed);
                    kind = ElementKind.NAME;  // Because the "Unnamed" string is not a real OperationMethod name.
                }
            }
        }
        formatter.append(name, kind);
        if (isWKT1) {
            /*
             * The WKT 1 keyword is "PROJECTION", which imply that the operation method should be of type
             * org.opengis.referencing.operation.Projection. So strictly speaking only the first check in
             * the following 'if' statement is relevant.
             *
             * Unfortunately in many cases we do not know the operation type, because the method that we
             * invoked - getOperationType() - is not a standard OGC/ISO property, so this information is
             * usually not provided in XML documents for example.  The user could also have instantiated
             * DirectOperationMethod directly without creating a subclass. Consequently we also accept to
             * format the keyword as "PROJECTION" if the operation type *could* be a projection. This is
             * the second check in the following 'if' statement.
             *
             * In other words, the combination of those two checks exclude the following operation types:
             * Transformation, ConcatenatedOperation, PassThroughOperation, or any user-defined type that
             * do not extend Projection. All other operation types are accepted.
             */
            final Class<? extends SingleOperation> type = getOperationType();
            if (Projection.class.isAssignableFrom(type) || type.isAssignableFrom(Projection.class)) {
                return WKTKeywords.Projection;
            }
            formatter.setInvalidWKT(this, null);
        }
        return WKTKeywords.Method;
    }


    //////////////////////////////////////////////////////////////////////////////////////////////////
    ////////                                                                                  ////////
    ////////                               XML support with JAXB                              ////////
    ////////                                                                                  ////////
    ////////        The following methods are invoked by JAXB using reflection (even if       ////////
    ////////        they are private) or are helpers for other methods invoked by JAXB.       ////////
    ////////        Those methods can be safely removed if Geographic Markup Language         ////////
    ////////        (GML) support is not needed.                                              ////////
    ////////                                                                                  ////////
    //////////////////////////////////////////////////////////////////////////////////////////////////

    /**
     * Creates a new object in which every attributes are set to a null value.
     * <strong>This is not a valid object.</strong> This constructor is strictly
     * reserved to JAXB, which will assign values to the fields using reflexion.
     */
    private DefaultOperationMethod() {
        super(org.apache.sis.internal.referencing.NilReferencingObject.INSTANCE);
    }

    /**
     * Invoked by JAXB at unmarshalling time.
     *
     * @see #getSourceDimensions()
     */
    private void setSourceDimensions(final Integer value) {
        if (sourceDimensions == null) {
            sourceDimensions = value;
        } else {
            MetadataUtilities.propertyAlreadySet(DefaultOperationMethod.class, "setSourceDimensions", "sourceDimensions");
        }
    }

    /**
     * Invoked by JAXB at unmarshalling time.
     *
     * @see #getTargetDimensions()
     */
    private void setTargetDimensions(final Integer value) {
        if (targetDimensions == null) {
            targetDimensions = value;
        } else {
            MetadataUtilities.propertyAlreadySet(DefaultOperationMethod.class, "setTargetDimensions", "targetDimensions");
        }
    }

    /**
     * Invoked by JAXB for marshalling a citation to the formula. In principle at most one of
     * {@code getFormulaCitation()} and {@link #getFormulaDescription()} methods can return a
     * non-null value. However SIS accepts both coexist (but this is invalid GML).
     */
    @XmlElement(name = "formulaCitation")
    private Citation getFormulaCitation() {
        final Formula formula = getFormula();   // Give to users a chance to override.
        return (formula != null) ? formula.getCitation() : null;
    }

    /**
     * Invoked by JAXB for marshalling the formula literally. In principle at most one of
     * {@code getFormulaDescription()} and {@link #getFormulaCitation()} methods can return
     * a non-null value. However SIS accepts both to coexist (but this is invalid GML).
     */
    @XmlElement(name = "formula")
    private String getFormulaDescription() {
        final Formula formula = getFormula();   // Give to users a chance to override.
        return (formula != null) ? StringAdapter.toString(formula.getFormula()) : null;
    }

    /**
     * Invoked by JAXB for setting the citation to the formula.
     */
    private void setFormulaCitation(final Citation citation) {
        if (formula == null || formula.getCitation() == null) {
            formula = (formula == null) ? new DefaultFormula(citation)
                      : new DefaultFormula(formula.getFormula(), citation);
        } else {
            MetadataUtilities.propertyAlreadySet(DefaultOperationMethod.class, "setFormulaCitation", "formulaCitation");
        }
    }

    /**
     * Invoked by JAXB for setting the formula description.
     */
    private void setFormulaDescription(final String description) {
        if (formula == null || formula.getFormula() == null) {
            formula = (formula == null) ? new DefaultFormula(description)
                      : new DefaultFormula(new SimpleInternationalString(description), formula.getCitation());
        } else {
            MetadataUtilities.propertyAlreadySet(DefaultOperationMethod.class, "setFormulaDescription", "formula");
        }
    }

    /**
     * Invoked by JAXB for getting the parameters to marshal. This method usually marshals the sequence of
     * descriptors without their {@link ParameterDescriptorGroup} wrapper, because GML is defined that way.
     * The {@code ParameterDescriptorGroup} wrapper is a GeoAPI addition done for allowing usage of its
     * methods as a convenience (e.g. {@link ParameterDescriptorGroup#descriptor(String)}).
     *
     * <p>However it could happen that the user really wanted to specify a {@code ParameterDescriptorGroup} as
     * the sole {@code <gml:parameter>} element. We currently have no easy way to distinguish those cases.</p>
     *
     * <div class="note"><b>Tip:</b>
     * One possible way to distinguish the two cases would be to check that the parameter group does not contain
     * any property that this method does not have:
     *
     * {@preformat java
     *   if (IdentifiedObjects.getProperties(this).entrySet().containsAll(
     *       IdentifiedObjects.getProperties(parameters).entrySet())) ...
     * }
     *
     * But we would need to make sure that {@link AbstractSingleOperation#getParameters()} is consistent
     * with the decision taken by this method.</div>
     *
     * <p><b>Historical note:</b> older, deprecated, names for the parameters were:
     * <ul>
     *   <li>{@code includesParameter}</li>
     *   <li>{@code generalOperationParameter} - note that this name was used by the EPSG registry</li>
     *   <li>{@code usesParameter}</li>
     * </ul>
     *
     * @see #getParameters()
     * @see AbstractSingleOperation#getParameters()
     */
    @XmlElement(name = "parameter")
    private GeneralParameterDescriptor[] getDescriptors() {
        if (parameters != null) {
            final List<GeneralParameterDescriptor> descriptors = parameters.descriptors();
            if (descriptors != null) {      // Paranoiac check (should not be allowed).
                return CC_OperationMethod.filterImplicit(descriptors.toArray(
                        new GeneralParameterDescriptor[descriptors.size()]));
            }
        }
        return null;
    }

    /**
     * Invoked by JAXB for setting the unmarshalled parameters.
     * This method wraps the given descriptors in a {@link DefaultParameterDescriptorGroup}.
     *
     * <p>The parameter descriptors created by this method are incomplete since we can not
     * provide a non-null value for {@link ParameterDescriptor#getValueClass()}. The value
     * class will be provided either by replacing this {@code OperationMethod} by one of the
     * pre-defined methods, or by unmarshalling the enclosing {@link AbstractSingleOperation}.</p>
     *
     * <p><b>Maintenance note:</b> the {@code "setDescriptors"} method name is also hard-coded in
     * {@link org.apache.sis.internal.jaxb.referencing.CC_GeneralOperationParameter} for logging purpose.</p>
     *
     * @see AbstractSingleOperation#setParameters
     */
    private void setDescriptors(final GeneralParameterDescriptor[] descriptors) {
        if (parameters == null) {
            parameters = CC_OperationMethod.group(super.getName(), descriptors);
        } else {
            MetadataUtilities.propertyAlreadySet(DefaultOperationMethod.class, "setDescriptors", "parameter");
        }
    }

    /**
     * Invoked by {@link AbstractSingleOperation} for completing the parameter descriptor.
     */
    final void updateDescriptors(final GeneralParameterDescriptor[] descriptors) {
        final ParameterDescriptorGroup previous = parameters;
        parameters = new DefaultParameterDescriptorGroup(IdentifiedObjects.getProperties(previous),
                previous.getMinimumOccurs(), previous.getMaximumOccurs(), descriptors);
    }
}