Package: groovy.transform

## [Groovy] Annotation Type ConditionalInterrupt

- groovy.transform.ConditionalInterrupt

- All Implemented Interfaces and Traits:
    Annotation

      @Documented
      @Retention(value=RetentionPolicy.SOURCE)
      @Target(value=[ElementType.PACKAGE, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.LOCAL_VARIABLE])
      @GroovyASTTransformationClass(value="org.codehaus.groovy.transform.ConditionalInterruptibleASTTransformation")
      @interface ConditionalInterrupt

  Allows "interrupt-safe" executions of scripts by adding a custom check for interruption into loops (for, while, ...) and at the start of closures and methods.

  This is especially useful when executing foreign scripts that you do not have control over. Inject this transformation into a script that you need to interrupt based on some custom criteria.

  Annotating anything in a script will cause for loops, while loops, methods, and closures to make a check against the specified closure. If the closure yields true (according to GroovyTruth), then the script will throw an InterruptedException. The annotation by default applies to any classes defined in the script as well. Annotated a class will cause (by default) all classes in the entire file ('Compilation Unit') to be enhanced. You can fine tune what is enhanced using the annotation parameters.

  The following is sample usage of the annotation:

       @ConditionalInterrupt({ counter++> 10})
       import groovy.transform.ConditionalInterrupt

       counter = 0
       def scriptMethod() {
            4.times {
                println 'executing script method...'
            }
       }

       scriptMethod()

  Which results in the following code being generated (XXXXXX will be replaced with some runtime generated hashCode). Notice the checks and exceptions:

       public class script1291741477073 extends groovy.lang.Script {
         Object counter = 0

         public java.lang.Object run() {
           counter = 0
         }

         public java.lang.Object scriptMethod() {
           if (this.conditionalTransformXXXXXX$condition()) {
             throw new java.lang.InterruptedException('Execution interrupted. The following condition failed: { counter++> 10}')
           }
           4.times({
             if (this.conditionalTransformXXXXXX$condition()) {
               throw new java.lang.InterruptedException('Execution interrupted. The following condition failed: { counter++> 10}')
             }
             this.println('executing script method...')
           })
         }

         private java.lang.Object conditionalTransformXXXXXX$condition() {
           counter++ > 10
         }
       }

  Note that when you're annotating scripts, the variable scoping semantics are unchanged. Therefore, you must be careful about the variable scope you're using. Make sure that variables you reference in the closure parameter are in scope during script execution. The following example will throw a MissingPropertyException because counter is not in scope for a class:

       import groovy.transform.ConditionalInterrupt

       def counter = 0
       @ConditionalInterrupt({ counter++> 10})
       class MyClass {
         def myMethod() {
           4.times {
             println 'executing script method...'
           }
         }
       }

       new MyClass().myMethod()

  Additional usage examples can be found in the unit test for this class.
  See Also:
    TimedInterrupt
    ThreadInterrupt
  Since:
    1.8.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `abstract boolean` | `applyToAllClasses()` Set this to false if you have multiple classes within one source file and only want a conditional check on some of the classes.
    `` | `abstract boolean` | `applyToAllMembers()` Set this to false if you have multiple methods/closures within a class or script and only want conditional checks on some of them.
    `` | `abstract boolean` | `checkOnMethodStart()` By default a conditional check is added to the start of all user-defined methods.
    `` | `abstract Class` | `thrown()` Sets the type of exception which is thrown.
    `` | `abstract Class` | `value()` Conditional check - set as a closure expression.

  - ### Inherited Methods Summary

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

- - ### Method Detail

    - #### abstract boolean applyToAllClasses()

      Set this to false if you have multiple classes within one source file and only want a conditional check on some of the classes. Place annotations on the classes you want enhanced. Set to true (the default) for blanket coverage of conditional checks on all methods, loops and closures within all classes/script code. For even finer-grained control see `applyToAllMembers`.

      Returns:
        `true` if interrupt checks apply to all classes in the compilation unit
      See Also:
        applyToAllMembers()

    - #### abstract boolean applyToAllMembers()

      Set this to false if you have multiple methods/closures within a class or script and only want conditional checks on some of them. Place annotations on the methods/closures that you want enhanced. When false, `applyToAllClasses` is automatically set to false. Set to true (the default) for blanket coverage of conditional checks on all methods, loops and closures within the class/script.

      Returns:
        `true` if interrupt checks apply to all members of the annotated class or script
      Since:
        2.2.0
      See Also:
        applyToAllClasses()

    - #### abstract boolean checkOnMethodStart()

      By default a conditional check is added to the start of all user-defined methods. To turn this off simply set this parameter to false.

      Returns:
        `true` if the condition is evaluated at method entry

    - #### abstract Class thrown()

      Sets the type of exception which is thrown.

      Returns:
        the exception type thrown when the condition evaluates to `true`

    - #### abstract Class value()

      Conditional check - set as a closure expression.

      Returns:
        the closure expression used to decide whether execution should be interrupted