001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2014-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.feature;
019
020import org.opengis.annotation.UML;
021import org.opengis.annotation.Classifier;
022import org.opengis.annotation.Stereotype;
023import org.opengis.util.GenericName;
024
025import static org.opengis.annotation.Obligation.*;
026import static org.opengis.annotation.Specification.ISO_19109;
027
028
029/**
030 * Indicates the role played by the association between two features.
031 * In the area of geographic information, there exist multiple kinds of associations:
032 *
033 * <ul>
034 *   <li><b>Aggregation</b> represents associations between features which can exist even if the aggregate is destroyed.</li>
035 *   <li><b>Composition</b> represents relationships where the owned features are destroyed together with the composite.</li>
036 *   <li><b>Spatial</b> association represents spatial or topological relationships that may exist between features (e.g. <q>east of</q>).</li>
037 *   <li><b>Temporal</b> association may represent for example a sequence of changes over time involving the replacement of some
038 *       feature instances by other feature instances.</li>
039 * </ul>
040 *
041 * @author  Jody Garnett (Refractions Research, Inc.)
042 * @author  Justin Deoliveira (The Open Planning Project)
043 * @author  Martin Desruisseaux (Geomatys)
044 * @version 3.1
045 * @since   3.1
046 *
047 * @see FeatureAssociation
048 */
049@Classifier(Stereotype.METACLASS)
050@UML(identifier="FeatureAssociationRole", specification=ISO_19109)
051public interface FeatureAssociationRole extends PropertyType {
052    /**
053     * Returns the name of this association role.
054     * For {@code FeatureAssociationRole}, the name is mandatory.
055     *
056     * @return the association role name.
057     */
058    @Override
059    @UML(identifier="name", obligation=MANDATORY, specification=ISO_19109)
060    GenericName getName();
061
062    /**
063     * Returns the type of feature values.
064     *
065     * @return the type of feature values.
066     */
067    @UML(identifier="valueType", obligation=MANDATORY, specification=ISO_19109)
068    FeatureType getValueType();
069
070    /**
071     * Returns the minimum number of occurrences of the association within its containing entity.
072     * The returned value is greater than or equal to zero.
073     *
074     * @return the minimum number of occurrences of the association within its containing entity.
075     */
076    @UML(identifier="cardinality", obligation=MANDATORY, specification=ISO_19109)
077    int getMinimumOccurs();
078
079    /**
080     * Returns the maximum number of occurrences of the association within its containing entity.
081     * The returned value is greater than or equal to the {@link #getMinimumOccurs()} value.
082     * If there is no maximum, then this method returns {@link Integer#MAX_VALUE}.
083     *
084     * @return the maximum number of occurrences of the association within its containing entity,
085     *         or {@link Integer#MAX_VALUE} if none.
086     */
087    @UML(identifier="cardinality", obligation=MANDATORY, specification=ISO_19109)
088    int getMaximumOccurs();
089
090    /**
091     * Creates a new feature association instance of this role.
092     *
093     * @return a new feature association instance.
094     * @throws UnsupportedOperationException if this role does not support new instance creation.
095     */
096    FeatureAssociation newInstance() throws UnsupportedOperationException;
097}