Runtime tools : Core components : Events : Concepts : Handler registration and deregistration
  
Handler registration and deregistration
The application can register a handler for a specific local or remote event at any time. In both cases, it calls handleEvent method and uses the event name, the notifier name, the context in which the handler is running, and the server name as arguments. If the handler needs to listen for an event coming from a specific workstation, the server name is the TID (terminal identifier) of the workstation.
The event manager receives all requests for event handler registration but its behavior differs depending on whether the event notifier is local or remote:
If the event manager detects that the notifier that signals the event is available in the given context or in its list of notifier instantiated in the workstation, the event manager adds the handler to the notifier's list of registered handlers.
If the event manager can not find the notifier in the context or in its list of notifiers, the event manager assumes that the notifier is defined on the server. In this case, it adds the handler to its own list of handlers. The event manager stores the event name, the notifier name and, if provided, the TID of workstation that signal the event. If the TID is not provided, the event manager listens to the event signaled by a notifier located on any workstation with which the client workstation has a session.
The event manager adds only listeners for remote events to its list of handlers. All local handlers register with the notifier that signals the event.
If the application has registered interest in a remote event with the client event manager, it does not have to do any registration on the remote workstation. The remote operation, if it is responsible for registering a remote handler, or the local operation takes care of the registration process before the handler is instantiated and registered. The remote operation uses the addHandler method of the specific notifier to do this while the local operation uses the registerInterestInRemoteEvent or the registerServerInterestInEvent methods.
At any time, the application can remove itself as a listener for a remote event. The event manager provides the deregisterInterestInRemoteEvent and deregisterServerInterestInEvent methods to disable a remote event notification to a workstation. The application would use one of these methods when there are no handlers waiting locally for a specific remote event. Before it does so, the application first call the hasHandlersInterestedIn method passing the event and notifier names and the CSClient instance as arguments. This method returns a Vector of the local handlers listening for the remote event or it returns null to indicate that there are no registered handlers in this workstation for the remote event. The application can then remove its interest in this remote event on the server by calling the deregisterInterestInRemoteEvent method. This method stops the remote workstation from sending these events to the client workstation and thus prevents unnecessary client/server messages. The deregisterInterestInRemoteEvent method starts a client/server communication to start a remote EventManagerServerOperation. This operation invokes the removeHandler method in the event manager using the event name, the notifier name, and the originating workstation TID as arguments. The event manager removes itself from the notifier's list of handlers and removes the workstation from the table of workstations listening for this event. The application can also disable remote event notification locally using the deregisterServerInterestInEvent method. This method deregisters the interest of a server workstation in a client workstation event.
A handler can also unregister itself as a listener for an event. It uses its own stopHandlingEvent method using the event name, the notifier name, the context in which the handler is instantiated, and, if it wants to stop handling an event coming from a specific workstation, the TID of that workstation as arguments. This method calls the event manager, which in turn invokes removeHandler in the local notifier or removes the handler from list of handlers of event manager if the local notifier does not exist.
Go up to
Concepts