Callback method parameter annotation @Param

Callback parameter annotated with @Param(<number>) provides the value of the instrumented method parameter with given number. Parameters are numbered starting with 1.

In which callbacks can be used

Parameter annotated with @Param(<number>) can be used in any callback.

If the callback parameter is used in onReturn(), onUncaughtException() or onUncaughtExceptionExt() the original value of the instrumented method parameter variable will be provided, even if the parameter variable was modified inside the instrumented method body.

However, note that parameter of a reference type can refer an object which state is modified inside the instrumented method body. In this case, if you need the original state, access the parameter in onEnter().

The following code snippet illustrates the rules:

// Class being instrumented
class Foo {
  void bar(StringBuffer buffer, Object obj, int number) {
    buffer.append("some string"); // change object state
    obj = null; // modify parameter variable
    ++number; // modify parameter variable
  }
}

//...

// Probe class which instruments Foo.bar()
@MethodPattern("Foo:bar(java.lang.StringBuffer, Object, int)")
public class MyProbe {
  public static void onEnter(
    @Param(1) StringBuffer buffer
    @Param(2) Object obj,
    @Param(3) int number
  ) {
    System.out.println(buffer.toString()); // will print original 'buffer' content
    System.out.println(obj); // will print original 'obj'
    System.out.println(number); // will print original 'number'
  }

  public static void onExit(
    @Param(1) StringBuffer buffer
    @Param(2) Object obj,
    @Param(3) int number
  ) {
    System.out.println(buffer.toString()); // will print modified 'buffer' content
    System.out.println(obj); // will print original 'obj' (not null)
    System.out.println(number); // will print original 'number'
  }
}

Parameter count mismatch

If parameter number in @Param(<number>) is bigger than the actual number of method parameters, it will be assigned with null, if declared as a reference type, or with 0, if declared as primitive type.

Declaration type

Parameter annotated with @Param(<number>) can be declared as a reference type or as a primitive type.

If the callback parameter is declared as java.lang.Object, it will be assigned with object reference as is if the actual parameter type is a reference type, or with a boxed value if the actual parameter type is primitive.

If the callback parameter is declared as some reference type other than java.lang.Object, it will be assigned with the actual method parameter value only if it is declared as strictly the same type. Otherwise the callback parameter value will be null.

If the callback parameter is declared as a primitive type, it will be assigned with the actual method parameter value only if it is declared as strictly the same type. Otherwise it will be assigned with 0; no type conversions will be performed. For example, int will not be cast to long.

Type of callback parameter annotated with @Param	Actual instrumented method parameter type	Resulting value of the callback parameter
java.lang.Object	any reference type	the value as is
	any primitive type	a boxed value
some reference type T1 other than java.lang.Object	same reference type T1	the value as is
	any reference or primitive type T2 != T1	null
some primitive type T1	same primitive type T1	the value as is
	any reference or primitive type T2 != T1	0

Note: The type matching rules for @Param are similar to ones for @ReturnValue and differ from the rules for @This