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 java.util.Collection;
021import org.opengis.util.GenericName;
022
023
024/**
025 * An instance of an {@link FeatureAssociationRole} containing the associated feature.
026 * {@code FeatureAssociation} can be instantiated by calls to {@link FeatureAssociationRole#newInstance()}.
027 *
028 * @author  Jody Garnett (Refractions Research, Inc.)
029 * @author  Justin Deoliveira (The Open Planning Project)
030 * @author  Martin Desruisseaux (Geomatys)
031 * @version 3.1
032 * @since   3.1
033 *
034 * @see FeatureAssociationRole
035 */
036public interface FeatureAssociation extends Property {
037    /**
038     * Returns the name of this association as defined by its {@linkplain #getRole() role}.
039     * This convenience method delegates to {@link FeatureAssociationRole#getName()}.
040     *
041     * @return the association name specified by its role.
042     */
043    @Override
044    GenericName getName();
045
046    /**
047     * Returns information about the association.
048     *
049     * @return information about the association.
050     */
051    FeatureAssociationRole getRole();
052
053    /**
054     * Returns the associated feature, or {@code null} if none. This convenience method can be invoked in
055     * the common case where the {@linkplain FeatureAssociationRole#getMaximumOccurs() maximum number} of
056     * features is restricted to 1 or 0.
057     *
058     * @return the associated feature (may be {@code null}).
059     * @throws MultiValuedPropertyException if this association contains more than one value.
060     *
061     * @see Feature#getPropertyValue(String)
062     */
063    @Override
064    Feature getValue() throws MultiValuedPropertyException;
065
066    /**
067     * Sets the associated feature.
068     *
069     * <h4>Note on validation</h4>
070     * The verifications performed by this method is implementation dependent.
071     * For performance reasons, an implementation may verify only the most basic constraints
072     * and offer another method for performing more extensive validation.
073     * Implementations should document their validation process.
074     *
075     * @param  value  the new value, or {@code null}.
076     * @throws InvalidPropertyValueException if this method verifies argument validity and the given value
077     *         does not met the association constraints.
078     *
079     * @see Feature#setPropertyValue(String, Object)
080     */
081    void setValue(Feature value) throws InvalidPropertyValueException;
082
083    /**
084     * Returns all features, or an empty collection if none.
085     *
086     * <h4>Note for implementers</h4>
087     * There is different approaches in the way that collection elements are related to this property values:
088     * <ul>
089     *   <li>The collection may be a snapshot of property values at the method invocation time.</li>
090     *   <li>The collection may be an unmodifiable view of properties values.</li>
091     *   <li>The collection may be <i>live</i> (changes in the collection are reflected in this association, and vis-versa).</li>
092     * </ul>
093     * This method does not mandate a particular approach.
094     * However, implementations should document which policy they choose.
095     *
096     * @return the features.
097     */
098    Collection<Feature> getValues();
099
100    /**
101     * Sets the features. All previous values are replaced by the given collection.
102     *
103     * <h4>Note on validation</h4>
104     * The verifications performed by this method is implementation dependent.
105     * For performance reasons, an implementation may verify only the most basic constraints
106     * and offer another method for performing more extensive validation.
107     * Implementations should document their validation process.
108     *
109     * @param  values  the new values.
110     * @throws InvalidPropertyValueException if this method verifies argument validity and the given values
111     *         do not met the association constraints.
112     */
113    void setValues(Collection<? extends Feature> values) throws InvalidPropertyValueException;
114}