net.lenni0451.classtransform.annotations.injection

Annotation Type CInject

@Retention(value=CLASS)
 @Target(value={METHOD,CONSTRUCTOR})
public @interface CInject

Inject into a method at various targets.
The original code flow can be cancelled and own values can be returned.
The transformer method has to return void and can have the following arguments:

• The arguments of the target method
• A InjectionCallback for cancelling the original method and returning values

If the target method is static the transformer method has to be static as well.
The arguments have to be in the same order as the target method but are not required. You can skip the original method arguments or the callback if you don't need them. When injecting into multiple methods the arguments have to be the same for all of them (or skipped).
The argument types have to match the target method arguments. Object types can be replaced with Object instead of the actual type (useful if classes are not accessible).
The arguments in the target method can not be directly changed. If you want to change them you need to use CLocalVariable.

Cancelling the target method is only possible if cancellable() is set to true. Not doing so will throw an exception when calling InjectionCallback.setCancelled(boolean). If the target method has a return value you have to use InjectionCallback.setReturnValue(Object) to change it. Calling this method will also call InjectionCallback.setCancelled(boolean) with true internally.

When injecting at the targets RETURN, TAIL and THROW the callback will contain the return value or the thrown exception. It can be accessed by calling InjectionCallback.getReturnValue() or InjectionCallback.castReturnValue(). The return value can be changed but skipping the return/throw is not possible.

Injecting at the top of a method:

 @CInject(method = "print(Ljava/lang/String;)V", target = @CTarget("HEAD"))
 public void injectHead(String text, InjectionCallback callback) {
     //Do something at the top of the method
 }
 

Injecting above a method call:

 @CInject(method = "print", target = @CTarget(value = "INVOKE", target = "...", shift = CTarget.Shift.BEFORE))
 public void injectBefore(String text, InjectionCallback callback) {
     //Do something before the method call
 }
 

See CTarget for more information about targets.
If your target has to be chosen more precisely you can use a slice() to narrow down the search.

See Also:

CTarget, CSlice, GitHub Wiki

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.String[]	method The method name and descriptor to inject into. This supports multiple targets and wildcards. e.g.
CTarget[]	target The targets for the injection. This can be used to inject at multiple locations at once.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	cancellable Allow the target method to be cancelled. This is also required to change the return value. If this is set to false an exception will be thrown when trying to cancel the target method. Cancelling the method is only possible using the InjectionCallback.
CSlice	slice The slice to narrow down the search for the target.

Element Detail

method

public abstract java.lang.String[] method

The method name and descriptor to inject into.
This supports multiple targets and wildcards.
e.g. print(Ljava/lang/String;)V or print*

Returns:

The method name and descriptor

target

public abstract CTarget[] target

The targets for the injection.
This can be used to inject at multiple locations at once.

Returns:

The targets

slice

public abstract CSlice slice

The slice to narrow down the search for the target.

Returns:

The slice

Default:

@net.lenni0451.classtransform.annotations.CSlice

cancellable

public abstract boolean cancellable

Allow the target method to be cancelled.
This is also required to change the return value.
If this is set to false an exception will be thrown when trying to cancel the target method.
Cancelling the method is only possible using the InjectionCallback.

Returns:

If the original method can be cancelled

Default:

false