001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2014-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.metadata.identification;
019
020import java.util.List;
021import java.util.Collection;
022import java.util.Collections;
023import org.opengis.annotation.UML;
024import org.opengis.util.InternationalString;
025import org.opengis.parameter.ParameterDescriptor;
026import org.opengis.metadata.citation.OnlineResource;
027
028import static org.opengis.annotation.Obligation.*;
029import static org.opengis.annotation.Specification.ISO_19115;
030
031
032/**
033 * Describes the signature of one and only one method provided by the service.
034 *
035 * @author  Rémi Maréchal (Geomatys)
036 * @version 3.1
037 * @since   3.1
038 */
039@UML(identifier="SV_OperationMetadata", specification=ISO_19115)
040public interface OperationMetadata {
041    /**
042     * An unique identifier for this interface.
043     *
044     * @return an unique identifier for this interface.
045     */
046    @UML(identifier="operationName", obligation=MANDATORY, specification=ISO_19115)
047    String getOperationName();
048
049    /**
050     * Distributed computing platforms (DCPs) on which the operation has been implemented.
051     *
052     * @return distributed computing platforms on which the operation has been implemented.
053     */
054    @UML(identifier="distributedComputingPlatform", obligation=MANDATORY, specification=ISO_19115)
055    Collection<DistributedComputingPlatform> getDistributedComputingPlatforms();
056
057    /**
058     * Free text description of the intent of the operation and the results of the operation.
059     *
060     * @return free text description of the intent of the operation and the results of the operation,
061     *         or {@code null} if none.
062     */
063    @UML(identifier="operationDescription", obligation=OPTIONAL, specification=ISO_19115)
064    default InternationalString getOperationDescription() {
065        return null;
066    }
067
068    /**
069     * The name used to invoke this interface within the context of the DCP.
070     * The name is identical for all Distributed computing platforms (DCPs).
071     *
072     * @return the name used to invoke this interface within the context of the DCP, or {@code null} if none.
073     */
074    @UML(identifier="invocationName", obligation=OPTIONAL, specification=ISO_19115)
075    default InternationalString getInvocationName() {
076        return null;
077    }
078
079    /**
080     * Handle for accessing the service interface.
081     *
082     * @return handle for accessing the service interface.
083     */
084    @UML(identifier="connectPoint", obligation=MANDATORY, specification=ISO_19115)
085    Collection<? extends OnlineResource> getConnectPoints();
086
087    /**
088     * The parameters that are required for this interface.
089     * Returns an empty collection if none.
090     *
091     * <h4>Unified parameter API</h4>
092     * In GeoAPI, the {@code SV_Parameter} type defined by ISO 19115 is replaced by {@link ParameterDescriptor}
093     * in order to provide a single parameter API (see {@link org.opengis.parameter} for more information).
094     * The mapping from ISO 19115 to GeoAPI is defined in the following table.
095     * The equivalences are straightforward except for the {@code name} property, which is mapped to
096     * an {@link org.opengis.metadata.Identifier} instead of {@link org.opengis.util.MemberName}
097     * ({@linkplain ParameterDescriptor#getName() more information on the mapping of names}).
098     *
099     * <table class="ogc">
100     *   <caption>Service metadata properties mapped to GeoAPI</caption>
101     *   <tr><th>{@code SV_Parameter} property</th> <th>{@code ParameterDescriptor} property</th></tr>
102     *   <tr><td>{@code name}</td>                  <td>{@link ParameterDescriptor#getName()          name}</td></tr>
103     *   <tr><td>{@code name.attributeType}</td>    <td>{@link ParameterDescriptor#getValueClass()    valueClass}</td></tr>
104     *   <tr><td>{@code direction}</td>             <td>{@link ParameterDescriptor#getDirection()     direction}</td></tr>
105     *   <tr><td>{@code description}</td>           <td>{@link ParameterDescriptor#getDescription()   description}</td></tr>
106     *   <tr><td>{@code optionality}</td>           <td>{@link ParameterDescriptor#getMinimumOccurs() minimumOccurs} &gt; 0</td></tr>
107     *   <tr><td>{@code repeatability}</td>         <td>{@link ParameterDescriptor#getMaximumOccurs() maximumOccurs} &gt; 1</td></tr>
108     * </table>
109     *
110     * @departure harmonization
111     *   Usage of the ISO 19115 {@code SV_Parameter} type has been replaced by usage of the ISO 19111
112     *   {@code OperationParameter} type, completed with new {@code SV_Parameter} properties,
113     *   in order to provide a unified parameter API. Note that {@code OperationParameter} is named
114     *   {@link org.opengis.parameter.ParameterDescriptor} in GeoAPI to reflect its extended scope.
115     *
116     * @return the parameters that are required for this interface, or an empty collection if none.
117     *
118     * @see org.opengis.parameter.GeneralParameterDescriptor
119     */
120    @UML(identifier="parameter", obligation=OPTIONAL, specification=ISO_19115)     // Was "parameters" in ISO 19115:2003
121    default Collection<? extends ParameterDescriptor<?>> getParameters() {
122        return Collections.emptyList();
123    }
124
125    /**
126     * List of operation that must be completed immediately before current operation is invoked.
127     * The return value is structured as a list for capturing alternate predecessor paths
128     * and sets for capturing parallel predecessor paths.
129     *
130     * @return list of operation that must be completed immediately, or an empty list if none.
131     */
132    @UML(identifier="dependsOn", obligation=OPTIONAL, specification=ISO_19115)
133    default List<? extends OperationMetadata> getDependsOn() {
134        return Collections.emptyList();
135    }
136}