Annotation Interface Advice.OnMethodEnter

Enclosing class:
Advice

@Documented @Retention(RUNTIME) @Target(METHOD) public static @interface Advice.OnMethodEnter

Indicates that this method should be inlined before the matched method is invoked. Any class must declare at most one method with this annotation. The annotated method must be static. When instrumenting constructors, the this values can only be accessed for writing fields but not for reading fields or invoking methods.

The annotated method can return a value that is made accessible to another method annotated by Advice.OnMethodExit.

See Also:
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    Determines if the annotated method should be inlined into the instrumented method or invoked from it.
    boolean
    If set to true, the instrumented method's line number information is adjusted such that stack traces generated within this advice method appear as if they were generated within the first line of the instrumented method.
    Determines if the execution of the instrumented method should be skipped.
    int
    Indicates that the value to be used for skipOn() should be read from an array that is returned by the advice method, if the assigned property is non-negative.
    Class<? extends Throwable>
    Indicates that this advice should suppress any Throwable type being thrown during the advice's execution.
  • Element Details

    • skipOn

      Class<?> skipOn

      Determines if the execution of the instrumented method should be skipped. This does not include any exit advice.

      When specifying a non-primitive type, this method's return value that is subject to an instanceof check where the instrumented method is only executed, if the returned instance is not an instance of the specified class. Alternatively, it is possible to specify either Advice.OnDefaultValue or Advice.OnNonDefaultValue where the instrumented method is only executed if the advice method returns a default or non-default value of the advice method's return type. It is illegal to specify a primitive type as an argument whereas setting the value to void indicates that the instrumented method should never be skipped.

      Important: Constructors cannot be skipped.

      Returns:
      A value defining what return values of the advice method indicate that the instrumented method should be skipped or void if the instrumented method should never be skipped.
      Default:
      void.class
    • skipOnIndex

      int skipOnIndex
      Indicates that the value to be used for skipOn() should be read from an array that is returned by the advice method, if the assigned property is non-negative. If the returned array is shorter than the supplied index, an ArrayIndexOutOfBoundsException will be thrown, even if suppression is used.
      Returns:
      The array index for the value to be considered for skipping a method, or a negative value for using the returned value.
      Default:
      -1
    • prependLineNumber

      boolean prependLineNumber
      If set to true, the instrumented method's line number information is adjusted such that stack traces generated within this advice method appear as if they were generated within the first line of the instrumented method. If set to false, no line number information is made available for such stack traces.
      Returns:
      true if this advice code should appear as if it was added within the first line of the instrumented method.
      Default:
      true
    • inline

      boolean inline
      Determines if the annotated method should be inlined into the instrumented method or invoked from it. When a method is inlined, its byte code is copied into the body of the target method. this makes it is possible to execute code with the visibility privileges of the instrumented method while loosing the privileges of the declared method methods. When a method is not inlined, it is invoked similarly to a common Java method call. Note that it is not possible to set breakpoints within a method when it is inlined as no debugging information is copied from the advice method into the instrumented method.
      Returns:
      true if the annotated method should be inlined into the instrumented method.
      Default:
      true
    • suppress

      Class<? extends Throwable> suppress
      Indicates that this advice should suppress any Throwable type being thrown during the advice's execution. By default, any such exception is silently suppressed. Custom behavior can be configured by using Advice.withExceptionHandler(StackManipulation).
      Returns:
      The type of Throwable to suppress.
      See Also:
      Default:
      net.bytebuddy.asm.Advice.NoExceptionHandler.class