001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2009-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.net.URI;
021import java.util.Collection;
022import java.util.Collections;
023
024import org.opengis.annotation.UML;
025import org.opengis.util.LocalName;
026import org.opengis.util.InternationalString;
027import org.opengis.metadata.identification.BrowseGraphic;
028
029import static org.opengis.annotation.Obligation.*;
030import static org.opengis.annotation.Specification.*;
031
032
033/**
034 * Description of a transfer data file.
035 *
036 * @author  Cédric Briançon (Geomatys)
037 * @version 3.1
038 * @since   2.3
039 */
040@UML(identifier="MX_DataFile", specification=ISO_19115_3)
041public interface DataFile {
042    /**
043     * Name of the file that contains the data.
044     *
045     * @departure integration
046     *   ISO 19115-3 type is {@code <gcx:FileName>}, which we map to a {@link URI} in Java.
047     *
048     * @return name of the file that contains the data.
049     *
050     * @see BrowseGraphic#getFileName()
051     *
052     * @since 3.1
053     */
054    @UML(identifier="fileName", obligation=MANDATORY, specification=ISO_19115_3)
055    URI getFileName();
056
057    /**
058     * Text description of the data.
059     *
060     * @return text description of the data.
061     *
062     * @see BrowseGraphic#getFileDescription()
063     *
064     * @since 3.1
065     */
066    @UML(identifier="fileDescription", obligation=MANDATORY, specification=ISO_19115_3)
067    InternationalString getFileDescription();
068
069    /**
070     * Format in which the data is encoded.
071     *
072     * @departure integration
073     *   ISO 19115-3 type is {@code <gcx:MimeFileType>}.
074     *
075     * @return format in which the data is encoded.
076     *
077     * @see BrowseGraphic#getFileType()
078     *
079     * @since 3.1
080     */
081    @UML(identifier="fileType", obligation=MANDATORY, specification=ISO_19115_3)
082    String getFileType();
083
084    /**
085     * Provides the list of feature types concerned by the transfer data file. Depending on
086     * the transfer choices, a data file may contain data related to one or many feature types.
087     * This attribute may be omitted when the dataset is composed of a single file and/or the
088     * data does not relate to a feature catalogue.
089     *
090     * @return list of features types concerned by the transfer data file.
091     */
092    @UML(identifier="featureTypes", obligation=OPTIONAL, specification=ISO_19115_3)
093    default Collection<? extends LocalName> getFeatureTypes() {
094        return Collections.emptyList();
095    }
096
097    /**
098     * Defines the format of the transfer data file.
099     *
100     * @return format of the transfer data file.
101     *
102     * @deprecated Removed in latest XSD schemas.
103     */
104    @Deprecated(since="3.1")
105    @UML(identifier="fileFormat", obligation=MANDATORY, specification=ISO_19139, version=2007)
106    default Format getFileFormat() {
107        return null;
108    }
109}