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 DataManagerEvents 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).