Callback method parameter annotation @This

Callback parameter annotated with @This will be assigned with a reference to the object whose method is being executed.

Declaration type

Callback parameter annotated with @This should be declared as a reference type, capable to store a reference to the objects whose method(s) the probe is applied to.

To make the probe applicable to any method (even static!), declare the callback parameter as java.lang.Object. If needed, cast the value to appropriate class in the callback body.

If the callback parameter is declared as some reference type T other than java.lang.Object, the probe callbacks will only be called for methods of class T or of a class which extends T or implements T. In particular this means that callback with parameter annotated with @This declared as T != java.lang.Object will never be called for a static method.

In which callbacks can be used

Parameter annotated with @This can be used in any callback.

However, if more than one probe callback has parameters annotated with @This, all of them must be declared as same type.

@MethodPattern("*:findPerson(*)")
public class GoodProbe1 {
  public static void onEnter() {/*....*/} // will only be called to methods of Person (because of onReturn()'s parameter)
  public static void onReturn(@This Person person) {/*...*/} // will only be called to methods of Person
}

@MethodPattern("*:foo(*)")
public class GoodProbe2 {
  public static void onEnter(@This Object _this) {/*....*/} // will be called to any methods matching the pattern
  public static void onReturn(@This Object _this) {/*...*/} // will be called to any methods matching the pattern
}

@MethodPattern("*:bar(*)")
public class BadProbe2 { // the probe is invalid - @This type mismatch
  public static void onEnter(@This Object _this) {/*....*/}
  public static void onUncaughtException(@This String _this) {/*...*/}
}

Special notes on instrumenting a static method

If callback is applied to a static method, parameter annotated with @This will be null.

Special notes on instrumenting a constructor

If probe is applied to a constructor, it may be important to account all activity in super constructors, e.g. to properly measure the constructor execution time or handle nested events should the constructor execution be considered a lasting event.

However, the bytecode verifier forbids access to the object reference before the constructor of its superclass (super(...);) or another constructor of the same class (this(...);) is invoked.

Hence using callback parameter annotated with @This in a probe applied to a constructor affects the point where the call to onEnter() is injected, as well as the scope of exceptions monitored via onUncaughtException() or onUncaughtExceptionExt(). See the table below for detail.

	If @This is used in onEnter(), or onUncaughtException(), or onUncaughtExceptionExt(), or if @This declared as non-java.lang.Object is used in onReturn()	Otherwise
onEnter() injection point	onEnter() will be called right after the call to super(...) or this(...)	onEnter() will be injected at the very start of the constructor, i.e. before the call to super(...) or this(...)
onUncaughtException() or onUncaughtExceptionExt() monitored scope	The scope of monitored exceptions will start right after the call to super(...) or this(...)	The scope of monitored exceptions will be the whole method, i.e. will include the call to super(...) or this(...)

In particular, this means that using @This may not let to monitor what happens inside super(...) or this(...).

If you need both onEnter() and onReturn() and want to avoid this limitation, do not use @This in onEnter(); use it in onReturn() only and declare it as java.lang.Object.