Class Advice.AssignReturned

java.lang.Object
net.bytebuddy.asm.Advice.AssignReturned
All Implemented Interfaces:
Advice.PostProcessor
Direct Known Subclasses:
Advice.AssignReturned.ForArray, Advice.AssignReturned.ForScalar
Enclosing class:
Advice

@Enhance public abstract static class Advice.AssignReturned extends Object implements Advice.PostProcessor

A post processor that uses the return value of an advice method to define values for fields, arguments, the instrumented method's return value or the exception being thrown. This post processor allows for the assignment of values from advice methods that use delegation. When inlining advice code, it is recommended to assign values directly to annotated parameters.

Assignments can either be performed by returning a single value from an advice method or by returning an array with multiple values. If the return type of an advice method is declared as an array type, the latter is assumed what can be overridden by annotating the advice method with Advice.AssignReturned.AsScalar. With a scalar assignment, the return type's default value is considered as an indication to skip any assignment what can be configured via the annotation's property. When returning null when using an array-typed assignment, the assignment will always be skipped.

Important: This post processor is not registered by default but requires explicit registration via Advice.WithCustomMapping.with(Advice.PostProcessor.Factory).

Important: Assignment exceptions will not be handled by a suppression handler but will be propagated.

  • Field Details

    • NO_INDEX

      public static final int NO_INDEX
      Indicates that a value is not assigned from an array but as a scalar value.
      See Also:
    • typeDescription

      protected final TypeDescription typeDescription
      The advice method's return type.
    • exceptionHandlerFactory

      protected final Advice.AssignReturned.ExceptionHandler.Factory exceptionHandlerFactory
      The exception handler factory to use.
    • exit

      protected final boolean exit
      true if this post processor is used within exit advice.
    • skipOnDefaultValue

      protected final boolean skipOnDefaultValue
      true if a default value indicates that no assignment should be conducted.
  • Constructor Details

    • AssignReturned

      protected AssignReturned(TypeDescription typeDescription, Advice.AssignReturned.ExceptionHandler.Factory exceptionHandlerFactory, boolean exit, boolean skipOnDefaultValue)
      Creates a new post processor for assigning an advice method's return value.
      Parameters:
      typeDescription - The advice method's return type.
      exceptionHandlerFactory - The exception handler factory to use.
      exit - true if this post processor is used within exit advice.
      skipOnDefaultValue - true if a default value indicates that no assignment should be conducted.
  • Method Details

    • resolve

      public StackManipulation resolve(TypeDescription instrumentedType, MethodDescription instrumentedMethod, Assigner assigner, Advice.ArgumentHandler argumentHandler, Advice.StackMapFrameHandler.ForPostProcessor stackMapFrameHandler, StackManipulation exceptionHandler)
      Resolves this post processor for a given instrumented method.
      Specified by:
      resolve in interface Advice.PostProcessor
      Parameters:
      instrumentedType - The instrumented type.
      instrumentedMethod - The instrumented method.
      assigner - The assigner to use.
      argumentHandler - The argument handler to use.
      stackMapFrameHandler - The argument handler for the instrumented method.
      exceptionHandler - The exception handler that is resolved for the instrumented method.
      Returns:
      The stack manipulation to apply.
    • getType

      protected abstract TypeDescription getType()
      Returns the assigned type that is handled by any handler.
      Returns:
      The handled type.
    • getHandlers

      protected abstract Collection<Advice.AssignReturned.Handler> getHandlers()
      Returns a collection of all handlers to apply.
      Returns:
      The handlers to apply.
    • toLoadInstruction

      protected abstract StackManipulation toLoadInstruction(Advice.AssignReturned.Handler handler, int offset)
      Creates a load instruction for the given handler.
      Parameters:
      handler - The handler for which to apply a load instruction.
      offset - The offset of the value that is returned by the advice method.
      Returns:
      A stack manipulation to load the handled value.