Event Subscription
Events provide the glue to dynamically bind actors to each other
and to entities
without any of them having to be directly aware of,
or in any way connected to, each other.
Any set of actors can coordinate their actions by creating new
DataManagerEvent
s
to trigger each other on.
Every subscription requires three bits of code:
-
In the declaration for the event handler class,
code that specifies that the class
either implements the event handler interface
or extends a class that implements the event handler interface.
This may be an inner class, the actor itself, or an external class
(especially an active entity value, but it may be any class).
For example:
public class MyHandler implements EventHandler
-
Code that implements the event handler interface method.
For example:
public void handle(DataManagerEvent event) { ...//code that reacts to the event... }
-
Code that registers an instance of the event handler class
for particular events (described by a constraint)
of a particular event generator.
For example:
someEventGenerator.subscribe(instanceOfMyHandler, instanceOfMyEventConstraint);
The subscribe()
method
takes an event handler and a constraint.
A ValueClassIsConstraint
is a subclass of class Constraint
that takes a Class as a parameter of its constructor.
You can use this Class class to filter DataManagerEvents
.
When an event generator fires an event,
the kernel checks whether any event handlers
are subscribed to the event generator.
If there are any,
it then checks their registered event constraints
to see if the event matches.
For each such constraint that the event matches,
the kernel passes the event on to the appropriate handler
by executing its handle()
method in an event handler thread.
The kernel then discards the event.
Any number of handlers, including none, can listen to the same generator. A handler can even listen multiple times to the same generator, although presumably with different event constraints. (The kernel does not check for identical constraints even for the same generator and handler.) Events that no handler is listening for will simply be discarded. Handlers that have been subscribed multiple times to a single generator can only unsubscribe totally from it, so to remove any one subscription an actor must unsubscribe all of them, then add the others back again.
A GetValueEvent
fires
when anyone examines an entity's value.
A SetValueEvent
fires
when anyone alters an entity's value.
An AttachLinkEvent
fires
when anyone links two entities
(both entities generate an event).
A DetachLinkEvent
fires
when anyone unlinks two entities
(both entities generate an event).
Event handlers may listen to the pool (an event generator) to detect
inter-module events (for example, NetworkDownCollectorEvent
).