Triggering and Handling Events
In ABAP Objects, triggering and handling an event means that certain methods act as triggers and trigger events, to which other methods - the handlers - react. This means that the handler methods are executed when the event occurs.
This section contains explains how to work with events in ABAP Objects. For precise details of the relevant ABAP statements, refer to the corresponding keyword documentation in the ABAP Editor.
To trigger an event, a class must
- Declare the event in its declaration part
- Trigger the event in one of its methods
Declaring Events
You declare events in the declaration part of a class or in an interface. To declare instance events, use the following statement:
EVENTS evt EXPORTING... VALUE(e1 e2 ...) TYPE type [OPTIONAL]..
To declare static events, use the following statement:
CLASS-EVENTS evt...
Both statements have the same syntax.
When you declare an event, you can use the EXPORTINGaddition to specify parameters that are passed to the event handler. The parameters are always passed by value. Instance events always contain the implicit parameter SENDER, which has the type of a reference to the type or the interface in which the event is declared.
Triggering Events
An instance event in a class can be triggered by any instance method in the class. Static events can be triggered by any method. However, static methods can only trigger static events. To trigger an event in a method, use the following statement:
RAISE EVENT evt EXPORTING e 1 = f 1 e 2 = f 2 ...
For each formal parameter e1 that is not defined as optional, you must pass a corresponding actual parameter f1 in the EXPORTING addition. The self-reference me is automatically passed to the implicit parameter sender.
Events are handled using special methods. To handle an event, a method must
- be defined as an event handler method for that event
- be registered at runtime for the event.
Declaring Event Handler Methods
Any class can contain event handler methods for events from other classes. You can, of course, also define event handler methods in the same class as the event itself. To declare an event handler method, use the following statement:
METHODS meth FOR EVENT evt OF cif IMPORTING e 1 e 2 ...
for an instance method. For a static method, use CLASS-METHODS instead of METHODS. evtis an event declared in the class or interface cif.
The interface of an event handler method may only contain formal parameters defined in the declaration of the event evt. The attributes of the parameter are also adopted by the event. The event handler method does not have to use all of the parameters passed in the RAISE EVENT statement. If you want the implicit parameter sender to be used as well, you must list it in the interface. This parameter allows an instance event handler to access the trigger, for example, to allow it to return results.
If you declare an event handler method in a class, it means that the instances of the class or the class itself are, in principle, able to handle an event evt triggered in a method.
Registering Event Handler Methods
To allow an event handler method to react to an event, you must determine at runtime the trigger to which it is to react. You can do this with the following statement:
SET HANDLER h 1 h 2 ... [FOR]...
It links a list of handler methods with corresponding trigger methods. There are four different types of event.
It can be
- An instance event declared in a class
- An instance event declared in an interface
- A static event declared in a class
- A static event declared in an interface
The syntax and effect of the SET HANDLERdepends on which of the four cases listed above applies.
For an instance event, you must use the FOR addition to specify the instance for which you want to register the handler. You can either specify a single instance as the trigger, using a reference variable ref:
SET HANDLER h 1 h 2 ... FOR ref.
or you can register the handler for all instances that can trigger the event:
SET HANDLER h 1 h 2 ... FOR ALL INSTANCES.
The registration then applies even to triggering instances that have not yet been created when you register the handler.
You cannot use the FOR addition for static events:
SET HANDLER h 1 h 2 ...
The registration applies automatically to the whole class, or to all of the classes that implement the interface containing the static event. In the case of interfaces, the registration also applies to classes that are not loaded until after the handler has been registered.
Timing of Event Handling
After the RAISE EVENTstatement, all registered handler methods are executed before the next statement is processed (synchronous event handling). If a handler method itself triggers events, its handler methods are executed before the original handler method continues. To avoid the possibility of endless recursion, events may currently only be nested 64 deep.
Handler methods are executed in the order in which they were registered. Since event handlers are registered dynamically, you should not assume that they will be processed in a particular order. Instead, you should program as though all event handlers will be executed simultaneously.
See also: