Debugging, Tracing, and Stack Management Operations in the Rule Engine

Tracking and Debugging Operations

1. Debug

The rule engine provides a simple built‑in debug method to conditionally display messages during rule execution. The helper class defines the following API:

public boolean debug(String message)

debug : prints the provided message to System.out prefixed with the executing rule name, always returns true , allowing the debug call to be combined with other boolean expressions using AND .

Debug messages can be enabled by setting the JVM system property:

-Dorg.jboss.byteman.debug=true

2. Trace

The rule engine offers a set of built‑in methods to record trace messages during execution. Messages can be written to System.out , System.err , or a specified file. The helper class defines the following API:

public boolean traceOpen(Object identifier, String filename)
public boolean traceOpen(Object identifier)
public boolean traceClose(Object identifier)
public boolean trace(Object identifier, String message)
public boolean traceln(Object identifier, String message)
public boolean trace(String message)
public boolean traceln(String message)

traceOpen : opens a file specified by filename , associates it with identifier , and returns true . If the file already exists for the identifier, returns false ; otherwise opens in append mode or generates a unique name if no filename is given.

traceClose : closes and disassociates the file linked to identifier , returning true or false if no file is found.

trace : writes the message to the file associated with identifier (creating one if necessary) and returns true .

traceln : same as trace but appends a newline.

If identifier is omitted or null , the message goes to System.out ; if it is the string "err" , the message goes to System.err .

Special Cases :

When identifier is null or "out" , trace and traceln output to System.out ; when it is "err" , they output to System.err . In these cases, traceOpen and traceClose always return false .

Stack Management Operations

1. Check Call Stack

The rule engine provides methods to examine the call stack when a rule fires. The helper class defines the following API:

public boolean callerEquals(String name)
public boolean callerEquals(String name, int frameCount)
public boolean callerEquals(String name, int startFrame, int frameCount)
public boolean callerEquals(String name, boolean includeClass)
public boolean callerEquals(String name, boolean includeClass, int frameCount)
public boolean callerEquals(String name, boolean includeClass, int startFrame, int frameCount)
public boolean callerEquals(String name, boolean includeClass, boolean includePackage)
public boolean callerEquals(String name, boolean includeClass, boolean includePackage, int frameCount)
public boolean callerEquals(String name, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
public boolean callerMatches(String regExp)
public boolean callerMatches(String regExp, int frameCount)
public boolean callerMatches(String regExp, int startFrame, int frameCount)
public boolean callerMatches(String regExp, boolean includeClass)
public boolean callerMatches(String regExp, boolean includeClass, int frameCount)
public boolean callerMatches(String regExp, boolean includeClass, int startFrame, int frameCount)
public boolean callerMatches(String regExp, boolean includeClass, boolean includePackage)
public boolean callerMatches(String regExp, boolean includeClass, boolean includePackage, int frameCount)
public boolean callerCheck(String match, boolean isRegExp, boolean includeClass, boolean includePackage, int startFrame, int frameCount)

callerCheck : checks frameCount frames starting at startFrame ; returns true if any frame matches the given criteria.

startFrame defaults to 1 (the caller of the triggering method); frameCount defaults to 1 (only the immediate caller).

includeClass and includePackage control whether class or package qualifiers are considered.

isRegExp determines whether the match string is treated as a regular expression.

2. Trace Call Stack

Methods to record or format a string representation of the call stack are provided:

public void traceStack()
public void traceStack(String prefix)
public void traceStack(String prefix, Object key)
public void traceStack(int maxFrames)
public void traceStack(String prefix, int maxFrames)
public void traceStack(String prefix, Object key, int maxFrames)
public String formatStack()
public String formatStack(String prefix)
public String formatStack(int maxFrames)
public String formatStack(String prefix, int maxFrames)

formatStack : generates a string representation of the call stack, including fully‑qualified method names, file names, and line numbers.

traceStack : writes the formatted stack string to the trace file.

Regular‑expression filtering of stack frames is supported via:

public void traceStackMatching(String regExp)
public void traceStackMatching(String regExp, String prefix)
public void traceStackMatching(String regExp, boolean includeClass, ...)
public String formatStackMatching(String regExp, boolean includeClass, ...)

3. Trace Thread Call Stack

The engine can record the call stack of a specific thread or all threads:

public void traceThreadStack(String threadName, ...)
public void traceAllStacks(String prefix, ...)

Default Helper Lifecycle Methods

The default helper provides four lifecycle methods that emit debug messages to System.out , for example:

Default helper activated
Installed rule using default helper : my test rule
Uninstalled rule using default helper : my test rule
Default helper deactivated

These methods allow developers to manage and debug rule execution effectively, ensuring correctness and efficiency.