Mastering Byteman: How AT LINE, AT READ, and Other Specifiers Control Java Bytecode Injection

AT LINE

The AT LINE specifier places the trigger point just before the first executable bytecode instruction whose source line number is greater than or equal to the line number supplied as a parameter. If no executable code exists at or after the specified line, the rule is not inserted and no error is printed, because the rule simply does not apply to that class or method.

AT READ

The AT READ specifier is followed by a field name and targets the point before the first occurrence of the corresponding getField instruction in bytecode. If a type is provided, the getField matches only when the declaring class of the field matches the given type. An optional count N selects the N‑th matching getField; the keyword ALL triggers on every matching read.

A variant uses a variable name prefixed with $ (local variable, method parameter, or $this) to place the trigger before the corresponding iload, dload, or aload instruction. The same counting rules apply, and ALL triggers on every matching load. The variable name can be used only when the method’s bytecode contains a local variable table (e.g., compiled with the -g flag).

AFTER READ

The AFTER READ specifier behaves like AT READ but positions the trigger after the getField or variable‑load instruction.

AT WRITE / AFTER WRITE

The AT WRITE and AFTER WRITE specifiers mirror the read variants, targeting field or variable assignments. They match the putField instruction for fields or the istore, dstore, etc., for variables. AT WRITE $0 or AT WRITE $this never matches instance method calls because the target object of an instance method is never assigned.

When a local variable is specified (e.g., AT WRITE $localvar or AT WRITE $localvar 1), the trigger corresponds to the point immediately after the variable’s initialization, effectively the same as AFTER WRITE $localvar. This ensures the variable is in scope before the rule body accesses it.

AT INVOKE / AFTER INVOKE

The AT INVOKE and AFTER INVOKE specifiers are analogous to the read/write specifiers but mark the point before or after a method or constructor call inside the target method. The method can be identified by its simple name or a fully qualified descriptor, where the descriptor lists parameter types inside parentheses.

AT NEW / AFTER NEW

The AT NEW and AFTER NEW specifiers identify the location of a new operation that creates a Java object or array. AT NEW triggers before allocation; AFTER NEW triggers after the object or array has been created and initialized.

The NEW specifier can be refined with optional type names, array dimensions (using brackets), an integer count, or the keyword ALL. Type names limit injection to instances of that class (or array type). Brackets restrict matching to arrays of the specified dimensionality (e.g., AT NEW [][] matches any 2‑dimensional array creation). If no type or brackets are supplied, the rule matches any object creation.

AT SYNCHRONIZE / AFTER SYNCHRONIZE

The AT SYNCHRONIZE and AFTER SYNCHRONIZE specifiers target synchronized blocks, corresponding to the MONITORENTER bytecode instruction. AFTER SYNCHRONIZE marks the point immediately after entering the synchronized block, not after exiting it.

AT THROW

The AT THROW specifier marks a throw operation as the trigger point. An optional exception type can narrow the match, and an optional count N selects the N‑th occurrence. The keyword ALL triggers on every matching throw.

AT EXCEPTION EXIT

The AT EXCEPTION EXIT specifier identifies the point where a method returns control to its caller via an unhandled exception. This can occur because the method itself threw the exception or because it called another method that threw it. Rules injected at this point fire when the exception propagates; they may optionally execute RETURN to alter the normal exception flow or THROW to re‑throw a new exception.

When multiple rules target the same location, injection order follows the order of rules in the script, except for AFTER positions where the order is reversed.

Historical synonyms: CALL is equivalent to INVOKE, RETURN to EXIT, and the leading AT in AT LINE is optional.