Class Helper

java.lang.Object
org.jboss.byteman.rule.helper.Helper
Direct Known Subclasses:
BytemanTestHelper, InterpretedHelper, JMXHelper, PeriodicHelper, ThreadHistoryMonitorHelper, ThreadMonitorHelper

public class Helper extends Object
This is the default helper class which is used to define builtin operations for rules. Methods provided on this class are automatically made available as builtin operations in expressions appearing in rule event bindings, conditions and actions. Although Helper methods are all instance methods the message recipient for the method call is implicit and does not appear in the builtin call. It does, however, appear in the runtime invocation, giving the builtin operation access to the helper and thence the rule being fired.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static HashMap<Object,CountDown>
    a hash map used to identify countdowns from their identifying objects
    private static HashMap<Object,Counter>
    a hash map used to identify counters from their identifying objects
    private static Set<Object>
    a set used to identify settings for boolean flags associated with arbitrary objects.
    private static HashMap<Object,Joiner>
     
    a hash map used to identify maps from their identifying objects
    private static int
     
    private static HashMap<Object,Rendezvous>
    a hash map used to identify rendezvous from their identifying objects
    protected Rule
     
    private static String
     
    private static String
     
     
    private static HashMap<Object,Timer>
    a hash map used to identify timer from their identifying objects
    private static final ConcurrentMap<Object,PrintStream>
    a hash map used to identify trace streams from their identifying objects Mutating the map requires synchronization on the traceMap; not required for read operations (or use of the stored PrintStream instances) as that is inherently racy.
    private static HashMap<Object,Waiter>
    a hash map used to identify waiters from their identifying objects
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Helper(Rule rule)
     
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
     
    boolean
    addCountDown(Object identifier, int count)
    alias for createCountDown provided for backwards compatibility
    private void
    appendStack(StringBuffer buffer, String prefix, int maxFrames, Thread thread, StackTraceElement[] stack)
     
    boolean
    callerCheck(String match, boolean isRegExp, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression.
    boolean
    test whether the name of the method which called the the trigger method matches the supplied name by calling callerEquals(name, false)
    boolean
    callerEquals(String name, boolean includeClass)
    test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, false)
    boolean
    callerEquals(String name, boolean includeClass, boolean includePackage)
    test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, includePackage, 1)
    boolean
    callerEquals(String name, boolean includeClass, boolean includePackage, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerCheck(name, false, includeClass, includePackage, 1, frameCount)
    boolean
    callerEquals(String name, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerCheck(name, false, includeClass, false, startFrame, frameCount)
    boolean
    callerEquals(String name, boolean includeClass, int frameCount)
    test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, false, frameCount)
    boolean
    callerEquals(String name, boolean includeClass, int startFrame, int frameCount)
    test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, false, startFrame, frameCount)
    boolean
    callerEquals(String name, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerEquals(name, 1, frameCount)
    boolean
    callerEquals(String name, int startFrame, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerEquals(name, false, startFrame, frameCount)
    boolean
    test whether the name of the method which called the the trigger method matches the supplied regular by calling callerMatches(regExp, false)
    boolean
    callerMatches(String regExp, boolean includeClass)
    test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, false)
    boolean
    callerMatches(String regExp, boolean includeClass, boolean includePackage)
    test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, includePackage, 1)
    boolean
    callerMatches(String regExp, boolean includeClass, boolean includePackage, int frameCount)
    test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, includePackage, 1, frameCount)
    boolean
    callerMatches(String regExp, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression by calling callerCheck(regExp, true, includeClass, includePackage, 1, frameCount)
    boolean
    callerMatches(String regExp, boolean includeClass, int frameCount)
    test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, false, frameCount)
    boolean
    callerMatches(String regExp, boolean includeClass, int startFrame, int frameCount)
    test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, false, startFrame, frameCount)
    boolean
    callerMatches(String regExp, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression by calling callerMatches(regExp, 1, frameCount)
    boolean
    callerMatches(String regExp, int startFrame, int frameCount)
    test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression by calling callerMatches(regExp, false, startFrame, frameCount)
    boolean
    clear(Object identifier)
    clear the flag keyed by the supplied object if it is not already clear
    boolean
    clear all links in the default linkmap by indirectly calling clearLinks("default")
    boolean
    clearLinks(Object mapName)
    clear all current links from the map named by mapName
    private static void
    clean up function called by deactivate to ensure all static resources used to hold rule state are cleared
    boolean
    closeTrace(Object identifier)
    version for backwards compatibility -- docs and original code were mismatched
    boolean
    countDown(Object identifier)
    builtin to decrement the countdown identified by a specific object, uninstalling it and returning true only when the count is zero.
    boolean
    createCountDown(Object identifier, int count)
    builtin to test create a countdown identified by a specific object and with the specified count.
    boolean
    create a counter identified by the given object with count 0 as its initial count
    boolean
    createCounter(Object o, int value)
    create a counter identified by the given object with the supplied value as its iniital count
    boolean
    createJoin(Object key, int max)
     
    boolean
    create a LinkMap used to store links between names and values
    boolean
    createRendezvous(Object identifier, int expected)
    call createRendezvous(Object, int, boolean) supplying false for the last parameter
    boolean
    createRendezvous(Object identifier, int expected, boolean restartable)
    create a rendezvous for a given number of threads to join
    boolean
    create a timer identified by the given object
    static void
     
    boolean
    debug(String text)
    builtin to print a message during rule execution.
    int
    decrement the value of the counter associated with given identifier, creating a new one with count zero if none exists
    void
    delay(long millisecs)
    delay execution of the current thread for a specified number of milliseconds
    boolean
    delete a counter identified by the given object with count 0 as its initial count
    boolean
    delete a LinkMap used to store links between names and values
    boolean
    deleteRendezvous(Object identifier, int expected)
    delete a rendezvous.
    boolean
    delete a timer identified by the given object
    private static boolean
    dotrace(Object identifier, String message)
    write the supplied message to the trace stream identified by identifier, creating a new stream if none exists
    private static boolean
    doTraceClose(Object identifier)
    close the trace output stream identified by identifier flushing any pending output.
    private static void
     
    private static boolean
    dotraceln(Object identifier, String message)
    write the supplied message to the trace stream identified by identifier, creating a new stream if none exists, and append a new line
    private static boolean
    doTraceOpen(Object identifier, String fileName)
    open a trace output stream identified by identifier to a file located in the current working directory using the given file name or a generated name if the supplied name is null
    static boolean
    err(String msg)
    punts to static call dotraceln("err", msg) to print msg to the "err" trace stream
    static void
    Print the stack trace for th to the "err" trace stream
    boolean
    flag(Object identifier)
    set a flag keyed by the supplied object if it is not already set
    boolean
    flagged(Object identifier)
    test the state of the flag keyed by the supplied object
    return all stack traces by calling formatAllStacks(null)
    formatAllStacks(int maxFrames)
    return all stack traces by calling formatAllStacks(null, maxFrames)
    return all stack traces by calling formatAllStacks(prefix, 0)
    formatAllStacks(String prefix, int maxFrames)
    return all stack traces
    return a stack trace by calling formatStack(null)
    formatStack(int maxFrames)
    return a stack trace by calling formatStack(null, maxFrames)
    return a stack trace by calling formatStack(prefix, 0)
    formatStack(String prefix, int maxFrames)
    print a stack trace to the trace stream identified by key
    return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, null)
    formatStackBetween(String from, String to, boolean includeClass)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, false)
    formatStackBetween(String from, String to, boolean includeClass, boolean includePackage)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, includePackage, null)
    formatStackBetween(String from, String to, boolean includeClass, boolean includePackage, String prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackRange(from, to, false, includeClass, includePackage, prefix)
    formatStackBetween(String from, String to, boolean includeClass, String prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, false, prefix)
    formatStackBetween(String from, String to, String prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, false, false, false, prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, null)
    formatStackBetweenMatches(String from, String to, boolean includeClass)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, false)
    formatStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, includePackage, null)
    formatStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage, String prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackRange(from, to, true, includeClass, includePackage, prefix)
    formatStackBetweenMatches(String from, String to, boolean includeClass, String prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, false, prefix)
    return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, false, false, false, prefix)
    return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, null)
    formatStackMatching(String regExp, boolean includeClass)
    return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, false)
    formatStackMatching(String regExp, boolean includeClass, boolean includePackage)
    return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, includePackage, null)
    formatStackMatching(String regExp, boolean includeClass, boolean includePackage, String prefix)
    return a String tracing all stack frames which match pattern.
    formatStackMatching(String regExp, boolean includeClass, String prefix)
    return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, false, prefix)
    return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, false, prefix)
    formatStackRange(String from, String to, boolean isRegExp, boolean includeClass, boolean includePackage, String prefix)
    return a String tracing the stack between the frames which match start and end.
    return stack traces of a specific thread by calling formatThreadStack(threadName, null)
    formatThreadStack(String threadName, int maxFrames)
    return all stack traces by calling formatThreadStack(threadName, null, maxFrames)
    formatThreadStack(String threadName, String prefix)
    return all stack traces by calling formatThreadStack(threadName, prefix, 0)
    formatThreadStack(String threadName, String prefix, int maxFrames)
    return all stack traces
    boolean
    getCountDown(Object identifier)
    for backwards compatibility
    long
    get the elapsed time from the start (or last reset) of timer associated with given identifier, creating a new one if none exists
    long
    provide an estimate of an object's size return -1 if not running in a real agent
    int
    getRendezvous(Object identifier, int expected)
    test whether a rendezvous with a specific expected count is associated with identifier
    protected StackTraceElement[]
    access to the current stack frames
    private Waiter
    getWaiter(Object object, boolean createIfAbsent)
    lookup the waiter object used to target wait and signal requests associated with a specific identifying object
    int
    increment the value of the counter associated with given identifier, creating a new one with count zero if none exists
    int
    incrementCounter(Object o, int amount)
    increment the value of the counter associated with given identifier by the given amount, creating a new one with count zero if none exists
    static void
     
    boolean
    isCountDown(Object identifier)
    builtin to test test if a countdown has been installed
    boolean
    isJoin(Object key, int max)
     
    boolean
    isRendezvous(Object identifier, int expected)
    test whether a rendezvous with a specific expected count is associated with identifier
    boolean
     
    boolean
    joinWait(Object key, int count)
     
    boolean
    joinWait(Object key, int count, long millis)
     
    void
    cause the current JVM to halt immediately, simulating a crash as near as possible.
    void
    killJVM(int exitCode)
    cause the current JVM to halt immediately, simulating a crash as near as possible.
    void
    cause the current thread to throw a runtime exception which will normally cause it to exit.
    link(Object name, Object value)
    add a link to the default LinkMap by calling link("default", name, value)
    link(Object mapName, Object name, Object value)
    atomically add a link from name to value to the LinkMap identified by mapName returning any previously linked Object or null if no link currently exists in the map
    linked(Object name)
    retrieve a link from the default LinkMap by calling linked("default", name)
    linked(Object mapName, Object name)
    retrieve the Object name currently is linked to from the LinkMap named by mapName or null if no link currently exists in the map
    retrieve all keys in the default linkmap by indirectly calling linkNames("default")
    linkNames(Object mapName)
    atomically return a list of all keys for current links in the map named by mapName
    retrieve all values in the default linkmap by indirectly calling linkValues("default")
    linkValues(Object mapName)
    atomically return a list of all values for current links in the map named by mapName
    protected int
    matchIndex(StackTraceElement[] stack, String pattern, boolean isRegExp, boolean includeClass, boolean includePackage, int start, int limit)
    return the index of the first frame at or below index start which matches pattern
    private static int
     
    private static String
    generate a name for an output file to be used to sink the trace stream named by identifier.
    static boolean
    punts to static call dotraceln("nzy", msg) to print msg to the "nzy" trace stream when the noisy log level is enabled
    static void
    Print the stack trace to System.out when the noisy log level is enabled
    boolean
    openTrace(Object identifier)
    version for backwards compatibility -- docs and original code were mismatched
    boolean
    openTrace(Object identifier, String fileName)
    version for backwards compatibility -- docs and original code were mismatched
    static boolean
    out(String msg)
    punts to static call dotraceln("out", msg) to print msg to the "out" trace stream
    static void
    Print the stack trace for th to the "out" trace stream
    protected void
    print the details of stack frame to buffer
    protected void
    print the details of stack frame followed by a newline to buffer by calling printlnFrame(buffer, frame) then buffer.append('\n')
    int
    read the value of the counter associated with given identifier, creating a new one with count zero if none exists
    int
    readCounter(Object o, boolean zero)
    read and optionally reset to zero the value of the counter associated with given identifier, creating a new one with count zero if none exists
    private Waiter
    remove the waiter object used to target wait and signal requests associated with a specific identifying object
    int
    rendezvous(Object identifier)
    meet other threads at a given rendezvous returning only when the expected number have arrived
    int
    rendezvous(Object identifier, long millis)
    meet other threads at a given rendezvous returning either when the expected number have arrived or if a timeout is exceeded
    long
    reset the timer associated with given identifier, creating a new one if none exists
    boolean
    setTriggering(boolean enabled)
    enable or disable recursive triggering of rules by subsequent operations performed during binding, testing or firing of the current rule in the current thread.
    boolean
    signalKill(Object identifier)
    for backwards compatibility
    boolean
    signalKill(Object identifier, boolean mustMeet)
    for backwards compatibility
    boolean
    signalThrow(Object identifier)
    call signalThrow(Object, boolean) defaulting the second argument to false
    boolean
    signalThrow(Object identifier, boolean mustMeet)
    signal an event identified by the suppied object, causing all waiting threads to throw an exception and clearing the event.
    boolean
    signalWake(Object identifier)
    call signalWake(Object, boolean) defaulting the second argument to false
    boolean
    signalWake(Object identifier, boolean mustMeet)
    signal an event identified by the supplied object, causing all waiting threads to resume rule processing and clearing the event.
    return a unique name for the trigger point associated with this rule.
    boolean
    trace(Object identifier, String message)
    punts to static call Helper.dotrace(identifier, message).
    boolean
    trace(String message)
    equivalent to calling trace("out", message).
    void
    print trace of all threads' stacks to System.out by calling traceAllStacks(null)
    void
    traceAllStacks(int maxFrames)
    print trace of all threads' stacks to System.out by calling traceAllStacks(null, maxFrames)
    void
    print trace of all threads' stacks to System.out by calling traceAllStacks(prefix, "out")
    void
    traceAllStacks(String prefix, int maxFrames)
    print trace of all threads' stacks to System.out by calling traceAllStacks(prefix, "out", maxFrames)
    void
    print trace of all threads' stacks to the trace stream identified by key by calling traceAllStacks(prefix, key, 0)
    void
    traceAllStacks(String prefix, Object key, int maxFrames)
    print trace of all threads' stacks to the trace stream identified by key
    boolean
    traceClose(Object identifier)
    builtin to close the trace output stream identified by identifier flushing any pending output.
    boolean
    traceln(Object identifier, String message)
    punts to static call dotraceln(identifier, message).
    boolean
    traceln(String message)
    equivalent to calling traceln("out", message).
    boolean
    traceOpen(Object identifier)
    builtin to open a trace output stream identified by identifier to a file located in the current working directory using a unique generated name.
    boolean
    traceOpen(Object identifier, String fileName)
    builtin to open a trace output stream which is redirected to a file in the current directory if specified.
    void
    print a stack trace to System.out by calling traceStack(null)
    void
    traceStack(int maxFrames)
    print a stack trace to System.out by calling traceStack(null, maxFrames)
    void
    print a stack trace to System.out by calling traceStack(prefix, "out")
    void
    traceStack(String prefix, int maxFrames)
    print a stack trace to System.out by calling traceStack(prefix, "out", maxFrames)
    void
    traceStack(String prefix, Object key)
    print a stack trace to the trace stream identified by key by calling traceStack(prefix, key, 0)
    void
    traceStack(String prefix, Object key, int maxFrames)
    print a stack trace to the trace stream identified by key
    void
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, null)
    void
    traceStackBetween(String from, String to, boolean includeClass)
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, includeClass, false)
    void
    traceStackBetween(String from, String to, boolean includeClass, boolean includePackage)
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, includeClass, includePackage, null)
    void
    traceStackBetween(String from, String to, boolean includeClass, boolean includePackage, String prefix)
    print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetween(from, to, includeClass, includePackage, prefix, "out") should be printed.
    void
    traceStackBetween(String from, String to, boolean includeClass, boolean includePackage, String prefix, Object key)
    print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, false, includeClass, includePackage, prefix, key)
    void
    traceStackBetween(String from, String to, boolean includeClass, String prefix)
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, includeClass, false, prefix)
    void
    traceStackBetween(String from, String to, boolean includeClass, String prefix, Object key)
    print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, includeClass, false, prefix, key)
    void
    traceStackBetween(String from, String to, String prefix)
    print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetween(from, to, prefix, "out")
    void
    traceStackBetween(String from, String to, String prefix, Object key)
    print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, false, prefix, key)
    void
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, null)
    void
    traceStackBetweenMatches(String from, String to, boolean includeClass)
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, includeClass, false)
    void
    traceStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage)
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, includeClass, includePackage, null)
    void
    traceStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage, String prefix)
    print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetweenMatches(from, to, true, includeClass, includePackage, prefix, "out");
    void
    traceStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage, String prefix, Object key)
    print all stack frames between the frames which match start and end preceded by prefix by calling traceStackRange(from, to, true, includeClass, includePackage, prefix, key)
    void
    traceStackBetweenMatches(String from, String to, boolean includeClass, String prefix)
    print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, includeClass, false, prefix)
    void
    traceStackBetweenMatches(String from, String to, boolean includeClass, String prefix, Object key)
    print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, includeClass, false, prefix, key)
    void
    print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetweenMatches(from, to, prefix, "out")
    void
    print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetweenMatches(from, to, false, prefix, key)
    void
    print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, null)
    void
    traceStackMatching(String regExp, boolean includeClass)
    print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, includeClass, false)
    void
    traceStackMatching(String regExp, boolean includeClass, boolean includePackage)
    print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, includeClass, includePackage, null)
    void
    traceStackMatching(String regExp, boolean includeClass, boolean includePackage, String prefix)
    print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, , includePackage, prefix, "out")
    void
    traceStackMatching(String regExp, boolean includeClass, boolean includePackage, String prefix, Object key)
    print all stack frames which match pattern to the trace stream identified by key preceded by prefix.
    void
    traceStackMatching(String regExp, boolean includeClass, String prefix)
    print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, false, prefix)
    void
    traceStackMatching(String regExp, boolean includeClass, String prefix, Object key)
    print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, false, prefix, key)
    void
    traceStackMatching(String regExp, String prefix)
    print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, prefix, "out")
    void
    traceStackMatching(String regExp, String prefix, Object key)
    print all stack frames which match pattern to System.out preceded by prefix by calling
    void
    traceStackRange(String from, String to, boolean isRegExp, boolean includeClass, boolean includePackage, String prefix, Object key)
    print all stack frames between the frames which match start and end to the trace stream identified by key preceded by prefix.
    void
    print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, null)
    void
    traceThreadStack(String threadName, int maxFrames)
    print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, null, maxFrames)
    void
    traceThreadStack(String threadName, String prefix)
    print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, prefix, "out")
    void
    traceThreadStack(String threadName, String prefix, int maxFrames)
    print a stack trace of a specific thread of a specific thread to System.out by calling traceThreadStack(threadName, prefix, "out", maxFrames)
    void
    traceThreadStack(String threadName, String prefix, Object key)
    print a stack trace of a specific thread to the trace stream identified by key by calling traceThreadStack(threadName, prefix, key, 0)
    void
    traceThreadStack(String threadName, String prefix, Object key, int maxFrames)
    print a stack trace to the trace stream identified by key
    protected int
    return the index of the frame in stack for the trigger method below which the rule system was entered or -1 if it cannot be found
    static void
     
    unlink(Object name)
    delete a link from the default LinkMap by calling unlink("default", name)
    unlink(Object mapName, Object name)
    atomically remove any link from name returning the Object it is currently linked to or null if no link currently exists in the map
    static boolean
    punts to static call dotraceln("vrb", msg) to print msg to the "vrb" trace stream when the verbose log level is enabled
    static void
    Print the stack trace for th to System.out when the verbose log level is enabled
    void
    waitFor(Object identifier)
    wait for another thread to signal an event with no timeout.
    void
    waitFor(Object identifier, long millisecs)
    wait for another thread to signal an event with a specific timeout or no timeout if zero is supplied as the second argument.
    boolean
    waiting(Object identifier)
    test if there are threads waiting for an event identified by the supplied object to be signalled

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • rule

      protected Rule rule
    • joinerMap

      private static HashMap<Object,Joiner> joinerMap
    • stack

      private StackTraceElement[] stack
    • RULE_CLASS_NAME

      private static String RULE_CLASS_NAME
    • RULE_EXECUTE_METHOD_NAME

      private static String RULE_EXECUTE_METHOD_NAME
    • nextFileIndex

      private static int nextFileIndex
    • traceMap

      private static final ConcurrentMap<Object,PrintStream> traceMap
      a hash map used to identify trace streams from their identifying objects Mutating the map requires synchronization on the traceMap; not required for read operations (or use of the stored PrintStream instances) as that is inherently racy.
    • flagSet

      private static Set<Object> flagSet
      a set used to identify settings for boolean flags associated with arbitrary objects. if an object is in the set then the flag associated with the object is set (true) otherwise it is clear (false).
    • countDownMap

      private static HashMap<Object,CountDown> countDownMap
      a hash map used to identify countdowns from their identifying objects
    • counterMap

      private static HashMap<Object,Counter> counterMap
      a hash map used to identify counters from their identifying objects
    • waitMap

      private static HashMap<Object,Waiter> waitMap
      a hash map used to identify waiters from their identifying objects
    • rendezvousMap

      private static HashMap<Object,Rendezvous> rendezvousMap
      a hash map used to identify rendezvous from their identifying objects
    • timerMap

      private static HashMap<Object,Timer> timerMap
      a hash map used to identify timer from their identifying objects
    • linkMaps

      private static ConcurrentHashMap<Object,HashMap<Object,Object>> linkMaps
      a hash map used to identify maps from their identifying objects
  • Constructor Details

    • Helper

      protected Helper(Rule rule)
  • Method Details

    • debug

      public boolean debug(String text)
      builtin to print a message during rule execution. n.b. this always returns true which means it can be invoked during condition execution. punts to a static call to Helper.dotraceln("dbg", debugPrefix + text) to do the actual printing to the "dbg" trace stream where debugPrefix is a prefix including the keyword debug and a key based on the rule name which is specific to the injection point for the rule.
      Parameters:
      text - the message to be printed as trace output
      Returns:
      true
    • traceOpen

      public boolean traceOpen(Object identifier)
      builtin to open a trace output stream identified by identifier to a file located in the current working directory using a unique generated name. equivalent to calling traceOpen(identifier, null).
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      Returns:
      true if new file and stream was created, false if a stream identified by identifier already existed or the identifier is null, "out" or "err"
    • traceOpen

      public boolean traceOpen(Object identifier, String fileName)
      builtin to open a trace output stream which is redirected to a file in the current directory if specified. Punts to static call Helper.doTraceOpen(identifier, fileName)
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      fileName - the name of the trace file or null if a name should be generated
      Returns:
      true if the output stream was successfully created. false if a stream identified by identifier already existed or if a file of the same name already exists or the identifier is null, "out" or "err"
    • traceClose

      public boolean traceClose(Object identifier)
      builtin to close the trace output stream identified by identifier flushing any pending output. Punts to static call Helper.doTraceClose(identifier)
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      Returns:
      true if the stream was flushed and closed, false if no stream is identified by identifier or identifer is null, "out" or "err"
    • trace

      public boolean trace(String message)
      equivalent to calling trace("out", message).
      Parameters:
      message - the message to be printed in the output stream
      Returns:
      true
    • trace

      public boolean trace(Object identifier, String message)
      punts to static call Helper.dotrace(identifier, message).
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      message - the message to be printed
      Returns:
      true
    • traceln

      public boolean traceln(String message)
      equivalent to calling traceln("out", message).
      Parameters:
      message - the message to be traced
      Returns:
      true
    • traceln

      public boolean traceln(Object identifier, String message)
      punts to static call dotraceln(identifier, message).
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      message - the message to be traced
      Returns:
      true
    • openTrace

      public boolean openTrace(Object identifier)
      version for backwards compatibility -- docs and original code were mismatched
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      Returns:
      true if the open succeeds false if it fails
    • openTrace

      public boolean openTrace(Object identifier, String fileName)
      version for backwards compatibility -- docs and original code were mismatched
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      fileName - the name of the trace file or null if a name should be generated
      Returns:
      true if the open succeeds false if it fails
    • closeTrace

      public boolean closeTrace(Object identifier)
      version for backwards compatibility -- docs and original code were mismatched
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      Returns:
      true if the close succeeds false if it fails
    • out

      public static boolean out(String msg)
      punts to static call dotraceln("out", msg) to print msg to the "out" trace stream
      Parameters:
      msg - the message to be traced
      Returns:
      true
    • err

      public static boolean err(String msg)
      punts to static call dotraceln("err", msg) to print msg to the "err" trace stream
      Parameters:
      msg - the message to be traced
      Returns:
      true
    • verbose

      public static boolean verbose(String msg)
      punts to static call dotraceln("vrb", msg) to print msg to the "vrb" trace stream when the verbose log level is enabled
      Parameters:
      msg - the message to be traced
      Returns:
      true
    • noisy

      public static boolean noisy(String msg)
      punts to static call dotraceln("nzy", msg) to print msg to the "nzy" trace stream when the noisy log level is enabled
      Parameters:
      msg - the message to be traced
      Returns:
      true
    • outTraceException

      public static void outTraceException(Throwable th)
      Print the stack trace for th to the "out" trace stream
      Parameters:
      th - the throwable stack trace
    • errTraceException

      public static void errTraceException(Throwable th)
      Print the stack trace for th to the "err" trace stream
      Parameters:
      th - the throwable stack trace
    • verboseTraceException

      public static void verboseTraceException(Throwable th)
      Print the stack trace for th to System.out when the verbose log level is enabled
      Parameters:
      th - the throwable stack trace
    • noisyTraceException

      public static void noisyTraceException(Throwable th)
      Print the stack trace to System.out when the noisy log level is enabled
      Parameters:
      th - the throwable stack trace
    • doTraceOpen

      private static boolean doTraceOpen(Object identifier, String fileName)
      open a trace output stream identified by identifier to a file located in the current working directory using the given file name or a generated name if the supplied name is null
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      fileName - the name of the trace file or null if a name should be generated
      Returns:
      true if new file and stream was created, false if a stream identified by identifier already existed or if a file of the same name already exists or the identifier is null, "out" or "err"
    • doTraceClose

      private static boolean doTraceClose(Object identifier)
      close the trace output stream identified by identifier flushing any pending output.
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      Returns:
      true if the stream was flushed and closed, false if no stream is identified by identifier or identifier is null, "out" or "err"
    • dotrace

      private static boolean dotrace(Object identifier, String message)
      write the supplied message to the trace stream identified by identifier, creating a new stream if none exists
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      message - the message to be traced
      Returns:
      true caveat: if identifier is the string "out" or null the message will be written to System.out. if identifier is the string "err" the message will be written to System.err.
    • dotraceln

      private static boolean dotraceln(Object identifier, String message)
      write the supplied message to the trace stream identified by identifier, creating a new stream if none exists, and append a new line
      Parameters:
      identifier - an identifier used subsequently to identify the trace output stream
      message - the message to be traced
      Returns:
      true caveat: if identifier is the string "out" or null the message will be written to System.out. if identifier is the string "err" the message will be written to System.err.
    • doTraceException

      private static void doTraceException(Object id, Throwable th)
      Parameters:
      id - the tracestream to write to
      th - the throwable to dump a stacktrace for
    • flag

      public boolean flag(Object identifier)
      set a flag keyed by the supplied object if it is not already set
      Parameters:
      identifier - the object identifying the relevant flag
      Returns:
      true if the flag was clear before this call otherwise false
    • flagged

      public boolean flagged(Object identifier)
      test the state of the flag keyed by the supplied object
      Parameters:
      identifier - the object identifying the relevant flag
      Returns:
      true if the flag is set otherwise false
    • clear

      public boolean clear(Object identifier)
      clear the flag keyed by the supplied object if it is not already clear
      Parameters:
      identifier - the object identifying the relevant flag
      Returns:
      true if the flag was clear before this call otherwise false
    • getCountDown

      public boolean getCountDown(Object identifier)
      for backwards compatibility
      Parameters:
      identifier - an object which uniquely identifies the countdown in question
      Returns:
      true if the countdown is currently installed
    • isCountDown

      public boolean isCountDown(Object identifier)
      builtin to test test if a countdown has been installed
      Parameters:
      identifier - an object which uniquely identifies the countdown in question
      Returns:
      true if the countdown is currently installed
    • addCountDown

      public boolean addCountDown(Object identifier, int count)
      alias for createCountDown provided for backwards compatibility
      Parameters:
      identifier - an object which uniquely identifies the countdown in question
      count - the number of times the countdown needs to be counted down before the countdown operation returns true. e.g. if count is supplied as 2 then the first two calls to countDown(Object) will return false and the third call will return true.
      Returns:
      true if a new countdown is installed, false if one already exists.
    • createCountDown

      public boolean createCountDown(Object identifier, int count)
      builtin to test create a countdown identified by a specific object and with the specified count. n.b. this builtin checks if a countdown identified by the supplied object is currently installed, returning false if so, otherwise atomically adds the countdown and returns true. This allows the builtin to be used safely in conditions where concurrent rule firings (including firings of multiple rules) might otherwise lead to a race condition.
      Parameters:
      identifier - an object which uniquely identifies the countdown in question
      count - the number of times the countdown needs to be counted down before the countdown operation returns true. e.g. if count is supplied as 2 then the first two calls to countDown(Object) will return false and the third call will return true.
      Returns:
      true if a new countdown is installed, false if one already exists.
    • countDown

      public boolean countDown(Object identifier)
      builtin to decrement the countdown identified by a specific object, uninstalling it and returning true only when the count is zero.
      Parameters:
      identifier - an object which uniquely identifies the countdown in question
      Returns:
      true if the countdown is installed and its count is zero, otherwise false
    • waiting

      public boolean waiting(Object identifier)
      test if there are threads waiting for an event identified by the supplied object to be signalled
      Parameters:
      identifier - an object identifying the event to be signalled
      Returns:
      true if threads are waiting for the associated event to be signalled
    • waitFor

      public void waitFor(Object identifier)
      wait for another thread to signal an event with no timeout. see waitFor(Object, long) for details and caveats regarding calling this builtin.
      Parameters:
      identifier - an object used to identify the signal that is to be waited on.
    • waitFor

      public void waitFor(Object identifier, long millisecs)
      wait for another thread to signal an event with a specific timeout or no timeout if zero is supplied as the second argument. this may be called in a rule event, condition or action. it will suspend the current thread pending signalling of the event at which point rule processing will either continue or abort depending upon the type of signal. if an exception is thrown it will be an instance of runtime exception which, in normal circumstances, will cause the thread to exit. The exception may not kill the thread f the trigger method or calling code contains a catch-all handler so care must be used to ensure that an abort of waiting threads has the desired effect. n.b. care must also be employed if the current thread is inside a synchronized block since there is a potential for the waitFor call to cause deadlock.
      Parameters:
      identifier - an object used to identify the signal that is to be waited on. n.b. the wait operation is not performed using synchronization on the supplied object as the rule system cannot safely release and reobtain locks on application data. this argument is used as a key to identify a synchronization object private to the rule system.
      millisecs - hwo long to wait
    • signalWake

      public boolean signalWake(Object identifier)
      call signalWake(Object, boolean) defaulting the second argument to false
      Parameters:
      identifier - an object used to identify the signal that is to be waited on. n.b. the wait operation is not performed using synchronization on the supplied object as the rule system cannot safely release and reobtain locks on application data. this argument is used
      Returns:
      true if a waiting thread was woken false if no thread was waiting
    • signalWake

      public boolean signalWake(Object identifier, boolean mustMeet)
      signal an event identified by the supplied object, causing all waiting threads to resume rule processing and clearing the event. if there are no threads waiting either because there has been no call to waitFor(java.lang.Object) or because some other thread has sent the signal then this call returns false, otherwise it returns true. This operation is atomic, allowing the builtin to be used in rule conditions.
      Parameters:
      identifier - an object used to identify the which waiting threads the signal should be delivered to. n.b. the operation is not performed using a notify on the supplied object. this argument is used as a key to identify a synchronization object private to the rule system.
      mustMeet - if true then the signal operation must not be delivered until some other thread is actually waiting on a waiter identified by identifier. if there is no such waiter when this method is called then the calling thread will suspend until one arrives.
      Returns:
      true if a waiting thread was woken false if no thread was waiting
    • signalKill

      public boolean signalKill(Object identifier)
      for backwards compatibility
      Parameters:
      identifier - an object used to identify the which waiting threads the signal should be delivered to. n.b. the operation is not performed using a notify on the supplied object. this argument is used as a key to identify a synchronization object private to the rule system.
      Returns:
      true if a waiting thread was killed false if no thread was waiting
    • signalKill

      public boolean signalKill(Object identifier, boolean mustMeet)
      for backwards compatibility
      Parameters:
      identifier - an object used to identify the which waiting threads the signal should be delivered to. n.b. the operation is not performed using a notify on the supplied object. this argument is used as a key to identify a synchronization object private to the rule system.
      mustMeet - if true then the signal operation must not be delivered until some other thread is actually waiting on a waiter identified by identifier. if there is no such waiter when this method is called then the calling thread will suspend until one arrives.
      Returns:
      true if a waiting thread was killed false if no thread was waiting
    • signalThrow

      public boolean signalThrow(Object identifier)
      call signalThrow(Object, boolean) defaulting the second argument to false
      Parameters:
      identifier - an object used to identify the which waiting threads the signal should be delivered to. n.b. the operation is not performed using a notify on the supplied object. this argument is used as a key to identify a synchronization object private to the rule system.
      Returns:
      true if a throw occured in a waiting thread false if no thread was waiting
    • signalThrow

      public boolean signalThrow(Object identifier, boolean mustMeet)
      signal an event identified by the suppied object, causing all waiting threads to throw an exception and clearing the event. if there are no objects waiting, either because there has been no call to waitFor(java.lang.Object) or because some other thread has already sent the signal, then this call returns false, otherwise it returns true. This operation is atomic, allowing the builtin to be used safely in rule conditions.
      Parameters:
      identifier - an object used to identify the which waiting threads the signal should be delivered to. n.b. the operation is not performed using a notify on the supplied object. this argument is used as a key to identify a synchronization object private to the rule system.
      mustMeet - if true then the signal operation must not be delivered until some other thread is actually waiting on a waiter identified by identifier. if there is no such waiter when this method is called then the calling thread will suspend until one arrives.
      Returns:
      true if a throw occured in a waiting thread false if no thread was waiting
    • delay

      public void delay(long millisecs)
      delay execution of the current thread for a specified number of milliseconds
      Parameters:
      millisecs - how many milliseconds to delay for
    • createRendezvous

      public boolean createRendezvous(Object identifier, int expected)
      call createRendezvous(Object, int, boolean) supplying false for the last parameter
      Parameters:
      identifier - an identifier for the rendezvous
      expected - the number of threads expected to meet at the rendezvous
      Returns:
      true if the rendezvous is created or false if a rendezvous identified by identifier already exists
    • createRendezvous

      public boolean createRendezvous(Object identifier, int expected, boolean restartable)
      create a rendezvous for a given number of threads to join
      Parameters:
      identifier - an identifier for the rendezvious in subsequent rendezvous operations
      expected - the number of threads expected to meet at the rendezvous
      restartable - true if the rendezvous is can be repeatedly entered false if it is deleted after the first time all expected threads arrive
      Returns:
      true if the rendezvous is created or false if a rendezvous identified by identifier already exists
    • isRendezvous

      public boolean isRendezvous(Object identifier, int expected)
      test whether a rendezvous with a specific expected count is associated with identifier
      Parameters:
      identifier - the identifier for the rendezvous
      expected - the number of threads expected to meet at the rendezvous
      Returns:
      true if the endezvous exists and is active otherwise false
    • getRendezvous

      public int getRendezvous(Object identifier, int expected)
      test whether a rendezvous with a specific expected count is associated with identifier
      Parameters:
      identifier - the identifier for the rendezvous
      expected - the number of threads expected to meet at the rendezvous
      Returns:
      the numer of threads currently arrived at the rendezvous
    • rendezvous

      public int rendezvous(Object identifier)
      meet other threads at a given rendezvous returning only when the expected number have arrived
      Parameters:
      identifier - the identifier for the rendezvous
      Returns:
      an ordinal which sorts all parties to the rendezvous in order of arrival from 0 to (expected-1) or -1 if the rendezvous does not exist
    • rendezvous

      public int rendezvous(Object identifier, long millis)
      meet other threads at a given rendezvous returning either when the expected number have arrived or if a timeout is exceeded
      Parameters:
      identifier - the identifier for the rendezvous
      millis - the timeout after which the caller may return
      Returns:
      an ordinal which sorts all parties to the rendezvous in order of arrival from 0 to (expected-1) or -1 if the rendezvous does not exist or the wait times out
    • deleteRendezvous

      public boolean deleteRendezvous(Object identifier, int expected)
      delete a rendezvous. All threads waiting inside a call to rendezvous return result -1;
      Parameters:
      identifier - the identifier for the rendezvous
      expected - the number of threads expected to meet at the rendezvous
      Returns:
      true if the rendezvous was active and deleted and false if it had already been deleted
    • createJoin

      public boolean createJoin(Object key, int max)
    • isJoin

      public boolean isJoin(Object key, int max)
    • joinEnlist

      public boolean joinEnlist(Object key)
    • joinWait

      public boolean joinWait(Object key, int count)
    • joinWait

      public boolean joinWait(Object key, int count, long millis)
    • createCounter

      public boolean createCounter(Object o)
      create a counter identified by the given object with count 0 as its initial count
      Parameters:
      o - an identifier used to refer to the counter in future
      Returns:
      true if a new counter was created and false if one already existed under the given identifier
    • createCounter

      public boolean createCounter(Object o, int value)
      create a counter identified by the given object with the supplied value as its iniital count
      Parameters:
      o - an identifier used to refer to the counter in future
      value - the initial value for the counter
      Returns:
      true if a new counter was created and false if one already existed under the given identifier
    • deleteCounter

      public boolean deleteCounter(Object o)
      delete a counter identified by the given object with count 0 as its initial count
      Parameters:
      o - the identifier for the coounter
      Returns:
      true if a counter was deleted and false if no counter existed under the given identifier
    • readCounter

      public int readCounter(Object o)
      read the value of the counter associated with given identifier, creating a new one with count zero if none exists
      Parameters:
      o - the identifier for the counter
      Returns:
      the value of the counter
    • readCounter

      public int readCounter(Object o, boolean zero)
      read and optionally reset to zero the value of the counter associated with given identifier, creating a new one with count zero if none exists
      Parameters:
      o - the identifier for the counter
      zero - if true then zero the counter
      Returns:
      the value of the counter
    • incrementCounter

      public int incrementCounter(Object o)
      increment the value of the counter associated with given identifier, creating a new one with count zero if none exists
      Parameters:
      o - the identifier for the counter
      Returns:
      the value of the counter after the increment
    • decrementCounter

      public int decrementCounter(Object o)
      decrement the value of the counter associated with given identifier, creating a new one with count zero if none exists
      Parameters:
      o - the identifier for the counter
      Returns:
      the value of the counter after the decrement
    • incrementCounter

      public int incrementCounter(Object o, int amount)
      increment the value of the counter associated with given identifier by the given amount, creating a new one with count zero if none exists
      Parameters:
      o - the identifier for the counter
      amount - the amount to add to the counter
      Returns:
      the value of the counter after the increment
    • createTimer

      public boolean createTimer(Object o)
      create a timer identified by the given object
      Parameters:
      o - an identifier used to refer to the timer in future
      Returns:
      true if a new timer was created and false if one already existed under the given identifier
    • deleteTimer

      public boolean deleteTimer(Object o)
      delete a timer identified by the given object
      Parameters:
      o - the identifier for the timer
      Returns:
      true if a timer was deleted and false if no timer existed under the given identifier
    • getElapsedTimeFromTimer

      public long getElapsedTimeFromTimer(Object o)
      get the elapsed time from the start (or last reset) of timer associated with given identifier, creating a new one if none exists
      Parameters:
      o - the identifier for the timer
      Returns:
      the elapsed time since the start (or reset) of the timer
    • resetTimer

      public long resetTimer(Object o)
      reset the timer associated with given identifier, creating a new one if none exists
      Parameters:
      o - the identifier for the timer
      Returns:
      the current elapsed value of the timer before the reset
    • createLinkMap

      public boolean createLinkMap(Object mapName)
      create a LinkMap used to store links between names and values
      Parameters:
      mapName - the identifier for the map
      Returns:
      true if a new map was created and false if one already existed under the given identifier
    • deleteLinkMap

      public boolean deleteLinkMap(Object mapName)
      delete a LinkMap used to store links between names and values
      Parameters:
      mapName - the identifier for the map
      Returns:
      true if the map was deleted and false if no map existed under the given identifier
    • link

      public Object link(Object mapName, Object name, Object value)
      atomically add a link from name to value to the LinkMap identified by mapName returning any previously linked Object or null if no link currently exists in the map
      Parameters:
      mapName - the identifier for the map
      name - the name of the key
      value - the value to be stored in the map
      Returns:
      the previous value stored under name, if any, or null
    • linked

      public Object linked(Object mapName, Object name)
      retrieve the Object name currently is linked to from the LinkMap named by mapName or null if no link currently exists in the map
      Parameters:
      mapName - the identifier for the map
      name - the name of the key
      Returns:
      the value stored in the map under the given key
    • unlink

      public Object unlink(Object mapName, Object name)
      atomically remove any link from name returning the Object it is currently linked to or null if no link currently exists in the map
      Parameters:
      mapName - the identifier for the map
      name - the name of the key
      Returns:
      the previous value stored under name, if any, or null
    • linkNames

      public List<Object> linkNames(Object mapName)
      atomically return a list of all keys for current links in the map named by mapName
      Parameters:
      mapName - the name of the map to retrieve keys from
      Returns:
      a possibly zero-length list of all keys or null if the named map is not found
    • linkValues

      public List<Object> linkValues(Object mapName)
      atomically return a list of all values for current links in the map named by mapName
      Parameters:
      mapName - the name of the map to retrieve values from
      Returns:
      a possibly zero-length list of all values or null if the named map is not found
    • clearLinks

      public boolean clearLinks(Object mapName)
      clear all current links from the map named by mapName
      Parameters:
      mapName - the name of the map to clear
      Returns:
      true if the named map was found and was not empty otherwise false
    • link

      public Object link(Object name, Object value)
      add a link to the default LinkMap by calling link("default", name, value)
      Parameters:
      name - the name of the key
      value - the value to be stored under key
      Returns:
      the previous value stored under name, if any, or null
    • linked

      public Object linked(Object name)
      retrieve a link from the default LinkMap by calling linked("default", name)
      Parameters:
      name - the name of the key
      Returns:
      the value stored in the map under the given key
    • unlink

      public Object unlink(Object name)
      delete a link from the default LinkMap by calling unlink("default", name)
      Parameters:
      name - the name of the key
      Returns:
      the previous value stored under name, if any, or null
    • linkNames

      public List<Object> linkNames()
      retrieve all keys in the default linkmap by indirectly calling linkNames("default")
      Returns:
      all current keys in the default linkmap
    • linkValues

      public List<Object> linkValues()
      retrieve all values in the default linkmap by indirectly calling linkValues("default")
      Returns:
      all current values in the default linkmap
    • clearLinks

      public boolean clearLinks()
      clear all links in the default linkmap by indirectly calling clearLinks("default")
      Returns:
      true if the default map was found and was not empty otherwise false
    • killThread

      public void killThread()
      cause the current thread to throw a runtime exception which will normally cause it to exit. The exception may not kill the thread if the trigger method or calling code contains a catch-all handler so care must be employed to ensure that a call to this builtin has the desired effect.
    • killJVM

      public void killJVM()
      cause the current JVM to halt immediately, simulating a crash as near as possible. exit code -1 is returned
    • killJVM

      public void killJVM(int exitCode)
      cause the current JVM to halt immediately, simulating a crash as near as possible.
      Parameters:
      exitCode - the code to be passed to the runtime halt call
    • callerEquals

      public boolean callerEquals(String name)
      test whether the name of the method which called the the trigger method matches the supplied name by calling callerEquals(name, false)
      Parameters:
      name - the name to match
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerEquals(name, 1, frameCount)
      Parameters:
      name - the name to match
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, int startFrame, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerEquals(name, false, startFrame, frameCount)
      Parameters:
      name - the name to match
      startFrame - the frame index to start checking from with 0 identifing the trigger method frame
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, boolean includeClass)
      test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, false)
      Parameters:
      name - the name to match
      includeClass - true if the check shoudl include class name false if not
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, boolean includeClass, int frameCount)
      test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, false, frameCount)
      Parameters:
      name - the name to match
      includeClass - true if the check should include the class name false if not
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, boolean includeClass, int startFrame, int frameCount)
      test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, false, startFrame, frameCount)
      Parameters:
      name - the name to match
      includeClass - true if the check should include the class name false if not
      startFrame - the frame index to start checking from with 0 identifing the trigger method frame
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, boolean includeClass, boolean includePackage)
      test whether the name of method which called the the trigger method matches the supplied name by calling callerEquals(name, includeClass, includePackage, 1)
      Parameters:
      name - the name to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, boolean includeClass, boolean includePackage, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerCheck(name, false, includeClass, includePackage, 1, frameCount)
      Parameters:
      name - the name to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerEquals

      public boolean callerEquals(String name, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied name by calling callerCheck(name, false, includeClass, false, startFrame, frameCount)
      Parameters:
      name - the name to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      startFrame - the frame index to start checking from with 0 identifing the trigger method frame
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied name otherwise false
    • callerMatches

      public boolean callerMatches(String regExp)
      test whether the name of the method which called the the trigger method matches the supplied regular by calling callerMatches(regExp, false)
      Parameters:
      regExp - the pattern to match
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression by calling callerMatches(regExp, 1, frameCount)
      Parameters:
      regExp - the pattern to match
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, int startFrame, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression by calling callerMatches(regExp, false, startFrame, frameCount)
      Parameters:
      regExp - the pattern to match
      startFrame - the frame index to start checking from with 0 identifing the trigger method frame
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, boolean includeClass)
      test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, false)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, boolean includeClass, int frameCount)
      test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, false, frameCount)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, boolean includeClass, int startFrame, int frameCount)
      test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, false, startFrame, frameCount)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      startFrame - the frame index to start checking from with 0 identifing the trigger method frame
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, boolean includeClass, boolean includePackage)
      test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, includePackage, 1)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, boolean includeClass, boolean includePackage, int frameCount)
      test whether the name of method which called the the trigger method matches the supplied regular expression by calling callerMatches(regExp, includeClass, includePackage, 1, frameCount)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerMatches

      public boolean callerMatches(String regExp, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression by calling callerCheck(regExp, true, includeClass, includePackage, 1, frameCount)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      startFrame - the frame index to start checking from with 0 identifing the trigger method frame
      frameCount - the number of frames to check
      Returns:
      true if the name of the method which called the the trigger method matches the supplied regular expression otherwise false
    • callerCheck

      public boolean callerCheck(String match, boolean isRegExp, boolean includeClass, boolean includePackage, int startFrame, int frameCount)
      test whether the name of any of the selected methods in the stack which called the trigger method matches the supplied regular expression.
      Parameters:
      match - an expression which will be matched against the name of the method which called the trigger method
      isRegExp - true if match should be matched as a regular expression and false if it should be matched using a String equals comparison.
      includeClass - true if the match should be against the class qualified method name
      includePackage - true if the match should be against the package and class qualified method name. ignored if includeClass is not also true.
      startFrame - identifies the first frame which frame which should be considered. 0 identifies the trigger frame, 1 the frame for the caller of the trigger method etc. If startFrame is negative false is returned.
      frameCount - counts the frames which should be checked starting from the first caller. if this is non-positive or exceeds the actual number of callers above the start frame then all frames in the stack are tested.
      Returns:
      true if the name of one of the selected methods in the call stack starting from the trigger method matches the supplied match value otherwise false
    • traceStack

      public void traceStack()
      print a stack trace to System.out by calling traceStack(null)
    • traceStack

      public void traceStack(String prefix)
      print a stack trace to System.out by calling traceStack(prefix, "out")
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStack

      public void traceStack(String prefix, Object key)
      print a stack trace to the trace stream identified by key by calling traceStack(prefix, key, 0)
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStack

      public void traceStack(int maxFrames)
      print a stack trace to System.out by calling traceStack(null, maxFrames)
      Parameters:
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceStack

      public void traceStack(String prefix, int maxFrames)
      print a stack trace to System.out by calling traceStack(prefix, "out", maxFrames)
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceStack

      public void traceStack(String prefix, Object key, int maxFrames)
      print a stack trace to the trace stream identified by key
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceAllStacks

      public void traceAllStacks()
      print trace of all threads' stacks to System.out by calling traceAllStacks(null)
    • traceAllStacks

      public void traceAllStacks(String prefix)
      print trace of all threads' stacks to System.out by calling traceAllStacks(prefix, "out")
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceAllStacks

      public void traceAllStacks(String prefix, Object key)
      print trace of all threads' stacks to the trace stream identified by key by calling traceAllStacks(prefix, key, 0)
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceAllStacks

      public void traceAllStacks(int maxFrames)
      print trace of all threads' stacks to System.out by calling traceAllStacks(null, maxFrames)
      Parameters:
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceAllStacks

      public void traceAllStacks(String prefix, int maxFrames)
      print trace of all threads' stacks to System.out by calling traceAllStacks(prefix, "out", maxFrames)
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceAllStacks

      public void traceAllStacks(String prefix, Object key, int maxFrames)
      print trace of all threads' stacks to the trace stream identified by key
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceThreadStack

      public void traceThreadStack(String threadName)
      print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, null)
      Parameters:
      threadName - a string identifying the thread
    • traceThreadStack

      public void traceThreadStack(String threadName, String prefix)
      print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, prefix, "out")
      Parameters:
      threadName - a string identifying the thread
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + threadName + "\n" is used
    • traceThreadStack

      public void traceThreadStack(String threadName, String prefix, Object key)
      print a stack trace of a specific thread to the trace stream identified by key by calling traceThreadStack(threadName, prefix, key, 0)
      Parameters:
      threadName - a string identifying the thread
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + threadName + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceThreadStack

      public void traceThreadStack(String threadName, int maxFrames)
      print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, null, maxFrames)
      Parameters:
      threadName - a string identifying the thread
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceThreadStack

      public void traceThreadStack(String threadName, String prefix, int maxFrames)
      print a stack trace of a specific thread of a specific thread to System.out by calling traceThreadStack(threadName, prefix, "out", maxFrames)
      Parameters:
      threadName - a string identifying the thread
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + threadName + "\n" is used
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceThreadStack

      public void traceThreadStack(String threadName, String prefix, Object key, int maxFrames)
      print a stack trace to the trace stream identified by key
      Parameters:
      threadName - a string identifying the thread
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + threadName + "\n" is used
      key - an object identifying the trace stream to which output should be generated
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
    • traceStackMatching

      public void traceStackMatching(String regExp)
      print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, null)
      Parameters:
      regExp - the pattern to match
    • traceStackMatching

      public void traceStackMatching(String regExp, String prefix)
      print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, prefix, "out")
      Parameters:
      regExp - the pattern to match
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackMatching

      public void traceStackMatching(String regExp, String prefix, Object key)
      print all stack frames which match pattern to System.out preceded by prefix by calling
      Parameters:
      regExp - the pattern to match
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated traceStackMatching(pattern, false, prefix, key)
    • traceStackMatching

      public void traceStackMatching(String regExp, boolean includeClass)
      print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, includeClass, false)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
    • traceStackMatching

      public void traceStackMatching(String regExp, boolean includeClass, String prefix)
      print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, false, prefix)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackMatching

      public void traceStackMatching(String regExp, boolean includeClass, String prefix, Object key)
      print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, false, prefix, key)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackMatching

      public void traceStackMatching(String regExp, boolean includeClass, boolean includePackage)
      print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, includeClass, includePackage, null)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
    • traceStackMatching

      public void traceStackMatching(String regExp, boolean includeClass, boolean includePackage, String prefix)
      print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, , includePackage, prefix, "out")
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackMatching

      public void traceStackMatching(String regExp, boolean includeClass, boolean includePackage, String prefix, Object key)
      print all stack frames which match pattern to the trace stream identified by key preceded by prefix.
      Parameters:
      regExp - a pattern which will be matched against the method name of the stack frame as a regular expression by calling String.matches()
      includeClass - true if the match should be against the package and class qualified method name
      includePackage - true if the match should be against the package and class qualified method name. ignored if includeClass is not also true.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + " matching " + pattern + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackBetween

      public void traceStackBetween(String from, String to)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, null)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
    • traceStackBetween

      public void traceStackBetween(String from, String to, String prefix)
      print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetween(from, to, prefix, "out")
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackBetween

      public void traceStackBetween(String from, String to, String prefix, Object key)
      print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, false, prefix, key)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackBetween

      public void traceStackBetween(String from, String to, boolean includeClass)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, includeClass, false)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
    • traceStackBetween

      public void traceStackBetween(String from, String to, boolean includeClass, String prefix)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, includeClass, false, prefix)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackBetween

      public void traceStackBetween(String from, String to, boolean includeClass, String prefix, Object key)
      print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, includeClass, false, prefix, key)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackBetween

      public void traceStackBetween(String from, String to, boolean includeClass, boolean includePackage)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, includeClass, includePackage, null)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
    • traceStackBetween

      public void traceStackBetween(String from, String to, boolean includeClass, boolean includePackage, String prefix)
      print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetween(from, to, includeClass, includePackage, prefix, "out") should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackBetween

      public void traceStackBetween(String from, String to, boolean includeClass, boolean includePackage, String prefix, Object key)
      print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, false, includeClass, includePackage, prefix, key)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, null)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, String prefix)
      print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetweenMatches(from, to, prefix, "out")
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, String prefix, Object key)
      print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetweenMatches(from, to, false, prefix, key)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, boolean includeClass)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, includeClass, false)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, boolean includeClass, String prefix)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, includeClass, false, prefix)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, boolean includeClass, String prefix, Object key)
      print all stack frames between the frames which match start and end preceded by prefix by calling traceStackBetween(from, to, includeClass, false, prefix, key)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, includeClass, includePackage, null)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage, String prefix)
      print all stack frames between the frames which match start and end to System.out preceded by prefix by calling traceStackBetweenMatches(from, to, true, includeClass, includePackage, prefix, "out");
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
    • traceStackBetweenMatches

      public void traceStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage, String prefix, Object key)
      print all stack frames between the frames which match start and end preceded by prefix by calling traceStackRange(from, to, true, includeClass, includePackage, prefix, key)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • traceStackRange

      public void traceStackRange(String from, String to, boolean isRegExp, boolean includeClass, boolean includePackage, String prefix, Object key)
      print all stack frames between the frames which match start and end to the trace stream identified by key preceded by prefix.
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      isRegExp - true if from and true should be matched as regular expressions or false if they should be matched using a String equals comparison.
      includeClass - true if the match should be against the package and class qualified method name
      includePackage - true if the match should be against the package and class qualified method name. ignored if includeClass is not also true.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace (restricted) for " + Thread.currentThread().getName() + "\n" is used
      key - an object identifying the trace stream to which output should be generated
    • formatStack

      public String formatStack()
      return a stack trace by calling formatStack(null)
      Returns:
      a stack trace formatted as a String
    • formatStack

      public String formatStack(String prefix)
      return a stack trace by calling formatStack(prefix, 0)
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStack

      public String formatStack(int maxFrames)
      return a stack trace by calling formatStack(null, maxFrames)
      Parameters:
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
      Returns:
      a stack trace formatted as a String
    • formatStack

      public String formatStack(String prefix, int maxFrames)
      print a stack trace to the trace stream identified by key
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
      Returns:
      a stack trace formatted as a String
    • formatAllStacks

      public String formatAllStacks()
      return all stack traces by calling formatAllStacks(null)
      Returns:
      all thread stack traces formatted as a String
    • formatAllStacks

      public String formatAllStacks(String prefix)
      return all stack traces by calling formatAllStacks(prefix, 0)
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      all thread stack traces formatted as a String
    • formatAllStacks

      public String formatAllStacks(int maxFrames)
      return all stack traces by calling formatAllStacks(null, maxFrames)
      Parameters:
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
      Returns:
      all thread stack traces formatted as a String
    • formatAllStacks

      public String formatAllStacks(String prefix, int maxFrames)
      return all stack traces
      Parameters:
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
      Returns:
      all thread stack traces formatted as a String
    • formatThreadStack

      public String formatThreadStack(String threadName)
      return stack traces of a specific thread by calling formatThreadStack(threadName, null)
      Parameters:
      threadName - a string identifying the thread
      Returns:
      a stack trace formatted as a String
    • formatThreadStack

      public String formatThreadStack(String threadName, String prefix)
      return all stack traces by calling formatThreadStack(threadName, prefix, 0)
      Parameters:
      threadName - a string identifying the thread
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + threadName + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatThreadStack

      public String formatThreadStack(String threadName, int maxFrames)
      return all stack traces by calling formatThreadStack(threadName, null, maxFrames)
      Parameters:
      threadName - a string identifying the thread
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
      Returns:
      a stack trace formatted as a String
    • formatThreadStack

      public String formatThreadStack(String threadName, String prefix, int maxFrames)
      return all stack traces
      Parameters:
      threadName - a string identifying the thread
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + threadName + "\n" is used
      maxFrames - the maximum number of frames to print or 0 if no limit should apply
      Returns:
      a stack trace formatted as a String
    • appendStack

      private void appendStack(StringBuffer buffer, String prefix, int maxFrames, Thread thread, StackTraceElement[] stack)
    • formatStackMatching

      public String formatStackMatching(String regExp)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, null)
      Parameters:
      regExp - the pattern to match
      Returns:
      a stack trace formatted as a String
    • formatStackMatching

      public String formatStackMatching(String regExp, String prefix)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, false, prefix)
      Parameters:
      regExp - the pattern to match
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackMatching

      public String formatStackMatching(String regExp, boolean includeClass)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, false)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      Returns:
      a stack trace formatted as a String
    • formatStackMatching

      public String formatStackMatching(String regExp, boolean includeClass, String prefix)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, false, prefix)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackMatching

      public String formatStackMatching(String regExp, boolean includeClass, boolean includePackage)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, includePackage, null)
      Parameters:
      regExp - the pattern to match
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      Returns:
      a stack trace formatted as a String
    • formatStackMatching

      public String formatStackMatching(String regExp, boolean includeClass, boolean includePackage, String prefix)
      return a String tracing all stack frames which match pattern.
      Parameters:
      regExp - a pattern which will be matched against the method name of the stack frame as a regular expression by calling String.matches()
      includeClass - true if the match should be against the package and class qualified method name
      includePackage - true if the match should be against the package and class qualified method name. ignored if includeClass is not also true.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + " matching " + pattern + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackBetween

      public String formatStackBetween(String from, String to)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, null)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      Returns:
      a stack trace formatted as a String
    • formatStackBetween

      public String formatStackBetween(String from, String to, String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, false, false, false, prefix)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackBetween

      public String formatStackBetween(String from, String to, boolean includeClass)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, false)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      Returns:
      a stack trace formatted as a String
    • formatStackBetween

      public String formatStackBetween(String from, String to, boolean includeClass, String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, false, prefix)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackBetween

      public String formatStackBetween(String from, String to, boolean includeClass, boolean includePackage)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, includePackage, null)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      Returns:
      a stack trace formatted as a String
    • formatStackBetween

      public String formatStackBetween(String from, String to, boolean includeClass, boolean includePackage, String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackRange(from, to, false, includeClass, includePackage, prefix)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackBetweenMatches

      public String formatStackBetweenMatches(String from, String to)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, null)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      Returns:
      a stack trace formatted as a String
    • formatStackBetweenMatches

      public String formatStackBetweenMatches(String from, String to, String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, false, false, false, prefix)
      Parameters:
      from - a string which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a string which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackBetweenMatches

      public String formatStackBetweenMatches(String from, String to, boolean includeClass)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, false)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      Returns:
      a stack trace formatted as a String
    • formatStackBetweenMatches

      public String formatStackBetweenMatches(String from, String to, boolean includeClass, String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, false, prefix)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackBetweenMatches

      public String formatStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, includePackage, null)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      Returns:
      a stack trace formatted as a String
    • formatStackBetweenMatches

      public String formatStackBetweenMatches(String from, String to, boolean includeClass, boolean includePackage, String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackRange(from, to, true, includeClass, includePackage, prefix)
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      includeClass - true if the check should include the class name false if not
      includePackage - true if the check should include the package name false if not
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace for thread " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • formatStackRange

      public String formatStackRange(String from, String to, boolean isRegExp, boolean includeClass, boolean includePackage, String prefix)
      return a String tracing the stack between the frames which match start and end.
      Parameters:
      from - a pattern which identifies the first frame which should be printed. from will be matched against the name of each successive stack frame from the trigger methdo frame until a matching frame is found. If null is supplied then the trigger frame will be used as the first frame to print. If a non-null value is supplied and no match is found then no frames will be printed.
      to - a pattern which identifies the last frame which should be printed. to will be matched against the name of each successive stack frame following the first matched frame until a matching frame is found. If null is supplied or no match is found then the bottom frame will be used as the last frame to print.
      isRegExp - true if from and true should be matched as regular expressions or false if they should be matched using a String equals comparison.
      includeClass - true if the match should be against the package and class qualified method name
      includePackage - true if the match should be against the package and class qualified method name. ignored if includeClass is not also true.
      prefix - a String to be printed once before printing each line of stack trace. if supplied as null then the prefix "Stack trace (restricted) for " + Thread.currentThread().getName() + "\n" is used
      Returns:
      a stack trace formatted as a String
    • setTriggering

      public boolean setTriggering(boolean enabled)
      enable or disable recursive triggering of rules by subsequent operations performed during binding, testing or firing of the current rule in the current thread.
      Parameters:
      enabled - true if triggering should be enabled or false if it should be disabled
      Returns:
      always returns true so it can be called in a rule condition
    • getObjectSize

      public long getObjectSize(Object o)
      provide an estimate of an object's size return -1 if not running in a real agent
      Parameters:
      o - the object whose size is sought
      Returns:
      the size or -1
    • toString

      public String toString()
      return a unique name for the trigger point associated with this rule. n.b. a single rule may give rise to more than one trigger point if the rule applies to several methods with the same name or to several classes with the same (package unqualified) name, or even to several versions of the same compiled class loaded into distinct class loaders.
      Overrides:
      toString in class Object
      Returns:
      a unique name for the trigger point from which this rule was invoked
    • activated

      public static void activated()
    • deactivated

      public static void deactivated()
    • installed

      public static void installed(Rule rule)
    • uninstalled

      public static void uninstalled(Rule rule)
    • getStack

      protected StackTraceElement[] getStack()
      access to the current stack frames
      Returns:
      an array of stack trace elements for the current stack
    • triggerIndex

      protected int triggerIndex(StackTraceElement[] stack)
      return the index of the frame in stack for the trigger method below which the rule system was entered or -1 if it cannot be found
      Parameters:
      stack - an array of stack trace elements for the current stack
      Returns:
      the index of the frame for the trigger method or -1 if it cannot be found
    • matchIndex

      protected int matchIndex(StackTraceElement[] stack, String pattern, boolean isRegExp, boolean includeClass, boolean includePackage, int start, int limit)
      return the index of the first frame at or below index start which matches pattern
      Parameters:
      stack - array of stack trace elements
      pattern - a pattern to be matched against the concatenated frame method name using String.matches()
      isRegExp - true if the pattern should be matched as a regular expression or false if it should be matched using a String equals comparison
      includeClass - true if the method name should be qualified with the package and class name
      includePackage - true if the check should include the package name false if not
      start - the index of the first frame which should be tested for a match. this must be greater than or equal to the trigger index.
      limit - the index of the first frame which should not be tested for a match. this must be less than or equal to the stack length
      Returns:
      the index of the matching frame between start and limit - 1 or -1 if it no match found
    • printlnFrame

      protected void printlnFrame(StringBuffer buffer, StackTraceElement frame)
      print the details of stack frame followed by a newline to buffer by calling printlnFrame(buffer, frame) then buffer.append('\n')
      Parameters:
      buffer - the buffer to write to
      frame - the stack frame to print
    • printFrame

      protected void printFrame(StringBuffer buffer, StackTraceElement frame)
      print the details of stack frame to buffer
      Parameters:
      buffer - the buffer to write to
      frame - the stack frame to print
    • getWaiter

      private Waiter getWaiter(Object object, boolean createIfAbsent)
      lookup the waiter object used to target wait and signal requests associated with a specific identifying object
      Parameters:
      object - the identifer for the waiter
      createIfAbsent - true if the waiter should be (atomically) inserted if it is not present
      Returns:
      the waiter if it was found or inserted or null if it was not found and createIfAbsent was false
    • removeWaiter

      private Waiter removeWaiter(Object object)
      remove the waiter object used to target wait and signal requests associated with a specific identifying object
      Parameters:
      object - the identifer for the waiter
      Returns:
      the waiter if it was found or inserted or null if it was not found and createIfAbsent was false
    • nextFileIndex

      private static int nextFileIndex()
    • nextFileName

      private static String nextFileName()
      generate a name for an output file to be used to sink the trace stream named by identifier. the name will start with the prefix "trace" followed by a 9 digit number followed by a ".log" suffix.
      Returns:
      a name to be used for the trace file.
    • clearStaticResources

      private static void clearStaticResources()
      clean up function called by deactivate to ensure all static resources used to hold rule state are cleared