AutoImplement (Groovy 4.0.15)
Description: declaration: package: groovy.transform, annotation type: AutoImplement

Package groovy.transform

# Annotation Type AutoImplement

@Documented @Retention(SOURCE) @Target(TYPE) public @interface AutoImplement
Class annotation used to provide default dummy methods for a class extending an abstract super class or implementing one or more interfaces.

Example usage:

     import groovy.transform.AutoImplement

     @AutoImplement
     class EmptyStringIterator implements Iterator {
         boolean hasNext() { false }
     }

     assert !new EmptyStringIterator().hasNext()

In the above example, since `hasNext` returns false, the `next` method should never be called, so any dummy implementation would do for `next`. The "empty" implementation provided by default when using `@AutoImplement` will suffice - which effectively returns `null` in Groovy for non-void, non-primitive methods. As a point of interest, the default implementation for methods returning primitive types is to return the default value (which incidentally never satisfies Groovy truth). For `boolean` this means returning `false`, so for the above example we could have (albeit perhaps less instructive of our intent) by just using:

     @AutoImplement
     class EmptyStringIterator implements Iterator { }

If we didn't want to assume that callers of our `EmptyStringIterator` correctly followed the `Iterator` contract, then we might want to guard against inappropriate calls to `next`. Rather than just returning `null`, we might want to throw an exception. This is easily done using the `exception` annotation attribute as shown below:

     import groovy.transform.AutoImplement
     import static groovy.test.GroovyAssert.shouldFail

     @AutoImplement(exception=UnsupportedOperationException)
     class EmptyStringIterator implements Iterator {
         boolean hasNext() { false }
     }

     shouldFail(UnsupportedOperationException) {
         new EmptyStringIterator().next()
     }

All implemented methods will throw an instance of this exception constructed using its no-arg constructor. You can also supply a single `message` annotation attribute in which case the message will be passed as an argument during exception construction as shown in the following example:

     @AutoImplement(exception=UnsupportedOperationException, message='Not supported for this empty iterator')
     class EmptyStringIterator implements Iterator {
         boolean hasNext() { false }
     }

     def ex = shouldFail(UnsupportedOperationException) {
         new EmptyStringIterator().next()
     }
     assert ex.message == 'Not supported for this empty iterator'

Finally, you can alternatively supply a `code` annotation attribute in which case a closure block can be supplied which should contain the code to execute for all implemented methods. This can be seen in the following example:

     @AutoImplement(code = { throw new UnsupportedOperationException("Not supported for ${getClass().simpleName}") })
     class EmptyStringIterator implements Iterator {
         boolean hasNext() { false }
     }

     def ex = shouldFail(UnsupportedOperationException) {
         new EmptyStringIterator().next()
     }
     assert ex.message == 'Not supported for EmptyStringIterator'

Since:
  2.5.0

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `Class`
  `code`
  If defined, all unimplemented methods will execute the code found within the supplied closure.
  `Class<? extends RuntimeException>`
  `exception`
  If defined, all unimplemented methods will throw this exception.
  `String`
  `message`
  If `exception` is defined, `message` can be used to specify the exception message.

- ## Element Details

  - ### exception

    Class<? extends RuntimeException> exception
    If defined, all unimplemented methods will throw this exception. Will be ignored if `code` is defined.
    Default:
      groovy.transform.Undefined.EXCEPTION.class

  - ### message

    String message
    If `exception` is defined, `message` can be used to specify the exception message. Will be ignored if `code` is defined or `exception` isn't defined.
    Default:
      "<DummyUndefinedMarkerString-DoNotUse>"

  - ### code

    Class code
    If defined, all unimplemented methods will execute the code found within the supplied closure.
    Default:
      groovy.transform.Undefined.CLASS.class