001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing.operation;
019
020import java.util.Set;
021import org.opengis.metadata.Identifier;
022import org.opengis.referencing.AuthorityFactory;
023import org.opengis.referencing.NoSuchAuthorityCodeException;
024import org.opengis.referencing.crs.CoordinateReferenceSystem;
025import org.opengis.util.FactoryException;
026import org.opengis.annotation.UML;
027
028import static org.opengis.annotation.Specification.*;
029
030
031/**
032 * Creates coordinate transformation objects from codes. The codes are maintained by an external authority.
033 * A commonly used authority is the <a href="https://epsg.org">EPSG geodetic registry</a>.
034 *
035 * @author  Martin Desruisseaux (IRD)
036 * @version 3.0
037 * @since   1.0
038 */
039@UML(identifier="CT_CoordinateTransformationAuthorityFactory", specification=OGC_01009)
040public interface CoordinateOperationAuthorityFactory extends AuthorityFactory {
041    /**
042     * Creates an operation method from a single code. The "{@linkplain Identifier#getAuthority
043     * authority}" and "{@linkplain Identifier#getCode code}" values of the created object will be
044     * set to the authority of this object, and the code specified by the client, respectively. The
045     * other metadata values may or may not be set.
046     *
047     * @param  code  coded value for operation method.
048     * @return the operation method for the given code.
049     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
050     * @throws FactoryException if the object creation failed for some other reason.
051     *
052     * @see CoordinateOperationFactory#getOperationMethod(String)
053     *
054     * @departure extension
055     *   This method has been added because OGC 01-009 does not define a factory
056     *   method for creating such object.
057     */
058    OperationMethod createOperationMethod(String code) throws FactoryException;
059
060    /**
061     * Creates an operation from a single operation code. The "{@linkplain Identifier#getAuthority
062     * authority}" and "{@linkplain Identifier#getCode code}" values of the created object will be
063     * set to the authority of this object, and the code specified by the client, respectively. The
064     * other metadata values may or may not be set.
065     *
066     * @param  code  coded value for coordinate operation.
067     * @return the operation for the given code.
068     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
069     * @throws FactoryException if the object creation failed for some other reason.
070     */
071    @UML(identifier="createFromTransformationCode", specification=OGC_01009)
072    CoordinateOperation createCoordinateOperation(String code) throws FactoryException;
073
074    /**
075     * Creates operations from Coordinate Reference System codes.
076     * This method returns only the operations declared by the authority, with preferred
077     * operations first. This method doesn't need to compute operations from {@code source} to
078     * {@code target} CRS if no such operations were explicitly defined in the authority database.
079     * Computation of arbitrary operations can be performed by
080     * <code>{@linkplain CoordinateOperationFactory#createOperation(CoordinateReferenceSystem,
081     * CoordinateReferenceSystem) CoordinateOperationFactory.createOperation}(sourceCRS, targetCRS)</code>
082     * instead.
083     *
084     * @param  sourceCRS  coded value of source coordinate reference system.
085     * @param  targetCRS  coded value of target coordinate reference system.
086     * @return the operations from {@code sourceCRS} to {@code targetCRS}.
087     * @throws NoSuchAuthorityCodeException if a specified code was not found.
088     * @throws FactoryException if the object creation failed for some other reason.
089     */
090    @UML(identifier="createFromCoordinateSystemCodes", specification=OGC_01009)
091    Set<CoordinateOperation> createFromCoordinateReferenceSystemCodes(String sourceCRS, String targetCRS)
092            throws FactoryException;
093}