Package org.opentrafficsim.core.perception

Class AbstractHistorical<T,​E extends AbstractHistorical.Event>

  • Type Parameters:
    T - value type
    E - event type
    All Implemented Interfaces:
    HistoryManager.HistoricalElement
    Direct Known Subclasses:
    AbstractHistoricalCollection, AbstractHistoricalMap, HistoricalParameters, HistoricalValue
    public abstract class AbstractHistorical<T,​E extends AbstractHistorical.Event>
extends Object
implements HistoryManager.HistoricalElement
    Base class for objects or properties that can be perceived from their actual state in the past. The principle by which a past state is determined is by storing an internal event for each change to the object. Each event can be reversed, and by working from a current state backwards, any previous state within the available history can be restored.

    This class couples the historical to a HistoryManager and in response to a request from the HistoryManager will clear old events. Subclasses need to define their own events as extensions to AbstractHistorical.Event. This class provides the following methods to subclasses to work with the events.
    • now(), returns the current time from the HistoryManager, which needs to be stored with each event.
    • getEvents(Time), returns all events between now and the given time, ordered from recent to old.
    • getEvent(Time), returns the most recent event from before the given time.
    • getLastEvent(), returns the most recent event.
    • removeEvent(Event), removes (oldest occurrence off) the event.
    • addEvent(Event), add the event.
    Typically, any change results in a new event which is added with addEvent(Event), where the event stores information such that the event can be restored. When an old state is requested, one or more events can be obtained with either of the get methods, after which they are applied to restore a previous state in a manner depending on the nature of the subclass.

    This class is defined with a single event type parameter E. Subclasses can use different event classes, so long as all of them derive from a common ancestor. For instance an 'add' and a 'remove' event that inherit from an abstract super.

    Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
    BSD-style license. See OpenTrafficSim License.

    Version:
    $Revision$, $LastChangedDate$, by $Author$, initial version 1 jan. 2018
    Author:
    Alexander Verbraeck, Peter Knoppers, Wouter Schakel

    • Constructor Detail

      • AbstractHistorical

        protected AbstractHistorical​(HistoryManager historyManager)
        Constructor.
        Parameters:
        historyManager - HistoryManager; history manager

    • Method Detail

      • now

        protected final Time now()
        Returns the current time.
        Returns:
        Time; current time

      • getEvents

        protected final List<E> getEvents​(Time time)
        Returns a list of events, ordered last to first, that includes all events after time.
        Parameters:
        time - Time; past time up to which to include events
        Returns:
        List; list of events, ordered last to first, that includes all events after time

      • getEvent

        protected final E getEvent​(Time time)
        Returns the most recent event from before or on time, or the oldest if no such event.
        Parameters:
        time - Time; past time at which to obtain event
        Returns:
        E; most recent event from before time

      • getLastEvent

        protected final E getLastEvent()
        Returns the last event.
        Returns:
        E; last event

      • isLastState

        protected final boolean isLastState​(Time time)
        Returns whether the state at the given time is equal to the state at the current time.
        Parameters:
        time - Time; time
        Returns:
        boolean; whether the state at the given time is equal to the state at the current time

      • removeEvent

        protected final void removeEvent​(E event)
        Removes the given event.
        Parameters:
        event - E; event to remove

      • addEvent

        protected final void addEvent​(E event)
        Adds the event to the list of events.
        Parameters:
        event - E; event to add

      • cleanUpHistory

        public final void cleanUpHistory​(Duration history)
        Removes events that are no longer needed to guarantee the history time. This is invoked by the history manager.
        Specified by:
        cleanUpHistory in interface HistoryManager.HistoricalElement
        Parameters:
        history - Duration; history time to keep