Annotation Type MethodHook
-
@Retention(RUNTIME) @Target(METHOD) @Repeatable(MethodHooks.class) @Documented public @interface MethodHook
Registers the annotated method as a hook that should run before, instead or after the method specified by the annotation parameters.Depending on
type()
this method will be called after, instead or before every call to the target method and has access to its parameters and return value. The target method is specified bytargetClassName()
andtargetMethod()
. In case of an overloaded method,targetMethodDescriptor()
can be used to restrict the application of the hook to a particular overload.The signature of the annotated method must be as follows (this does not restrict the method name and parameter names, which are arbitrary), depending on the value of
type()
:HookType.BEFORE
-
Arguments:public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId)
method
: AMethodHandle
representing the original method. The original method can be invoked viaMethodHandle.invokeWithArguments(Object...)
. This requires passingthisObject
as the first argument if the method is not static. This argument can benull
.thisObject
: AnObject
containing the implicitthis
argument to the original method. If the original method is static, this argument will benull
.arguments
: An array ofObject
s containing the arguments passed to the original method. Primitive types (e.g.boolean
) will be wrapped into their corresponding wrapper type (e.g.Boolean
).hookId
: A randomint
identifying the particular call site.This can be used to derive additional coverage information.
HookType.REPLACE
-
The return type may alternatively be taken to be the exact return type of target method or a wrapper type thereof. The returned object will be casted and unwrapped automatically.public static Object hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId)
Arguments:
method
: AMethodHandle
representing the original method. The original method can be invoked viaMethodHandle.invokeWithArguments(Object...)
. This requires passingthisObject
as the first argument if the method is not static. This argument can benull
.thisObject
: AnObject
containing the implicitthis
argument to the original method. If the original method is static, this argument will benull
.arguments
: An array ofObject
s containing the arguments passed to the original method. Primitive types (e.g.boolean
) will be wrapped into their corresponding wrapper type (e.g.Boolean
).hookId
: A randomint
identifying the particular call site.This can be used to derive additional coverage information.
Return value: the value that should take the role of the value the target method would have returned
HookType.AFTER
-
Arguments:public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId, Object returnValue)
method
: AMethodHandle
representing the original method. The original method can be invoked viaMethodHandle.invokeWithArguments(Object...)
. This requires passingthisObject
as the first argument if the method is not static. This argument can benull
.thisObject
: AnObject
containing the implicitthis
argument to the original method. If the original method is static, this argument will benull
.arguments
: An array ofObject
s containing the arguments passed to the original method. Primitive types (e.g.boolean
) will be wrapped into their corresponding wrapper type (e.g.Boolean
).hookId
: A randomint
identifying the particular call site.This can be used to derive additional coverage information.returnValue
: AnObject
containing the return value of the invocation of the original method. Primitive types (e.g.boolean
) will be wrapped into their corresponding wrapper type (e.g.Boolean
). If the original method has return typevoid
, this value will benull
.Multiple
HookType.BEFORE
andHookType.AFTER
hooks are allowed to reference the same target method. Exclusively oneHookType.REPLACE
hook may reference a target method, no other types allowed. Attention must be paid to not guide the Fuzzer in different directions viaJazzer
'sguideTowardsXY
methods in the different hooks.
-
-
Required Element Summary
Required Elements Modifier and Type Required Element Description String
targetClassName
The name of the class that contains the method that should be hooked, as returned byClass.getName()
.String
targetMethod
The name of the method to be hooked.HookType
type
The time at which the annotated method should be called.
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description String[]
additionalClassesToHook
Array of additional classes to hook.String
targetMethodDescriptor
The descriptor of the method to be hooked.
-
-
-
Element Detail
-
type
HookType type
The time at which the annotated method should be called.If this is
HookType.BEFORE
, the annotated method will be called before the target method and has access to its arguments.If this is
HookType.REPLACE
, the annotated method will be called instead of the target method. It has access to its arguments and can return a value that will replace the target method's return value.If this is
HookType.AFTER
, the annotated method will be called after the target method and has access to its arguments and return value.- Returns:
- when the hook should be called
-
-
-
targetClassName
String targetClassName
The name of the class that contains the method that should be hooked, as returned byClass.getName()
.If an interface or abstract class is specified, also calls to all implementations and subclasses available on the classpath during startup are hooked, respectively. Interfaces and subclasses are not taken into account for concrete classes.
Examples:
String
:"java.lang.String"
FileSystem
:"java.nio.file.FileSystem"
- Returns:
- the name of the class containing the method to be hooked
-
-
-
targetMethod
String targetMethod
The name of the method to be hooked. Use"<init>"
for constructors.Examples:
String.equals(Object)
:"equals"
String()
:"<init>"
- Returns:
- the name of the method to be hooked
-
-
-
targetMethodDescriptor
String targetMethodDescriptor
The descriptor of the method to be hooked. This is only needed if there are multiple methods with the same name and not all of them should be hooked.The descriptor of a method is an internal representation of the method's signature, which includes the types of its parameters and its return value. For more information on descriptors, see the JVM Specification, Section 4.3.3 and
MethodType.toMethodDescriptorString()
- Returns:
- the descriptor of the method to be hooked
- Default:
- ""
-
-
-
additionalClassesToHook
String[] additionalClassesToHook
Array of additional classes to hook.Hooks are applied on call sites. This means that classes calling the one defined in this annotation need to be instrumented to actually execute the hook. This property can be used to hook normally ignored classes.
- Returns:
- fully qualified class names to hook
- Default:
- {}
-
-