fulmine.event
Interface IEventFrame

All Known Subinterfaces:

IContainer

All Known Implementing Classes:

AbstractContainer, AbstractDynamicContainer, AbstractEventProcessingContainer, BasicContainer, Record

public interface IEventFrame

An event frame groups events from an IEventSource object into a unit of work.

An event frame has a repeating execution life-cycle:

  start -> add event -> commit events 
    ˆ       ˆ    |           |
    |       |____|           |
    |________________________|
 

The life-cycle stages are thread bound except for the 'add events' stage; the starting thread has to execute the 'commit events' stage. This thread is known as the event frame thread. Any thread can execute in the 'add events' stage. The distinction arises so that a publisher thread can control when an event frame starts and commits events, whilst separate threads can provide the events that form the event frame's unit of work.

An event frame is loosely analogous to a transaction, but with no concurrency or roll-back. Two threads that want to start an event frame on the same event source object have to do so sequentially:

 | thread #1 frame |
                   | thread #2 frame |
 

Author:

Ramon Servadei

Method Summary

void	addEvent(IEvent event) Add an event to an event frame.
void	beginFrame(IEventFrameExecution frame) An event frame life-cycle control method to start an event frame.
void	endFrame() An event frame life-cycle control method to commit all events within an event frame.
void	flushFrame() A convenience method to perform the event frame life-cycle methods at once.
boolean	isFrameActive() Identifies if an event frame is currently active.

Method Detail

beginFrame

void beginFrame(IEventFrameExecution frame)

An event frame life-cycle control method to start an event frame. The executing thread becomes the event frame thread and is the same thread that must execute the endFrame() and #end().

If an event frame is already active in another thread, this method blocks until the other frame ends.

Parameters:

frame - the frame identifier

Throws:

IllegalStateException - if this is called more than once before endFrame() is called

flushFrame

void flushFrame()

A convenience method to perform the event frame life-cycle methods at once. This is useful to process programmatically triggering events with one method call. This method will block if a frame is currently active and the executing thread is not the current event frame thread.

endFrame

void endFrame()

An event frame life-cycle control method to commit all events within an event frame. The executing thread must be the event frame thread (i.e. the same thread that started the event frame by executing a previous call to beginFrame(IEventFrameExecution)).

addEvent

void addEvent(IEvent event)

Add an event to an event frame. Any thread can execute this method. The event will be processed when a call to endFrame() is executed.

If this method is executed outside of an event frame or at the same time as the event frame thread is executing the endFrame(), the event becomes part of the next event frame's unit of work.

There is no stipulation on the ordering of the stored events nor is there any stipulation regarding coalescing of events.

Parameters:

event - the event

isFrameActive

boolean isFrameActive()

Identifies if an event frame is currently active. This is useful when determining if a new frame needs to be started or not when triggering events.

Returns:

true if an event frame is currently active (started)