001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2024 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.distribution;
019
020import java.util.Collection;
021import java.util.Collections;
022import java.util.Iterator;
023import org.opengis.util.InternationalString;
024import org.opengis.metadata.citation.Citation;
025import org.opengis.annotation.UML;
026import org.opengis.annotation.Profile;
027
028import static org.opengis.annotation.Obligation.*;
029import static org.opengis.annotation.Specification.*;
030import static org.opengis.annotation.ComplianceLevel.*;
031
032
033/**
034 * Description of the computer language construct that specifies the representation
035 * of data objects in a record, file, message, storage device or transmission channel.
036 *
037 * @author  Martin Desruisseaux (IRD, Geomatys)
038 * @version 3.1
039 * @since   2.0
040 */
041@UML(identifier="MD_Format", specification=ISO_19115)
042public interface Format {
043    /**
044     * Citation / URL of the specification format.
045     *
046     * @return citation / URL of the specification format.
047     *
048     * @since 3.1
049     */
050    @Profile(level=CORE)
051    @UML(identifier="formatSpecificationCitation", obligation=MANDATORY, specification=ISO_19115)
052    Citation getFormatSpecificationCitation();
053
054    /**
055     * Name of a subset, profile, or product specification of the format.
056     *
057     * @return name of a subset, profile, or product specification of the format, or {@code null}.
058     *
059     * @deprecated As of ISO 19115:2014, replaced by
060     * <code>{@linkplain #getFormatSpecificationCitation()}.{@linkplain Citation#getTitle() getTitle()}</code>.
061     */
062    @Deprecated(since="3.1")
063    @UML(identifier="specification", obligation=OPTIONAL, specification=ISO_19115, version=2003)
064    default InternationalString getSpecification() {
065        Citation spec = getFormatSpecificationCitation();
066        return (spec != null) ? spec.getTitle() : null;
067    }
068
069    /**
070     * Name of the data transfer format(s).
071     *
072     * @return name of the data transfer format(s).
073     *
074     * @deprecated As of ISO 19115:2014, replaced by
075     * <code>{@linkplain #getFormatSpecificationCitation()}.{@linkplain Citation#getAlternateTitles() getAlternateTitles()}</code>.
076     * Note that citation alternate titles are often used for abbreviations.
077     */
078    @Profile(level=CORE)
079    @Deprecated(since="3.1")
080    @UML(identifier="name", obligation=MANDATORY, specification=ISO_19115, version=2003)
081    default InternationalString getName() {
082        Citation spec = getFormatSpecificationCitation();
083        if (spec != null) {
084            Iterator<? extends InternationalString> it = spec.getAlternateTitles().iterator();
085            if (it.hasNext()) it.next();
086        }
087        return null;
088    }
089
090    /**
091     * Version of the format (date, number, <i>etc</i>).
092     *
093     * @return version of the format.
094     *
095     * @deprecated As of ISO 19115:2014, replaced by
096     * <code>{@linkplain #getFormatSpecificationCitation()}.{@linkplain Citation#getEdition() getEdition()}</code>.
097     */
098    @Profile(level=CORE)
099    @Deprecated(since="3.1")
100    @UML(identifier="version", obligation=MANDATORY, specification=ISO_19115, version=2003)
101    default InternationalString getVersion() {
102        Citation spec = getFormatSpecificationCitation();
103        return (spec != null) ? spec.getEdition() : null;
104    }
105
106    /**
107     * Amendment number of the format version.
108     *
109     * @return amendment number of the format version, or {@code null}.
110     */
111    @UML(identifier="amendmentNumber", obligation=OPTIONAL, specification=ISO_19115)
112    default InternationalString getAmendmentNumber() {
113        return null;
114    }
115
116    /**
117     * Recommendations of algorithms or processes that can be applied to read or
118     * expand resources to which compression techniques have been applied.
119     *
120     * @return processes that can be applied to read resources to which compression techniques have been applied,
121     *         or {@code null}.
122     */
123    @UML(identifier="fileDecompressionTechnique", obligation=OPTIONAL, specification=ISO_19115)
124    default InternationalString getFileDecompressionTechnique() {
125        return null;
126    }
127
128    /**
129     * Media used by the format.
130     *
131     * @return media used by the format.
132     *
133     * @since 3.1
134     */
135    @UML(identifier="medium", obligation=OPTIONAL, specification=ISO_19115)
136    default Collection<? extends Medium> getMedia() {
137        return Collections.emptyList();
138    }
139
140    /**
141     * Provides information about the distributor's format.
142     *
143     * @return information about the distributor's format.
144     */
145    @UML(identifier="formatDistributor", obligation=OPTIONAL, specification=ISO_19115)
146    default Collection<? extends Distributor> getFormatDistributors() {
147        return Collections.emptyList();
148    }
149}