Annotation Type MethodHook


  • @Retention(RUNTIME)
    @Target(METHOD)
    @Repeatable(MethodHooks.class)
    @Documented
    public @interface MethodHook
    Registers this method as a hook that should run after the method specified by the annotation parameters has returned.

    This method will be called after every call to the target method and has access to its return value. The target method is specified by targetClassName() and targetMethod(). 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
    
     public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId)
     
    Arguments:

    • method: A MethodHandle representing the original method. The original method can be invoked via MethodHandle.invokeWithArguments(Object...). This requires passing thisObject as the first argument if the method is not static. This argument can be null.
    • thisObject: An Object containing the implicit this argument to the original method. If the original method is static, this argument will be null.
    • arguments: An array of Objects 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 random int identifying the particular call site.This can be used to derive additional coverage information.
    HookType.REPLACE
    
     public static Object hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId)
     
    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.

    Arguments:

    • method: A MethodHandle representing the original method. The original method can be invoked via MethodHandle.invokeWithArguments(Object...). This requires passing thisObject as the first argument if the method is not static. This argument can be null.
    • thisObject: An Object containing the implicit this argument to the original method. If the original method is static, this argument will be null.
    • arguments: An array of Objects 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 random int 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
    
     public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId,
     Object returnValue)
     
    Arguments:

    • method: A MethodHandle representing the original method. The original method can be invoked via MethodHandle.invokeWithArguments(Object...). This requires passing thisObject as the first argument if the method is not static. This argument can be null.
    • thisObject: An Object containing the implicit this argument to the original method. If the original method is static, this argument will be null.
    • arguments: An array of Objects 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 random int identifying the particular call site.This can be used to derive additional coverage information.
    • returnValue: An Object 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 type void, this value will be null.
    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      java.lang.String targetClassName
      The name of the class that contains the method that should be hooked, as returned by Class.getName().
      java.lang.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
      java.lang.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

        java.lang.String targetClassName
        The name of the class that contains the method that should be hooked, as returned by Class.getName().

        Examples:

        • String: "java.lang.String"
        • FileSystem: "java.nio.file.FileSystem"

        Returns:
        the name of the class containing the method to be hooked
      • targetMethod

        java.lang.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

        java.lang.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:
        ""