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.
The callback can have any number of parameters, including zero.
Each of the parameters must be annotated with one of the following annotations:
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
}