Byteman Rule State Management: LinkMaps, CountDowns, Flags, Counters, Timers, and Recursive Triggering

The article focuses on Byteman rule state management operations, providing detailed explanations and API definitions for each helper class.

1. LinkMaps

LinkMaps record information when a rule fires and can be retrieved by other rules or after test execution. Internally a LinkMap is a named Map that associates one Object with another. The helper API includes methods such as createLinkMap , deleteLinkMap , link , linked , unlink , linkNames , linkValues , and clearLinks . Versions without the mapName parameter operate on a predefined global map named "default". Multiple maps can be created, often using the current thread as the map name to avoid cross‑thread interference.

boolean createLinkMap(Object mapName)
boolean deleteLinkMap(Object mapName)
Object link(Object mapName, Object name, Object value)
Object linked(Object mapName, Object name)
Object unlink(Object mapName, Object name)
List<Object> linkNames(Object mapName)
List<Object> linkValues(Object mapName)
boolean clearLinks(Object mapName)
Object link(Object name, Object value)
Object linked(Object name)
Object unlink(Object name)
List<Object> linkNames()
List<Object> linkValues()
boolean clearLinks()

2. CountDowns

CountDowns ensure that a rule only fires after a certain number of triggers or after other rules have executed. They are identified by any object and share a common API:

public boolean createCountDown(Object identifier, int count)
public boolean getCountDown(Object identifier)
public boolean countDown(Object identifier)

The createCountDown method creates a countdown with a specified count (values less than 1 are treated as 1). getCountDown tests for existence, returning true if a countdown is present. countDown decrements the counter; it returns false on successful decrement and true when the counter reaches zero, at which point the association is removed.

3. Flags

Flags provide a simple global boolean mechanism. The API consists of:

public boolean flag(Object identifier)
public boolean flagged(Object identifier)
public boolean clear(Object identifier)

flag sets the flag and returns true if it was previously cleared. flagged checks the flag state. clear resets the flag, returning true if it was previously set.

4. Counters

Counters maintain a global integer value that can be incremented, decremented, read, created, or deleted. The helper API includes:

public boolean createCounter(Object o)
public boolean createCounter(Object o, int count)
public boolean deleteCounter(Object o)
public int incrementCounter(Object o, int amount)
public int incrementCounter(Object o)
public int decrementCounter(Object o)
public int readCounter(Object o)
public int readCounter(Object o, boolean zero)

Counters are identified by any object. Creation without an explicit count defaults to zero. Increment and decrement operations return the new counter value.

5. Timers

Timers measure elapsed time between rule executions. The API provides methods to create, read, reset, and delete timers:

public boolean createTimer(Object o)
public long getElapsedTimeFromTimer(Object o)
public long resetTimer(Object o)
public boolean deleteTimer(Object o)

All timer methods operate on a timer identified by an arbitrary object.

6. Recursive Triggering

When a rule's Java code invokes helper methods that match Byteman rules, recursive triggering can occur, potentially leading to infinite loops. The article shows an example rule that triggers endlessly and demonstrates two solutions: adding a condition that filters out trace files, or disabling triggering programmatically using setTriggering(boolean enabled) . The setTriggering method returns true and can be combined with IF or BIND clauses to temporarily suspend rule execution.

public boolean setTriggering(boolean enabled)

This mechanism allows fine‑grained control over rule execution without needing complex conditional logic.