VetoableASTTransformation (groovy 2.4.5 API)
Date: 2015-09-17

Package: groovy.beans

## [Java] Class VetoableASTTransformation

- groovy.beans.VetoableASTTransformation

- Handles generation of code for the `@Vetoable` annotation, and `@Bindable` if also present.

  Generally, it adds (if needed) a VetoableChangeSupport field and the needed add/removeVetoableChangeListener methods to support the listeners.

  It also generates the setter and wires the setter through the VetoableChangeSupport.

  If a Bindable annotation is detected it also adds support similar to what BindableASTTransformation would do.

  Authors:
    Danno Ferrin (shemnon)
    Chris Reeves

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected static ClassNode` | `constrainedClassNode` |

  - Inherited fields
    Fields inherited from class | Fields
    --- | ---
    `class BindableASTTransformation` | `boundClassNode`

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `protected void` | `addVetoableChangeSupport(ClassNode declaringClass)` Adds the necessary field and methods to support vetoable change support.
    `protected Statement` | `createConstrainedStatement(PropertyNode propertyNode, Expression fieldExpression)` Creates a statement body similar to: `this.fireVetoableChange("field", field, field = value)`
    `protected Statement` | `createSetStatement(Expression fieldExpression)` Creates a statement body similar to: `field = value`.
    `protected void` | `createSetterMethod(ClassNode declaringClass, PropertyNode propertyNode, String setterName, Statement setterBlock)` Creates a setter method with the given body.
    `static boolean` | `hasVetoableAnnotation(AnnotatedNode node)` Convenience method to see if an annotated node is `@Vetoable`.
    `protected boolean` | `needsVetoableChangeSupport(ClassNode declaringClass, SourceUnit sourceUnit)` Snoops through the declaring class and all parents looking for a field of type VetoableChangeSupport.
    `void` | `visit(ASTNode[] nodes, SourceUnit source)` Handles the bulk of the processing, mostly delegating to other methods.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class BindableASTTransformation` | `addPropertyChangeSupport, createBindableStatement, createSetterMethod, hasBindableAnnotation, needsPropertyChangeSupport, visit`
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Field Detail

    - #### protected static ClassNode constrainedClassNode

  - ### Method Detail

    - #### protected void addVetoableChangeSupport(ClassNode declaringClass)

      Adds the necessary field and methods to support vetoable change support.

      Adds a new field: `"protected final java.beans.VetoableChangeSupport this$vetoableChangeSupport = new java.beans.VetoableChangeSupport(this)"`

      Also adds support methods: `public void addVetoableChangeListener(java.beans.VetoableChangeListener)` `public void addVetoableChangeListener(String, java.beans.VetoableChangeListener)` `public void removeVetoableChangeListener(java.beans.VetoableChangeListener)` `public void removeVetoableChangeListener(String, java.beans.VetoableChangeListener)` `public java.beans.VetoableChangeListener[] getVetoableChangeListeners()`

      Parameters:
        `declaringClass` - the class to which we add the support field and methods

    - #### protected Statement createConstrainedStatement(PropertyNode propertyNode, Expression fieldExpression)

      Creates a statement body similar to: `this.fireVetoableChange("field", field, field = value)`

      Parameters:
        `propertyNode` - the field node for the property
        `fieldExpression` - a field expression for setting the property value
      Returns:
        the created statement

    - #### protected Statement createSetStatement(Expression fieldExpression)

      Creates a statement body similar to: `field = value`.

      Used when the field is not also `@Bindable`.

      Parameters:
        `fieldExpression` - a field expression for setting the property value
      Returns:
        the created statement

    - #### protected void createSetterMethod(ClassNode declaringClass, PropertyNode propertyNode, String setterName, Statement setterBlock)

      Creates a setter method with the given body.

      This differs from normal setters in that we need to add a declared exception java.beans.PropertyVetoException

      Parameters:
        `declaringClass` - the class to which we will add the setter
        `propertyNode` - the field to back the setter
        `setterName` - the name of the setter
        `setterBlock` - the statement representing the setter block

    - #### public static boolean hasVetoableAnnotation(AnnotatedNode node)

      Convenience method to see if an annotated node is `@Vetoable`.

      Parameters:
        `node` - the node to check
      Returns:
        true if the node is constrained

    - #### protected boolean needsVetoableChangeSupport(ClassNode declaringClass, SourceUnit sourceUnit)

      Snoops through the declaring class and all parents looking for a field of type VetoableChangeSupport. Remembers the field and returns false if found otherwise returns true to indicate that such support should be added.

      Parameters:
        `declaringClass` - the class to search
      Returns:
        true if vetoable change support should be added

    - #### public void visit(ASTNode[] nodes, SourceUnit source)

      Handles the bulk of the processing, mostly delegating to other methods.

      Parameters:
        `nodes` - the AST nodes
        `source` - the source unit for the nodes