======= Interface Injection =======

===== Overview =====

Interface injection is a technique to add methods into a specific existing class.
More specifically, you can create an interface, and then inject this interface into the class.
As result the target class will acquire all the methods of the interface, as if it always had them.

This is particularly useful for libraries, with this you can add new methods to existing classes and use them without the need of casting or reimplementing the interface every time.

Fabric API takes advantage of this technique. For example, ''TagBuilder'' implements ''FabricTagBuilder'', ''BlockEntityType'' implements ''FabricBlockEntityType'', so that you can directly use the instance methods in the Fabric API on the vanilla objects.

===== Example Goal =====
The scope of this example is to add the following method into ''<yarn net.minecraft.class_3609>'' to get the sound of the bucket when emptied.
This, normally, is not possible because ''<yarn net.minecraft.class_3609>'' does not have a similar method.

<yarncode java [enable_line_numbers="false"]>
Optional<class_3414> getBucketEmptySound$myMod()
</yarncode>

===== Step 1: Create the Interface =====

To add the method into the class, first of all you need to create an interface with it:

<yarncode java [enable_line_numbers="false"]>
package net.fabricmc.example;

public interface BucketEmptySoundGetter {
	default Optional<class_3414> getBucketEmptySound$myMod() {
		return Optional.empty();
	}
}
</yarncode>

:!: Even if the method body in the interface isn't supposed to be used because it will be overridden by the mixin class, you must still generally specify the method body, which means the method must be ''default''. You can make it return null or throw ''UnsupportedOperationException'', but you //cannot// make it abstract, such as ''Optional<yarn class_3414> getBucketEmptySound()'', or exceptions will be thrown when compiling!

===== Step 2: Implement the Interface with a Mixin =====

The class tweaker step below on its own will be enough if you only want to implement the interface (for example, for marker interfaces, or where you have the whole implementation in default methods). However, you need to implement this interface on a mixin to ''<yarn net.minecraft.class_3609>'' if you want to implement any methods without providing the implementation in a default method:

<yarncode java [enable_line_numbers="false"]>
@Mixin(class_3609.class)
abstract class MixinFlowableFluid implements BucketEmptySoundGetter {
	@Override
	public Optional<class_3414> getBucketEmptySound$myMod() {
	    //This is how to get the default sound, copied from BucketItem class.
	    return Optional.of(((class_3609) (Object) this).method_15791(class_3486.field_15518) ? class_3417.field_15010 : class_3417.field_14834);
	}
}
</yarncode>

ℹ️ If implementing the method with an interface, it's highly recommended to add a dollar-character or underscore character with the mod name as the prefix or suffix of the method name, in order to avoid method name conflict with other mods.

===== Step 3: Inject the Interface in the class tweaker =====

Lastly you need to inject the interface into ''<yarn net.minecraft.class_3609>''.
The following snippet can be added to your class tweaker file to add one or more interfaces to the ''<yarn net.minecraft.class_3609>'' class.
Follow the [[tutorial:accesswidening|access widening tutorial]] for how to create a class tweaker.
Note that all class names here must use the "internal names" that use slashes instead of dots (''path/to/my/Class'').

<code - mymod.classtweaker [enable_line_numbers="false"]>
classTweaker v1 named

inject-interface net/minecraft/fluid/FlowableFluid net/fabricmc/example/BucketEmptySoundGetter
</code>

ℹ️ To make your interface injection visible to other mods depending on your mod (if you are writing a library mod), use ''transitive-inject-interface'' instead of ''inject-interface''.

==== Generic interfaces ====

If your interface has generics, you can specify them when you add the injected interface. For this, you need to add ''<>'' angled brackets and write the generics in Java bytecode signature format between them.

^ Description                                   ^ Java example                 ^ Syntax                                                                                                                                                                         ^ Signature format example       ^
| Class type                                    | ''java.lang.String''         | ''L'' + internal name + '';''                                                                                                                                                  | ''Ljava/lang/String;''         |
| Array type                                    | ''java.lang.String[]''       | ''['' + element type                                                                                                                                                           | ''[Ljava/lang/String;''        |
| Primitive type (may appear as array elements) | ''double''                   | A single capital letter representing the type. Mostly logical, such as ''int'' = ''I'', ''double'' = ''D'', with the 2 exceptions of ''boolean'' = ''Z'' and ''long'' = ''J''. | ''D''                          |
| Type variable                                 | ''T''                        | ''T'' + name + '';''                                                                                                                                                           | ''TT;''                        |
| Generic class type                            | ''java.util.List<T>''        | ''L'' + internal name + ''<'' + generics + ''>;''                                                                                                                              | ''Ljava/util/List<TT;>;''      |
| Wildcard                                      | ''?'', ''java.util.List<?>'' | The ''*'' character                                                                                                                                                            | ''*'', ''Ljava/util/List<*>;'' |
| Extends wildcard bound                        | ''? extends String''         | ''+'' + the bound                                                                                                                                                              | ''+Ljava/lang/String;''        |
| Super wildcard bound                          | ''? super String''           | ''-'' + the bound                                                                                                                                                              | ''-Ljava/lang/String;''        |

Here is a full example using generics:
<code - mymod.classtweaker [enable_line_numbers="false"]>
classTweaker v1 named

inject-interface net/minecraft/fluid/FlowableFluid net/fabricmc/example/MyGenericInterface<+TT;TU;>
</code>
which would generate the implementation:
<yarncode java [enable_line_numbers="false"]>
public class class_3609 implements MyGenericInterface<? extends T, U> {
   // ...
}
</yarncode>

===== Step 4: Using the Injected Method =====

Now you can use the new method:

<yarncode java [enable_line_numbers="false"]>
Optional<class_3414> sound = mytestfluid.getBucketEmptySound$myMod();
</yarncode>


You could also override this method in classes extending ''<yarn class_3609>'' to implement custom behaviours.