net.sf.jaer.event
Class EventPacket<E extends BasicEvent>

java.lang.Object
  net.sf.jaer.event.EventPacket<E>

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<E>

public class EventPacket<E extends BasicEvent>
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Iterable<E>

A packet of events that is used for rendering and event processing. For efficiency, these packets are designed to be re-used; they should be allocated rarely and allowed to grow in size. If a packet capacity needs to be increased a substantial peformance hit will occur e.g. 1 ms per resizing or initial allocation.

The EventPacket is prefilled with Events that have default values. One constructor lets you fill the EventPacket with a subclass of BasicEvent. This prefilling avoids the overhead of object creation. It also allows easy access to all information contained in the event and it allows storing arbitrary event information, including extended type information, in EventPackets.

However, this reuse of existing objects means that you need to take particular precautions. The events that are stored in a packet are references to objects. Therefore you can assign an event to a different packet but this event will still be referenced in the original packet and can change.

Generally in event processing, you will iterate over an input packet to produce an output packet. You iterate over an exsiting EventPacket that has input data using the iterator(). This lets you access the events in the input packet.

When you want to write these events to an existing output packet, then you need to use the target event's copyFrom(Event e) method that copies all the fields in the source packet to the target packet. This lets you copy data such as timestamp, x,y location to a target event. You can then fill in the target event's extended type infomation.

When you iterate over an input packet to write to a target packet, you obtain the target event to write your results to by using the target packet's output enumeration by using the outputIterator() method. This enumeration has a method nextOutput() that returns the next output event to write to. This nextOutput() method also expands the packet if they current capacity needs to be enlarged. The iterator is initialized by the call to outputIterator().

The amount of time iterating over events can also be limited by using the time limiter. This static (class) method starts a timer when it is restarted and after timeout, no more events are returned from input iteration. These methods are used in FilterChain to limit processing time.

Author:

tobi

Field Summary

int	DEFAULT_INITIAL_CAPACITY Default capacity in events for new EventPackets

Constructor Summary

EventPacket()
Constructs a new EventPacket filled with BasicEvent.

EventPacket(java.lang.Class<? extends BasicEvent> eventClass)
Constructs a new EventPacket filled with the given event class.

Method Summary

void	clear() Sets the size to zero.
java.lang.String	getDescription()
int	getDurationUs() Returns duration of packet in microseconds.
E	getEvent(int k) Returns the k'th event.
java.lang.Class	getEventClass() Returns the class of event in this packet.
E	getEventPrototype() Returns a prototype of the events in the packet.
float	getEventRateHz()
E	getFirstEvent() Returns first event, or null if there are no events.
int	getFirstTimestamp() Returns first timestamp or 0 if there are no events.
E	getLastEvent() Returns last event, or null if there are no events.
int	getLastTimestamp()
int	getNumCellTypes() Returns the number of 'types' of events.
int	getSize() Returns the number of events in the packet.
static int	getTimeLimitMs() Gets the class time limit for iteration in ms
protected void	initializeEvents() Fills this with DEFAULT_INITIAL_CAPACITY of the event class
java.util.Iterator<E>	inputIterator() Returns after initializng the iterator over input events.
boolean	isEmpty() Reports if the packet is empty.
static boolean	isTimedOut() Returns true if timeLimitTimer is timed out and timeLimitEnabled
static boolean	isTimeLimitEnabled() Returns status of time limiting
java.util.Iterator<E>	iterator() Initializes and returns the iterator
OutputEventIterator<E>	outputIterator() Returns an iterator that iterates over the output events.
static void	restartTimeLimiter() Resets the time limiter for input iteration.
static void	restartTimeLimiter(int timeLimitMs) restart the time limiter with limit timeLimitMs
void	setEventClass(java.lang.Class<? extends BasicEvent> eventClass) Sets the event class for this packet and fills the packet with these events.
protected void	setSize(int n)
static void	setTimeLimitEnabled(boolean yes)
static void	setTimeLimitMs(int timeLimitMs) Sets the class time limit for filtering a packet through the filter chain in ms.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_INITIAL_CAPACITY

