Annotation Interface Coerce
Usage with callback injectors (@Inject)
This annotation has two usages applicable to Callback Injectors (defined
using @Inject. For local capture injectors, it indicates
that the injector should coerce top-level primitive types (int) to covariant
types defined on the handler. It can also be used on a reference type to
indicate that the intended type is covariant over the argument type (or that
the argument type is contravariant on the target class type). This can be
used for multi-target injectors with a bounded type argument on the class or
target method. It is also acceptable to use an interface directly or
indirectly implemented by the relevant class, including interfaces applied by
other mixins.
@Coerce also has an important usage with primitive types. It is not always possible during LVT generation to determine the exact local type for types represented internally as integers, for example booleans and shorts. However adding a surrogate for these cases is overkill when the type is known for certain by the injector. Since the bytecode for all types stored as integer interally will be valid, we can force the local type to any covariant type as long as we know this in advance.
This annotation allows a covariant type parameter to be marked, and thus coerced to the correct type when the LVT generation would otherwise mark the type as invalid.
Usage with redirect injectors (@Redirect)
Similarly to callback injectors, @Coerce can be used to
indicate that an incoming parameter can be consumed as a valid supertype, up
to and including Object. This is particularly useful when an argument
on the target method invocation is inaccessible or unknown.
Since Mixin 0.8 it is also possible to use @Coerce on the return type of a field gettter or method invocation redirector. To do so simply annotate the method itself. Note that doing so will cast the return type back to the original return type as part of the injection, so the object must be of an appropriate type regardless of visibility.