groovy.transform

Annotation Type AutoImplement

@Documented
 @Retention(value=SOURCE)
 @Target(value=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 and 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 Detail

exception

public abstract 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

public abstract 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

public abstract Class code

If defined, all unimplemented methods will execute the code found within the supplied closure.

Default:

groovy.transform.Undefined.CLASS.class