001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2022-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.quality;
019
020import java.util.Collection;
021import java.util.Collections;
022import org.opengis.util.InternationalString;
023import org.opengis.annotation.UML;
024import org.opengis.metadata.Identifier;
025
026import static org.opengis.annotation.Obligation.*;
027import static org.opengis.annotation.Specification.*;
028
029
030/**
031 * Identifier of a measure fully described elsewhere.
032 * At least one of {@linkplain #getMeasureIdentification() measure identification}
033 * and {@linkplain #getNamesOfMeasure() measure names} shall be provided.
034 * The whole description can be found within a measure register or catalogue.
035 *
036 * <h2>Catalogue of data quality measures</h2>
037 * Catalogues of data quality measures may be available online to fully describe
038 * the measures referenced in the data quality report of the data evaluated.
039 * The catalogue may contain the set of measures used in one or several data quality reports.
040 * The catalogue (as a register) enables the user to describe the measure,
041 * and store the information in order to be able to refer to it each time needed,
042 * instead of re-describing the measure within a data quality report.
043 * This {@code MeasureReference} represents a reference to a measure in a catalogue.
044 * The full measure description is given by {@link Measure}.
045 *
046 * @author  Alexis Gaillard (Geomatys)
047 * @author  Martin Desruisseaux (Geomatys)
048 * @version 3.1
049 *
050 * @see Element#getMeasureReference()
051 * @see Measure
052 *
053 * @since 3.1
054 */
055@UML(identifier="DQ_MeasureReference", specification=ISO_19157)
056public interface MeasureReference {
057    /**
058     * Identifier of the measure, value uniquely identifying the measure within a namespace.
059     *
060     * @return code identifying a registered measure, or {@code null} if none.
061     *
062     * @see Measure#getMeasureIdentifier()
063     */
064    @UML(identifier="measureIdentification", obligation=OPTIONAL, specification=ISO_19157)
065    default Identifier getMeasureIdentification() {
066        return null;
067    }
068
069    /**
070     * Name(s) of the test applied to the data.
071     * Mandatory if {@linkplain #getMeasureIdentification() measure identification} is not provided.
072     *
073     * @return name of the test applied to the data.
074     *
075     * @see Measure#getName()
076     */
077    @UML(identifier="nameOfMeasure", obligation=CONDITIONAL, specification=ISO_19157)
078    default Collection<? extends InternationalString> getNamesOfMeasure() {
079        return Collections.emptyList();
080    }
081
082    /**
083     * Description of the measure.
084     *
085     * @return description of the measure being determined, or {@code null} if none.
086     *
087     * @see Measure#getDefinition()
088     */
089    @UML(identifier="measureDescription", obligation=OPTIONAL, specification=ISO_19157)
090    default InternationalString getMeasureDescription() {
091        return null;
092    }
093}