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.Collection;
021import java.util.Collections;
022import org.opengis.annotation.UML;
023import org.opengis.util.ScopedName;
024import org.opengis.metadata.citation.Citation;
025
026import static org.opengis.annotation.Obligation.*;
027import static org.opengis.annotation.Specification.ISO_19115;
028
029
030/**
031 * Links a given operation name (mandatory attribute of {@link OperationMetadata})
032 * with a resource identified by an "identifier".
033 *
034 * <p><b>Constraint:</b></p>
035 * <ul>
036 *   <li>For one {@code CoupledResource} either {@linkplain #getResources() resources} or
037 *       {@linkplain #getResourceReferences() resource references} should be used
038 *       (not both for the same {@code CoupledResource}).</li>
039 * </ul>
040 *
041 * @author  Rémi Maréchal (Geomatys)
042 * @author  Martin Desruisseaux (Geomatys)
043 * @version 3.1
044 * @since   3.1
045 */
046@UML(identifier="SV_CoupledResource", specification=ISO_19115)
047public interface CoupledResource {
048    /**
049     * Scoped identifier of the resource in the context of the given service instance.
050     * This is the name of the resources (for example dataset) as it is used by a service instance
051     *
052     * <div class="note"><b>Examples:</b> layer name or feature type name.</div>
053     *
054     * @return scoped identifier of the resource in the context of the given service instance, or {@code null} if none.
055     */
056    @UML(identifier="scopedName", obligation=OPTIONAL, specification=ISO_19115)
057    default ScopedName getScopedName() {
058        return null;
059    }
060
061    /**
062     * References to the resource on which the services operates.
063     * Returns an empty collection if none.
064     *
065     * @return references to the resource on which the services operates.
066     *
067     * @condition Only one of {@linkplain #getResources() resources} and resource references should be non-empty.
068     *
069     * @see DataIdentification#getCitation()
070     */
071    @UML(identifier="resourceReference", obligation=OPTIONAL, specification=ISO_19115)
072    default Collection<? extends Citation> getResourceReferences() {
073        return Collections.emptyList();
074    }
075
076    /**
077     * The tightly coupled resources.
078     * Returns an empty collection if none.
079     *
080     * @return tightly coupled resources.
081     *
082     * @condition Only one of resources and {@linkplain #getResourceReferences() resource references} should be non-empty.
083     */
084    @UML(identifier="resource", obligation=OPTIONAL, specification=ISO_19115)
085    default Collection<? extends DataIdentification> getResources() {
086        return Collections.emptyList();
087    }
088
089    /**
090     * The service operation.
091     *
092     * @return the service operation, or {@code null} if none.
093     */
094    @UML(identifier="operation", obligation=OPTIONAL, specification=ISO_19115)
095    default OperationMetadata getOperation() {
096        return null;
097    }
098}