Package org.opentrafficsim.core.perception

Class AbstractHistorical<T,​E extends org.opentrafficsim.core.perception.AbstractHistorical.Event>

java.lang.Object
org.opentrafficsim.core.perception.AbstractHistorical<T,​E>
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 org.opentrafficsim.core.perception.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-2019 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

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  AbstractHistorical.EventValue<T>
    Standard event which stores a time and value.

  • Constructor Summary

    Constructors 
    Modifier Constructor Description
    protected AbstractHistorical​(HistoryManager historyManager)
    Constructor.

  • Method Summary

    Modifier and Type Method Description
    protected void addEvent​(E event)
    Adds the event to the list of events.
    void cleanUpHistory​(Duration history)
    Removes events that are no longer needed to guarantee the history time.
    protected E getEvent​(Time time)
    Returns the most recent event from before or on time, or the oldest if no such event.
    protected List<E> getEvents​(Time time)
    Returns a list of events, ordered last to first, that includes all events after time.
    protected E getLastEvent()
    Returns the last event.
    protected boolean isLastState​(Time time)
    Returns whether the state at the given time is equal to the state at the current time.
    protected Time now()
    Returns the current time.
    protected void removeEvent​(E event)
    Removes the given event.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

  • Method Details

    • 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