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 and Description
static class	AbstractHistorical.EventValue<T> Standard event which stores a time and value.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractHistorical(HistoryManager historyManager) Constructor.

Method Summary

Modifier and Type	Method and 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 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