public final int DEFAULT_INITIAL_CAPACITY

Default capacity in events for new EventPackets

See Also:

Constant Field Values

Constructor Detail

EventPacket

public EventPacket()

Constructs a new EventPacket filled with BasicEvent.

See Also:

BasicEvent

EventPacket

public EventPacket(java.lang.Class<? extends BasicEvent> eventClass)

Constructs a new EventPacket filled with the given event class.

See Also:

BasicEvent

Method Detail

restartTimeLimiter

public static void restartTimeLimiter()

Resets the time limiter for input iteration. After the timer times out (time determined by timeLimitMs) input iterators will not return any more events.

restartTimeLimiter

public static void restartTimeLimiter(int timeLimitMs)

restart the time limiter with limit timeLimitMs

Parameters:

timeLimitMs - time in ms

initializeEvents

protected void initializeEvents()

Fills this with DEFAULT_INITIAL_CAPACITY of the event class

getDurationUs

public int getDurationUs()

Returns duration of packet in microseconds.

Returns:

0 if there are less than 2 events, otherwise last timestamp minus first timestamp.

getDescription

public java.lang.String getDescription()

clear

public void clear()

Sets the size to zero.

setSize

protected void setSize(int n)

getEventRateHz

public float getEventRateHz()

Returns:

event rate for this packet in Hz measured stupidly by the size in events divided by the packet duration. If packet duration is zero, rate returned is zero.

getFirstEvent

public E getFirstEvent()

Returns first event, or null if there are no events.

Returns:

the event or null if there are no events.

getLastEvent

public E getLastEvent()

Returns last event, or null if there are no events.

Returns:

the event or null if there are no events.

getFirstTimestamp

public int getFirstTimestamp()

Returns first timestamp or 0 if there are no events.

Returns:

timestamp

getLastTimestamp

public int getLastTimestamp()

Returns:

last timestamp in packet. If packet is empty, returns zero - which could be important if this time is used for e.g. filtering operations!

getEvent

public final E getEvent(int k)

Returns the k'th event.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if out of bounds of packet.

inputIterator

public final java.util.Iterator<E> inputIterator()

Returns after initializng the iterator over input events.

Returns:

an iterator that can iterate over the events.

outputIterator

public final OutputEventIterator<E> outputIterator()

Returns an iterator that iterates over the output events.

Returns:

the iterator. Use it to obtain new output events which can be then copied from other events or modfified.

getSize

public final int getSize()

Returns the number of events in the packet.

Returns:

size in events.

isEmpty

public boolean isEmpty()

Reports if the packet is empty.

Returns:

true if empty.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getNumCellTypes

public final int getNumCellTypes()

Returns the number of 'types' of events.

Returns:

the number of types, typically a small number like 1,2, or 4.

getEventPrototype

public final E getEventPrototype()

Returns a prototype of the events in the packet.

Returns:

a single instance of the event.

iterator

public final java.util.Iterator<E> iterator()

Initializes and returns the iterator

Specified by:

iterator in interface java.lang.Iterable<E extends BasicEvent>

getEventClass

public final java.lang.Class getEventClass()

Returns the class of event in this packet.

Returns:

the event class.

setEventClass

public final void setEventClass(java.lang.Class<? extends BasicEvent> eventClass)

Sets the event class for this packet and fills the packet with these events.

Parameters:

eventClass - which much extend BasicEvent

getTimeLimitMs

public static final int getTimeLimitMs()

Gets the class time limit for iteration in ms

setTimeLimitMs

public static final void setTimeLimitMs(int timeLimitMs)

Sets the class time limit for filtering a packet through the filter chain in ms.

Parameters:

timeLimitMs - the time limit in ms

See Also:

restartTimeLimiter()

setTimeLimitEnabled

public static final void setTimeLimitEnabled(boolean yes)

isTimeLimitEnabled

public static final boolean isTimeLimitEnabled()

Returns status of time limiting

Returns:

true if timelimiting is enabled

isTimedOut

public static final boolean isTimedOut()

Returns true if timeLimitTimer is timed out and timeLimitEnabled