001/* 002 * GeoAPI - Java interfaces for OGC/ISO standards 003 * Copyright © 2018-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 java.time.temporal.Temporal; 022 023 024/** 025 * An instance of a {@link DynamicAttributeType} containing time-dependent values of an attribute. 026 * A dynamic attribute represents the result of ascertaining the value of an attribute of a moving 027 * feature that changes over time and/or location. Dynamic attributes contain non-spatial values; 028 * time-varying geometric values should be represented by trajectories instead. 029 * {@code DynamicAttribute} holds four main information: 030 * 031 * <ul> 032 * <li>A {@linkplain #getType() reference to a dynamic attribute type} 033 * which defines the base Java type and domain of valid values.</li> 034 * <li>One or more {@linkplain #valuesAt values at given times}, 035 * which may be singletons ([0 … 1] multiplicity) or multi-valued ([0 … ∞] multiplicity).</li> 036 * <li>One or more {@linkplain #getValues() values at no particular time} (optional), 037 * inherited from the parent {@link Attribute} interface.</li> 038 * <li>Optional {@linkplain #characteristics() characteristics} about the attribute.</li> 039 * </ul> 040 * 041 * Values are evaluated at given {@link Temporal} positions, which may be calendar dates or Julian days for instances. 042 * Even though the value of dynamic attribute depends on the spatiotemporal location, 043 * this interface only considers the temporal dependencies of their changes of value. 044 * Evaluating at the given temporal position may require interpolation. 045 * Interpolation algorithm, if any, is implementation-dependent. 046 * 047 * <p>{@code DynamicAttribute} can be instantiated by calls to {@link DynamicAttributeType#newInstance()}.</p> 048 * 049 * @param <V> the type of dynamic attribute values. 050 * 051 * @author Martin Desruisseaux (Geomatys) 052 * @version 3.1 053 * @since 3.1 054 * 055 * @see DynamicAttributeType 056 * @see Attribute 057 */ 058public interface DynamicAttribute<V> extends Attribute<V> { 059 /** 060 * Returns information about the dynamic attribute (base Java class, domain of values, <i>etc.</i>). 061 * 062 * @return information about the dynamic attribute. 063 */ 064 @Override 065 DynamicAttributeType<V> getType(); 066 067 /** 068 * Returns the attribute value at the given time, or {@code null} if none. 069 * This convenience method can be invoked in the common case where the 070 * {@linkplain DynamicAttributeType#getMaximumOccurs() maximum number} 071 * of dynamic attribute values is restricted to 1 or 0. 072 * 073 * @param time the date, Julian day or other means to represent a position in time. 074 * @return the attribute value at the given time, or {@code null} if none. 075 * @throws IllegalArgumentException if the given time is not a type supported by this implementation. 076 * @throws OutOfTemporalDomainException if the given time is outside the period of validity. 077 * @throws MultiValuedPropertyException if this attribute contains more than one value at the given time. 078 */ 079 V valueAt(Temporal time) throws OutOfTemporalDomainException, MultiValuedPropertyException; 080 081 /** 082 * Returns all attribute values at the given time, or an empty collection if none. 083 * Evaluating at the given temporal position may require interpolation. 084 * Interpolation algorithm, if any, is implementation-dependent. 085 * 086 * <h4>Note for implementers</h4> 087 * There is different approaches in the way that collection elements are related to those 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 attribute, 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 * @param time the date, Julian day or other means to represent a position in time. 097 * @return the attribute values. 098 * @throws IllegalArgumentException if the given time is not a type supported by this implementation. 099 * @throws OutOfTemporalDomainException if the given time is outside the period of validity. 100 */ 101 Collection<V> valuesAt(Temporal time) throws OutOfTemporalDomainException; 102}