[Groovy] Annotation Type ListenerList

This annotation adds Java-style listener support to a class based on an annotated Collection-property.

For any given Collection property, several methods will be written into the enclosing class during the compile phase. These changes are visible from Java or other languages. The List is intended to hold listeners of some sort, and the methods addListener, removeListener, and getListeners are all added to the class. The actual methods names depend on the generic type of the collection.

Given the following example:

 class MyClass {
     @groovy.beans.ListenerList
     List<java.awt.event.ActionListener> listeners
 }
 

The following code is generated:

 public class MyClass extends java.lang.Object {
     @groovy.beans.ListenerList
     private java.util.List<java.awt.event.ActionListener> listeners

     public void addActionListener(java.awt.event.ActionListener listener) {
         if ( listener == null) {
             return null
         }
         if ( listeners == null) {
             listeners = []
         }
         listeners.add(listener)
     }

     public void removeActionListener(java.awt.event.ActionListener listener) {
         if ( listener == null) {
             return null
         }
         if ( listeners == null) {
             listeners = []
         }
         listeners.remove(listener)
     }

     public java.awt.event.ActionListener[] getActionListeners() {
         java.lang.Object __result = []
         if ( listeners != null) {
             __result.addAll(listeners)
         }
         return (( __result ) as java.awt.event.ActionListener[])
     }

     public void fireActionPerformed(java.awt.event.ActionEvent param0) {
         if ( listeners != null) {
             def __list = new java.util.ArrayList(listeners)
             for (java.lang.Object listener : __list ) {
                 listener.actionPerformed(param0)
             }
         }
     }
 }
 

A fire method is created for each public method in the target class. In this case, ActionListener only has one method. For a four method interface, four fire methods would be created.

The annotation can take the following parameters:

 name        = a suffix for creating the add, remove, and get methods.
               Default: Name of the listener type
               In the above example, if name is set to MyListener, then the class will have an addMyListener,
               removeMyListener, and getMyListeners methods. 

 synchronize = Whether or not the methods created should be synchronized at the method level. 
               Default: false
 

Compilation Errors - Using this annotation incorrectly results in compilation errors rather than runtime errors. A list of potential problems includes:

• This annotation can only be applied to a field of type Collection
• The annotated Collection field must have a generic type
• The annotated Collection field must not have a generic wildcard declared
• The generated methods must not already exist

See Also:

ListenerListASTTransformation

Authors:

Alexander Klein

Hamlet D'Arcy