Package: groovy.beans

## [Groovy] Annotation Type ListenerList

- groovy.beans.ListenerList

- All Implemented Interfaces and Traits:
    Annotation

      @Documented
      @Retention(value=RetentionPolicy.SOURCE)
      @Target(value=ElementType.FIELD)
      @GroovyASTTransformationClass(value=["groovy.beans.ListenerListASTStubber", "groovy.beans.ListenerListASTTransformation"])
      @interface 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

  Joint compilation note: when the listener interface is itself a Groovy class in the same compilation unit and gains methods from another AST transform, those `fireXxx` overloads are not visible in the stub. Classpath listener interfaces (e.g. `java.beans.PropertyChangeListener`, `java.awt.event.ActionListener`) are fully covered for Java callers.

  See Also:
    ListenerListASTTransformation

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `abstract String` | `name()` A suffix for creating the add, remove, and get methods defaulting to the name of the listener type, e.g. if name is set to MyListener, then the class will have addMyListener, removeMyListener, and getMyListeners methods.
    `` | `abstract boolean` | `synchronize()` Whether or not the methods created should be synchronized at the method level.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### abstract String name()

      A suffix for creating the add, remove, and get methods defaulting to the name of the listener type, e.g. if name is set to MyListener, then the class will have addMyListener, removeMyListener, and getMyListeners methods.

      Returns:
        the suffix used when deriving generated listener method names

    - #### abstract boolean synchronize()

      Whether or not the methods created should be synchronized at the method level.

      Returns:
        `true` if generated listener methods should be synchronized