EventListener annotation

EventListener lets you write an event handler for a Java™ environment, giving the EGL generator the information needed to create code that conforms to the Java event-listener pattern. The annotation is used in an external type of stereotypeJavaObject.

EGL package name

eglx.lang

Example use
Consider the java.beans package, which a Java developer uses to code a kind of Java class typically known as a Java bean or, more simply, a bean. Among its capabilities, a bean can invoke a method of a Java object in response to a runtime event. The rest of this description assumes that the runtime event is a change of a property value in the bean.

The Java developer registers that type of event by invoking the addPropertyChangeListener method of the bean and by passing a PropertyChangeListener object. In general terms, the PropertyChangeListener object is an event listener.

After a property value changes, the bean calls the event listener. Specifically, the bean calls the propertyChange method of the PropertyChangeListener object and passes a PropertyChangeEvent object that gives details about the change.

A further detail is that the event listener is based on a Java interface, and the propertyChange method is specific to a business application. The EGL developer's use of the @eventListener property means that the EGL-generated propertyChange method invokes logic that is derived from a developer-coded EGL function.

Before continuing this example, review the annotation detail and fields.

Annotation detail
Record EventListener type Annotation
{
   targets = [
      ElementKind.FieldMbr
   ]
} 
   addMethod String;
   listenerType String;
   method String;
end
Annotation fields
addMethod
A string that contains the name of the Java method that registers an event listener. Do not include parentheses when identifying the method.

In the previous example, the value of addMethod is “addPropertyChangeListener”.

listenerType
A string that contains the name of a Java class that acts as a listener. Include the package name for that class.

In the previous example, the value of listenerType is “java.beans.PropertyChangeListener”.

method
A string that contains the name of a Java method that is in the listener and that is invoked when the event occurs.

In the previous example, the value of method is “propertyChange”.

Comments
Continuing the example, consider EGL code that defines an external type for a bean named MyBean. The external type includes a field named onPropertyChange, which is based on a Delegate part shown later:
ExternalType MyBean type JavaObject
   onPropertyChange PropertyChangeDelegate
      { @eventListener{ addMethod = "addPropertyChangeListener", 
                        listenerType = "java.beans.PropertyChangeListener", 
                        method = "propertyChange" } };
end

The onPropertyChange field is not in the bean, but is present so that the listener pattern is available in your EGL code, where you assign that EGL function that will be invoked when an event occurs.

In keeping with the propertyChange method, the PropertyChangeDelegate Delegate part has a single parameter, which is an external type that is based on the PropertyChangeEvent object.
Delegate PropertyChangeDelegate( evt PropertyChangeEvent in ) 
end

ExternalType PropertyChangeEvent type JavaObject { packageName = "java.beans" }
   function getPropertyName() returns ( string );
   // You might make available other methods of java.beans.PropertyChangeEvent.
end
To see the use of the MyBean external type, consider the following EGL program:
program MyEGLProgram
   function main()
      mb MyBean{ onPropertyChange = propChange };
   end

   function propChange( evt PropertyChangeEvent in )
      writeStdout( "Property " :: evt.getPropertyName() :: " has changed." );
   end
end

The program creates a variable of type MyBean, assigns a function to the onPropertyChange field of that type, and defines the function itself. When a property value changes in the bean, the function is invoked and uses getPropertyName, which is the one method that was made available from the PropertyChangeEvent object.

Always assign the @eventListener property to a variable that is based on a Delegate part. The characteristics of the Delegate part must conform to an event-handling method such as propertyChange, which is in a specific Java event listener such as PropertyChangeListener.

When you reference Java field and method names in the code, remember that they are case sensitive, even though the equivalent EGL names are not.

Compatibility

Table 1. Compatibility
Target Issue
Java No issues.
JavaScript Not in use.