// Copyright 2021 Code Intelligence GmbH // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.code_intelligence.jazzer.api; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Repeatable; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import java.lang.invoke.MethodType; /** * 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 * {@link #targetClassName()} and {@link #targetMethod()}. In case of an * overloaded method, {@link #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 {@link #type()}: * *
{@code * public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId) * }* Arguments: *
{@code * 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: *
*
* Return value: the value that should take the role of the value the target * method would have returned * *
{@code * public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId, * Object returnValue) * }* Arguments: *
* If this is {@link HookType#BEFORE}, the annotated method will be called * before the target method and has access to its arguments. *
* If this is {@link 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 {@link HookType#AFTER}, the annotated method will be called * after the target method and has access to its arguments and return * value. * * @return when the hook should be called */ HookType type(); /** * The name of the class that contains the method that should be hooked, * as returned by {@link Class#getName()}. *
* Examples: *
*
* @return the name of the class containing the method to be hooked
*/
String targetClassName();
/**
* The name of the method to be hooked. Use {@code "
* Examples:
*
*
* @return the name of the method to be hooked
*/
String targetMethod();
/**
* 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 {@link MethodType#toMethodDescriptorString()}
*
* @return the descriptor of the method to be hooked
*/
String targetMethodDescriptor() default "";
}
*