groovy.beans.ListenerList.groovy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of driver-cql-shaded Show documentation
A Shaded CQL ActivityType driver for http://nosqlbench.io/
There is a newer version: 4.15.102
/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 */
package groovy.beans

import org.codehaus.groovy.transform.GroovyASTTransformationClass

import java.lang.annotation.Documented
import java.lang.annotation.ElementType
import java.lang.annotation.Retention
import java.lang.annotation.RetentionPolicy
import java.lang.annotation.Target

/**
 * 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 ListenerListASTTransformation
 * @author Alexander Klein
 * @author Hamlet D'Arcy
 */
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.FIELD)
@GroovyASTTransformationClass('groovy.beans.ListenerListASTTransformation')
@interface ListenerList {
    /**
     * 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.
     */
    String name() default ""

    /**
     * Whether or not the methods created should be synchronized at the method level.
     */
    boolean synchronize() default false
}