Callback onReturn()

To execute a code when method normally exits (i.e. via return or when a void method body execution completes), define callback method onReturn() in probe class.

Only one method named onReturn() can exist in a probe class. You can omit onReturn() method if it is not needed for your probe.

Parameters

The callback can have any number of parameters, including zero.

Each of the parameters must be annotated with one of the following annotations:

• @Param
• @Params
• @This
• @ClassRef
• @MethodName
• @MethodParameterTypes
• @MethodSignature
• @OnEnterResult
• @ReturnValue

Return type

onReturn() can be void or return a value.

If onReturn() is void, the original return value will be returned.

The following pseudo-code demonstrates how the callback works:

Before instrumentation:

ReturnType foo() {
  bar(); // do something
  return result;
}

After instrumentation with void onReturn():

ReturnType foo() {
  bar(); // do something
  SomeProbeClass.onReturn(...);
  return result;
}

Declare onReturn() as non-void to change the value returned from the instrumented method. If onReturn() is non-void, its return type must be the same as the return type of method to be instrumented. If the types mismatch, the probe will not be applied to the method. If needed, access the original return value with the help of @ReturnValue annotated parameter, and optionally return the original return value or a different value.

The capability to change return value has more to do with debugging than with monitoring or profiling, as it affects application logic. Be very careful: inappropriate use can break the application.

After instrumentation with ReturnType onReturn():

ReturnType foo() {
  bar(); // do something
  return SomeProbeClass.onReturn(...); // return value must be ReturnType
}