How events work

The following process describes how events work:

  1. The application or a server business process requests to register a handler for a specific local or remote event. If the application is doing the requesting, this usually occurs during the startup process of the application.
  2. For the server, the server event manager will create a corresponding Mirror Handler and adds this Mirror Handler to interested Mirror Notifier's event list.

    For the client, If the client event manager finds the notifier for the event in the given context or in the event manager's table of notifiers, the client event manager adds the handler to the notifier's list of registered handlers.

    If the client event manager cannot find the notifier in the context or in its table of notifiers, it assumes that the notifier is defined on the server and therefore the event is a remote event. the client event manager adds the handler to its table of handlers. (The entry for the handler includes information about the event name, the notifier name, and, if provided, the workstation that signals the event.) If you do not provide the server workstation parameter, the system sets its value to default. This value means that the handler listens for the event signaled by a notifier from any server workstation with which the client workstation has a session.

  3. For BTT Server, when a BTT Notifier generates an event, it will first go to the server event manager through message queue. When the server event manager get this event, it will find corresponding Mirror Notifier and gets the list of Mirror Handler's which interests in this event. Then invokes each of Mirror Handlers' dispatchEvent() method. "dispatchEvent()" method will send event with BTT handler global ID to message queue. In the other side, BTT Handler will use JMSEvReceipt class to keep listening message queue. If the global ID matches its global ID, JMSEvReceipt then retrieves the event and passes to BTT Handler.

    For BTT client, when a DSE Notifier generates an event, it goes through its list of handlers and calls the dispatchEvent method of the first handler in the list of handlers for the event. Note that notifier calls the handlers in the reverse order of their registration. That is, the last handler registered is the first handler called.

  4. For the server, when a BTT Handler receives an event, it directly invokes its "dispatchEvent" method. User can overwrite this method to put event processes.

    For the client, when a handler receives an event, it determines whether it will consume the event or propagate it to the next handler waiting for it. If the dispatchEvent method returns this, the notifier propagates the event to the next handler on the list. If the dispatchEvent method returns null, the handler stops propagating the event. This means that the notifier may not send the event to all of the registered handlers. Note that if the notifier propagates the event to a remote handler, the notifier does not expect a reply because remote notification is asynchronous.

    The diagram below shows an event being processed by a chain of handlers. The DSENotifier object has three handlers (aHandler1, aHandler2, and aHandler3) that are listeners for the event called noDocument. When the DSENotifier instance generates the event noDocument (signalEvent ("noDocument")), it is sent to the handler instance called "aHandler1". The handler instance called "aHandler1" is not interested in the event, so it returns the value "this" to pass the event to the next handler in the chain. The second handler processes the event and decides not to propagate it by returning null. The third handler is never called, even though it is capable of processing the event.

    Image of a flowchart illustrating an event being processed by a chain of handlers.