|Target Version:||Groovy 2.2 / 2.2+|
SAM stands for Single Abstract Method. SAM coercion is here a Groovy style transformation of a groovy.lang.Closure instance into an object suitable for our SAM type. A SAM type is an abstract class or interface with a single abstract method. The coercion can happen as part of an assignment or as the result of a method call. Since this transformation might be outside of the types provided by Closure itself, it can be more than a simple Java style cast. Closure becomes a kind of sub type to all SAM types. Groovy has other such transformations without explicit cast or asType usage, which are number object transformations as well as the conversion of GString to String.
Even before Java8 we had discussions about supporting different interfaces with Closure like Runnable and Callable. These two being easy cases, any framework can define a myriad of interfaces and abstract classes. This then requires to "groovify" the library by writing a helper layer capable of transforming Closure objects into something the library then understand. While it is unlikely of this approach to make Groovy Builder surplus, it can still help with a more simple integration.
Meaning of "Single Abstract Method"
For a SAM type to be a SAM type according to this GEP an abstract class or interface with a single abstract method is required. Any static methods, as well as non-abstract methods are not counted. The abstract method may be defined in the SAM class itself, but it can also be a parent. The required visibility modifier for the method is public though.
Interface with defender method (aka virtual extension method):
Interface inheriting from another interface:
Interface inheriting from another interface, but not defining a method on its own:
simple abstract class
abstract class with a abstract and a non abstract method:
abstract class extending other class:
abstract class implementing interface:
interface with two methods:
abstract class with two abstract methods:
empty abstract class:
Influence on method selection
The normal method selection algorithm tries to find the most specific method to the given argument runtime types and the most general for null. Since a SAM type and a target method parameter type are not in an inheritance relation "most specific" needs a redefinition in parts. It will be assumed the SAM type is like a direct child of the given target type, but if the SAM type is one implemented by Closure (Runnable and Callable), then no SAM coercion will be needed. This case is preferred in method selection. In case of a overloaded method, where each can be used as target for the SAM coercion, method selection will thus fail, regardless their internal relation. In Groovy the actual method signature of the SAM type and the coercion target are not important. Also it is not important if the target type is an abstract class or an interface.
Example of two SAM targets with failing runtime method selection:
Example of SAM type being ignore as a non-coercion case is available:
Influence on static typing system
The Scope for the static type system is split into a basic part for Groovy 2.2 and an extended one for a later version (2.3 or 3.0)
Groovy 2.2 static checks
The type checking in Groovy 2.2 will be limited to mimic the behavior of normal Groovy. No method signature checks are performed, as well as there will be no additional test or method selection based on the type provided by the open block.
Groovy 2.2+ static checks
In later versions of Groovy the static type checker has to be improved to refine method selection by the given type signature through the open block or lambda. A SAM type is then a fitting type for the coercion only if the provided types and the target types in the SAM are matching by number and type itself. A more detailed description can be found here: http://cr.openjdk.java.net/~dlsmith/jsr335-0.6.1/F.html