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}