Package org.spongepowered.asm.mixin.injection

Annotation Type Coerce

  • @Target({PARAMETER,METHOD})
public @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.