001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-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.citation;
019
020import java.util.Collection;
021import java.util.Collections;
022import org.opengis.util.InternationalString;
023import org.opengis.annotation.UML;
024import org.opengis.annotation.Classifier;
025import org.opengis.annotation.Stereotype;
026
027import static org.opengis.annotation.Obligation.*;
028import static org.opengis.annotation.Specification.*;
029
030
031/**
032 * Location of the responsible individual or organization.
033 *
034 * @author  Martin Desruisseaux (IRD)
035 * @version 3.1
036 * @since   1.0
037 */
038@Classifier(Stereotype.DATATYPE)
039@UML(identifier="CI_Address", specification=ISO_19115)
040public interface Address {
041    /**
042     * Address lines for the location (as described in ISO 11180, Annex A).
043     * This method allows multiple values for describing a location on many lines,
044     * not for enumerating many locations.
045     *
046     * <div class="warning"><b>Upcoming API change — internationalization</b><br>
047     * The return type will be changed from {@code Collection<String>} to
048     * {@code Collection<? extends InternationalString>} in GeoAPI 4.0.
049     * </div>
050     *
051     * @return address lines for the location, or an empty collection if none.
052     *
053     * @todo https://github.com/opengeospatial/geoapi/issues/34
054     */
055    @UML(identifier="deliveryPoint", obligation=OPTIONAL, specification=ISO_19115)
056    default Collection<String> getDeliveryPoints() {
057        return Collections.emptyList();
058    }
059
060    /**
061     * The city of the location.
062     * Returns {@code null} if unspecified.
063     *
064     * @return the city of the location, or {@code null}.
065     */
066    @UML(identifier="city", obligation=OPTIONAL, specification=ISO_19115)
067    default InternationalString getCity() {
068        return null;
069    }
070
071    /**
072     * State, province of the location.
073     * Returns {@code null} if unspecified.
074     *
075     * @return state, province of the location, or {@code null}.
076     */
077    @UML(identifier="administrativeArea", obligation=OPTIONAL, specification=ISO_19115)
078    default InternationalString getAdministrativeArea() {
079        return null;
080    }
081
082    /**
083     * ZIP or other postal code.
084     * Returns {@code null} if unspecified.
085     *
086     * @return ZIP or other postal code, or {@code null}.
087     */
088    @UML(identifier="postalCode", obligation=OPTIONAL, specification=ISO_19115)
089    default String getPostalCode() {
090        return null;
091    }
092
093    /**
094     * Country of the physical address.
095     * Returns {@code null} if unspecified.
096     *
097     * @return country of the physical address, or {@code null}.
098     */
099    @UML(identifier="country", obligation=OPTIONAL, specification=ISO_19115)
100    default InternationalString getCountry() {
101        return null;
102    }
103
104    /**
105     * Address of the electronic mailbox of the responsible organization or individual.
106     * Returns an empty collection if none.
107     *
108     * @return address of the electronic mailbox of the responsible organization or individual.
109     */
110    @UML(identifier="electronicMailAddress", obligation=OPTIONAL, specification=ISO_19115)
111    default Collection<String> getElectronicMailAddresses() {
112        return Collections.emptySet();                          // Use Set instead of List for hash-safe final classes.
113    }
114}