001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2003-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.citation;
019
020import java.util.Collection;
021import java.util.Collections;
022import java.util.Date;
023import org.opengis.metadata.Identifier;
024import org.opengis.metadata.identification.BrowseGraphic;
025import org.opengis.util.InternationalString;
026import org.opengis.annotation.UML;
027import org.opengis.annotation.Profile;
028import org.opengis.annotation.Classifier;
029import org.opengis.annotation.Stereotype;
030
031import static org.opengis.annotation.Obligation.*;
032import static org.opengis.annotation.Specification.*;
033import static org.opengis.annotation.ComplianceLevel.*;
034
035
036/**
037 * Standardized resource reference.
038 *
039 * @author  Martin Desruisseaux (IRD)
040 * @author  Cory Horner (Refractions Research)
041 * @author  Rémi Maréchal (Geomatys)
042 * @version 3.1
043 * @since   1.0
044 */
045@Classifier(Stereotype.DATATYPE)
046@UML(identifier="CI_Citation", specification=ISO_19115)
047public interface Citation {
048    /**
049     * Name by which the cited resource is known.
050     *
051     * @return the cited resource name.
052     */
053    @Profile(level=CORE)
054    @UML(identifier="title", obligation=MANDATORY, specification=ISO_19115)
055    InternationalString getTitle();
056
057    /**
058     * Short names or other language names by which the cited information is known.
059     * Returns an empty collection if there is none.
060     *
061     * <div class="note"><b>Example:</b>
062     * "DCW" as an alternative title for "Digital Chart of the World".
063     * </div>
064     *
065     * @return other names for the resource, or an empty collection if none.
066     */
067    @UML(identifier="alternateTitle", obligation=OPTIONAL, specification=ISO_19115)
068    default Collection<? extends InternationalString> getAlternateTitles() {
069        return Collections.emptyList();
070    }
071
072    /**
073     * Reference dates for the cited resource.
074     *
075     * @return reference dates for the cited resource.
076     */
077    @Profile(level=CORE)
078    @UML(identifier="date", obligation=OPTIONAL, specification=ISO_19115)
079    default Collection<? extends CitationDate> getDates() {
080        return Collections.emptyList();
081    }
082
083    /**
084     * Version of the cited resource.
085     *
086     * @return the version, or {@code null} if none.
087     */
088    @UML(identifier="edition", obligation=OPTIONAL, specification=ISO_19115)
089    default InternationalString getEdition() {
090        return null;
091    }
092
093    /**
094     * Date of the edition, or {@code null} if none.
095     *
096     * <div class="warning"><b>Upcoming API change — temporal schema</b><br>
097     * As of Java 8, the {@code java.time} package is a better match for the different
098     * types of date defined by ISO 19108 (<cite>Temporal Schema</cite>) or ISO 19103.
099     * The return value of this method may be changed to {@link java.time.temporal.Temporal} in GeoAPI 4.0.
100     * </div>
101     *
102     * @return the edition date, or {@code null} if none.
103     */
104    @UML(identifier="editionDate", obligation=OPTIONAL, specification=ISO_19115)
105    default Date getEditionDate() {
106        return null;
107    }
108
109    /**
110     * Unique identifier for the resource.
111     * Returns an empty collection if there is none.
112     *
113     * <div class="note"><b>Example:</b>
114     * Universal Product Code (UPC), National Stock Number (NSN).
115     * </div>
116     *
117     * @return the identifiers, or an empty collection if none.
118     */
119    @UML(identifier="identifier", obligation=OPTIONAL, specification=ISO_19115)
120    default Collection<? extends Identifier> getIdentifiers() {
121        return Collections.emptyList();
122    }
123
124    /**
125     * Role, name, contact and position information for individuals or organisations
126     * that are responsible for the resource.
127     * Returns an empty collection if there is none.
128     *
129     * <div class="warning"><b>Upcoming API change — generalization</b><br>
130     * As of ISO 19115:2014, {@code ResponsibleParty} is replaced by the {@link Responsibility} parent interface.
131     * This change may be applied in GeoAPI 4.0.
132     * </div>
133     *
134     * @return the information for individuals or organisations that are responsible for the resource,
135     *         or an empty collection if none.
136     */
137    @UML(identifier="citedResponsibleParty", obligation=OPTIONAL, specification=ISO_19115, version=2003)
138    default Collection<? extends ResponsibleParty> getCitedResponsibleParties() {
139        return Collections.emptyList();
140    }
141
142    /**
143     * Mode in which the resource is represented.
144     * Returns an empty collection if there is none.
145     *
146     * @return the presentation mode, or an empty collection if none.
147     */
148    @UML(identifier="presentationForm", obligation=OPTIONAL, specification=ISO_19115)
149    default Collection<PresentationForm> getPresentationForms() {
150        return Collections.emptySet();                          // Use Set instead of List for hash-safe final classes.
151    }
152
153    /**
154     * Information about the series, or aggregate dataset, of which the dataset is a part.
155     * Returns {@code null} if there is none.
156     *
157     * @return the series or aggregate dataset of which the dataset is a part, or {@code null} if none.
158     */
159    @UML(identifier="series", obligation=OPTIONAL, specification=ISO_19115)
160    default Series getSeries() {
161        return null;
162    }
163
164    /**
165     * Other information required to complete the citation that is not recorded elsewhere.
166     * Returns {@code null} if none.
167     *
168     * <div class="warning"><b>Upcoming API change — multiplicity</b><br>
169     * As of ISO 19115:2014, this singleton has been replaced by a collection.
170     * This change may be applied in GeoAPI 4.0.
171     * </div>
172     *
173     * @return other details, or {@code null} if none.
174     */
175    @UML(identifier="otherCitationDetails", obligation=OPTIONAL, specification=ISO_19115, version=2003)
176    default InternationalString getOtherCitationDetails() {
177        return null;
178    }
179
180    /**
181     * Common title with holdings note. Title identifies elements of a series collectively,
182     * combined with information about what volumes are available at the source cited.
183     *
184     * @return the common title, or {@code null} if none.
185     *
186     * @deprecated Removed as of ISO 19115:2014.
187     */
188    @Deprecated(since="3.1")
189    @UML(identifier="collectiveTitle", obligation=OPTIONAL, specification=ISO_19115, version=2003)
190    default InternationalString getCollectiveTitle() {
191        return null;
192    }
193
194    /**
195     * International Standard Book Number.
196     * Returns {@code null} if there is none.
197     *
198     * @return the International Standard Book Number, or {@code null} if none.
199     */
200    @UML(identifier="ISBN", obligation=OPTIONAL, specification=ISO_19115)
201    default String getISBN() {
202        return null;
203    }
204
205    /**
206     * International Standard Serial Number.
207     * Returns {@code null} if there is none.
208     *
209     * @return the International Standard Serial Number, or {@code null} if none.
210     */
211    @UML(identifier="ISSN", obligation=OPTIONAL, specification=ISO_19115)
212    default String getISSN() {
213        return null;
214    }
215
216    /**
217     * Online references to the cited resource.
218     * Returns an empty collection if there is none.
219     *
220     * @return online references to the cited resource, or an empty collection if none.
221     *
222     * @since 3.1
223     */
224    @UML(identifier="onlineResource", obligation=OPTIONAL, specification=ISO_19115)
225    default Collection<? extends OnlineResource> getOnlineResources() {
226        return Collections.emptyList();
227    }
228
229    /**
230     * Citation graphics or logo for cited party.
231     * Returns an empty collection if there is none.
232     *
233     * @return graphics or logo for cited party, or an empty collection if none.
234     *
235     * @since 3.1
236     */
237    @UML(identifier="graphic", obligation=OPTIONAL, specification=ISO_19115)
238    default Collection<? extends BrowseGraphic> getGraphics() {
239        return Collections.emptyList();
240    }
241}