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}