001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2014-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.feature;
019
020import java.util.Optional;
021import org.opengis.annotation.Classifier;
022import org.opengis.annotation.Stereotype;
023import org.opengis.annotation.UML;
024import org.opengis.util.GenericName;
025import org.opengis.util.InternationalString;
026
027import static org.opengis.annotation.Obligation.*;
028import static org.opengis.annotation.Specification.ISO_19109;
029
030
031/**
032 * Identification and description information inherited by property types and feature types.
033 *
034 * @author  Martin Desruisseaux (Geomatys)
035 * @version 3.1
036 * @since   3.1
037 */
038@Classifier(Stereotype.METACLASS)
039@UML(identifier="IdentifiedType", specification=ISO_19109)
040public interface IdentifiedType {
041    /**
042     * Returns the name of this type. The namespace can be either explicit
043     * ({@link org.opengis.util.ScopedName}) or implicit
044     * ({@link org.opengis.util.LocalName}).
045     *
046     * The name is optional for {@link Operation}, but mandatory for other types.
047     * For {@link AttributeType}, the name shall be unique in the {@code FeatureType}.
048     * For {@link FeatureType}, the name shall be unique in the unit processing the data.
049     *
050     * @return the type name, or {@code null} if none.
051     */
052    @UML(identifier="name", obligation=OPTIONAL, specification=ISO_19109)
053    GenericName getName();
054
055    /**
056     * Returns a concise definition of the element.
057     *
058     * @return concise definition of the element.
059     */
060    @UML(identifier="definition", obligation=MANDATORY, specification=ISO_19109)
061    InternationalString getDefinition();
062
063    /**
064     * Returns a natural language designator for the element.
065     * This can be used as an alternative to the {@linkplain #getName() name} in user interfaces.
066     *
067     * @return natural language designator for the element.
068     */
069    @UML(identifier="designation", obligation=OPTIONAL, specification=ISO_19109)
070    default Optional<InternationalString> getDesignation() {
071        return Optional.empty();
072    }
073
074    /**
075     * Returns optional information beyond that required for concise definition of the element.
076     * The description may assist in understanding the element scope and application.
077     *
078     * @return information beyond that required for concise definition of the element.
079     */
080    @UML(identifier="description", obligation=OPTIONAL, specification=ISO_19109)
081    default Optional<InternationalString> getDescription() {
082        return Optional.empty();
083    }
084
085    /*
086     * ISO 19109 properties omitted for now:
087     *
088     *   - constrainedBy : CharacterString
089     *
090     * Rational: a CharacterString is hardly programmatically usable.
091     * We may want for a {@code org.opengis.filter} package to be defined, and use it.
092     */
093}