Class Helper

  • Direct Known Subclasses:
    BytemanTestHelper, InterpretedHelper, JMXHelper, PeriodicHelper, ThreadHistoryMonitorHelper, ThreadMonitorHelper

    public class Helper
    extends java.lang.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 java.util.HashMap<java.lang.Object,​CountDown> countDownMap
      a hash map used to identify countdowns from their identifying objects
      private static java.util.HashMap<java.lang.Object,​Counter> counterMap
      a hash map used to identify counters from their identifying objects
      private static java.util.Set<java.lang.Object> flagSet
      a set used to identify settings for boolean flags associated with arbitrary objects.
      private static java.util.HashMap<java.lang.Object,​Joiner> joinerMap  
      private static java.util.concurrent.ConcurrentHashMap<java.lang.Object,​java.util.HashMap<java.lang.Object,​java.lang.Object>> linkMaps
      a hash map used to identify maps from their identifying objects
      private static int nextFileIndex  
      private static java.util.HashMap<java.lang.Object,​Rendezvous> rendezvousMap
      a hash map used to identify rendezvous from their identifying objects
      protected Rule rule  
      private static java.lang.String RULE_CLASS_NAME  
      private static java.lang.String RULE_EXECUTE_METHOD_NAME  
      private java.lang.StackTraceElement[] stack  
      private static java.util.HashMap<java.lang.Object,​Timer> timerMap
      a hash map used to identify timer from their identifying objects
      private static java.util.concurrent.ConcurrentMap<java.lang.Object,​java.io.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.
      private static java.util.HashMap<java.lang.Object,​Waiter> waitMap
      a hash map used to identify waiters from their identifying objects
    • Constructor Summary

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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void activated()  
      boolean addCountDown​(java.lang.Object identifier, int count)
      alias for createCountDown provided for backwards compatibility
      private void appendStack​(java.lang.StringBuffer buffer, java.lang.String prefix, int maxFrames, java.lang.Thread thread, java.lang.StackTraceElement[] stack)  
      boolean callerCheck​(java.lang.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 callerEquals​(java.lang.String name)
      test whether the name of the method which called the the trigger method matches the supplied name by calling callerEquals(name, false)
      boolean callerEquals​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 callerMatches​(java.lang.String regExp)
      test whether the name of the method which called the the trigger method matches the supplied regular by calling callerMatches(regExp, false)
      boolean callerMatches​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.Object identifier)
      clear the flag keyed by the supplied object if it is not already clear
      boolean clearLinks()
      clear all links in the default linkmap by indirectly calling clearLinks("default")
      boolean clearLinks​(java.lang.Object mapName)
      clear all current links from the map named by mapName
      private static void clearStaticResources()
      clean up function called by deactivate to ensure all static resources used to hold rule state are cleared
      boolean closeTrace​(java.lang.Object identifier)
      version for backwards compatibility -- docs and original code were mismatched
      boolean countDown​(java.lang.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​(java.lang.Object identifier, int count)
      builtin to test create a countdown identified by a specific object and with the specified count.
      boolean createCounter​(java.lang.Object o)
      create a counter identified by the given object with count 0 as its initial count
      boolean createCounter​(java.lang.Object o, int value)
      create a counter identified by the given object with the supplied value as its iniital count
      boolean createJoin​(java.lang.Object key, int max)  
      boolean createLinkMap​(java.lang.Object mapName)
      create a LinkMap used to store links between names and values
      boolean createRendezvous​(java.lang.Object identifier, int expected)
      call createRendezvous(Object, int, boolean) supplying false for the last parameter
      boolean createRendezvous​(java.lang.Object identifier, int expected, boolean restartable)
      create a rendezvous for a given number of threads to join
      boolean createTimer​(java.lang.Object o)
      create a timer identified by the given object
      static void deactivated()  
      boolean debug​(java.lang.String text)
      builtin to print a message during rule execution.
      int decrementCounter​(java.lang.Object o)
      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 deleteCounter​(java.lang.Object o)
      delete a counter identified by the given object with count 0 as its initial count
      boolean deleteLinkMap​(java.lang.Object mapName)
      delete a LinkMap used to store links between names and values
      boolean deleteRendezvous​(java.lang.Object identifier, int expected)
      delete a rendezvous.
      boolean deleteTimer​(java.lang.Object o)
      delete a timer identified by the given object
      private static boolean dotrace​(java.lang.Object identifier, java.lang.String message)
      write the supplied message to the trace stream identified by identifier, creating a new stream if none exists
      private static boolean doTraceClose​(java.lang.Object identifier)
      close the trace output stream identified by identifier flushing any pending output.
      private static void doTraceException​(java.lang.Object id, java.lang.Throwable th)  
      private static boolean dotraceln​(java.lang.Object identifier, java.lang.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​(java.lang.Object identifier, java.lang.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​(java.lang.String msg)
      punts to static call dotraceln("err", msg) to print msg to the "err" trace stream
      static void errTraceException​(java.lang.Throwable th)
      Print the stack trace for th to the "err" trace stream
      boolean flag​(java.lang.Object identifier)
      set a flag keyed by the supplied object if it is not already set
      boolean flagged​(java.lang.Object identifier)
      test the state of the flag keyed by the supplied object
      java.lang.String formatAllStacks()
      return all stack traces by calling formatAllStacks(null)
      java.lang.String formatAllStacks​(int maxFrames)
      return all stack traces by calling formatAllStacks(null, maxFrames)
      java.lang.String formatAllStacks​(java.lang.String prefix)
      return all stack traces by calling formatAllStacks(prefix, 0)
      java.lang.String formatAllStacks​(java.lang.String prefix, int maxFrames)
      return all stack traces
      java.lang.String formatStack()
      return a stack trace by calling formatStack(null)
      java.lang.String formatStack​(int maxFrames)
      return a stack trace by calling formatStack(null, maxFrames)
      java.lang.String formatStack​(java.lang.String prefix)
      return a stack trace by calling formatStack(prefix, 0)
      java.lang.String formatStack​(java.lang.String prefix, int maxFrames)
      print a stack trace to the trace stream identified by key
      java.lang.String formatStackBetween​(java.lang.String from, java.lang.String to)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, null)
      java.lang.String formatStackBetween​(java.lang.String from, java.lang.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)
      java.lang.String formatStackBetween​(java.lang.String from, java.lang.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)
      java.lang.String formatStackBetween​(java.lang.String from, java.lang.String to, boolean includeClass, boolean includePackage, java.lang.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)
      java.lang.String formatStackBetween​(java.lang.String from, java.lang.String to, boolean includeClass, java.lang.String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetween(from, to, includeClass, false, prefix)
      java.lang.String formatStackBetween​(java.lang.String from, java.lang.String to, java.lang.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)
      java.lang.String formatStackBetweenMatches​(java.lang.String from, java.lang.String to)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, null)
      java.lang.String formatStackBetweenMatches​(java.lang.String from, java.lang.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)
      java.lang.String formatStackBetweenMatches​(java.lang.String from, java.lang.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)
      java.lang.String formatStackBetweenMatches​(java.lang.String from, java.lang.String to, boolean includeClass, boolean includePackage, java.lang.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)
      java.lang.String formatStackBetweenMatches​(java.lang.String from, java.lang.String to, boolean includeClass, java.lang.String prefix)
      return a String tracing the stack between the frames which match start and end by calling formatStackBetweenMatches(from, to, includeClass, false, prefix)
      java.lang.String formatStackBetweenMatches​(java.lang.String from, java.lang.String to, java.lang.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)
      java.lang.String formatStackMatching​(java.lang.String regExp)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, null)
      java.lang.String formatStackMatching​(java.lang.String regExp, boolean includeClass)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, false)
      java.lang.String formatStackMatching​(java.lang.String regExp, boolean includeClass, boolean includePackage)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, includePackage, null)
      java.lang.String formatStackMatching​(java.lang.String regExp, boolean includeClass, boolean includePackage, java.lang.String prefix)
      return a String tracing all stack frames which match pattern.
      java.lang.String formatStackMatching​(java.lang.String regExp, boolean includeClass, java.lang.String prefix)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, includeClass, false, prefix)
      java.lang.String formatStackMatching​(java.lang.String regExp, java.lang.String prefix)
      return a String tracing all stack frames which match pattern by calling formatStackMatching(pattern, false, prefix)
      java.lang.String formatStackRange​(java.lang.String from, java.lang.String to, boolean isRegExp, boolean includeClass, boolean includePackage, java.lang.String prefix)
      return a String tracing the stack between the frames which match start and end.
      java.lang.String formatThreadStack​(java.lang.String threadName)
      return stack traces of a specific thread by calling formatThreadStack(threadName, null)
      java.lang.String formatThreadStack​(java.lang.String threadName, int maxFrames)
      return all stack traces by calling formatThreadStack(threadName, null, maxFrames)
      java.lang.String formatThreadStack​(java.lang.String threadName, java.lang.String prefix)
      return all stack traces by calling formatThreadStack(threadName, prefix, 0)
      java.lang.String formatThreadStack​(java.lang.String threadName, java.lang.String prefix, int maxFrames)
      return all stack traces
      boolean getCountDown​(java.lang.Object identifier)
      for backwards compatibility
      long getElapsedTimeFromTimer​(java.lang.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
      long getObjectSize​(java.lang.Object o)
      provide an estimate of an object's size return -1 if not running in a real agent
      int getRendezvous​(java.lang.Object identifier, int expected)
      test whether a rendezvous with a specific expected count is associated with identifier
      protected java.lang.StackTraceElement[] getStack()
      access to the current stack frames
      private Waiter getWaiter​(java.lang.Object object, boolean createIfAbsent)
      lookup the waiter object used to target wait and signal requests associated with a specific identifying object
      int incrementCounter​(java.lang.Object o)
      increment the value of the counter associated with given identifier, creating a new one with count zero if none exists
      int incrementCounter​(java.lang.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 installed​(Rule rule)  
      boolean isCountDown​(java.lang.Object identifier)
      builtin to test test if a countdown has been installed
      boolean isJoin​(java.lang.Object key, int max)  
      boolean isRendezvous​(java.lang.Object identifier, int expected)
      test whether a rendezvous with a specific expected count is associated with identifier
      boolean joinEnlist​(java.lang.Object key)  
      boolean joinWait​(java.lang.Object key, int count)  
      boolean joinWait​(java.lang.Object key, int count, long millis)  
      void killJVM()
      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 killThread()
      cause the current thread to throw a runtime exception which will normally cause it to exit.
      java.lang.Object link​(java.lang.Object name, java.lang.Object value)
      add a link to the default LinkMap by calling link("default", name, value)
      java.lang.Object link​(java.lang.Object mapName, java.lang.Object name, java.lang.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
      java.lang.Object linked​(java.lang.Object name)
      retrieve a link from the default LinkMap by calling linked("default", name)
      java.lang.Object linked​(java.lang.Object mapName, java.lang.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
      java.util.List<java.lang.Object> linkNames()
      retrieve all keys in the default linkmap by indirectly calling linkNames("default")
      java.util.List<java.lang.Object> linkNames​(java.lang.Object mapName)
      atomically return a list of all keys for current links in the map named by mapName
      java.util.List<java.lang.Object> linkValues()
      retrieve all values in the default linkmap by indirectly calling linkValues("default")
      java.util.List<java.lang.Object> linkValues​(java.lang.Object mapName)
      atomically return a list of all values for current links in the map named by mapName
      protected int matchIndex​(java.lang.StackTraceElement[] stack, java.lang.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 nextFileIndex()  
      private static java.lang.String nextFileName()
      generate a name for an output file to be used to sink the trace stream named by identifier.
      static boolean noisy​(java.lang.String msg)
      punts to static call dotraceln("nzy", msg) to print msg to the "nzy" trace stream when the noisy log level is enabled
      static void noisyTraceException​(java.lang.Throwable th)
      Print the stack trace to System.out when the noisy log level is enabled
      boolean openTrace​(java.lang.Object identifier)
      version for backwards compatibility -- docs and original code were mismatched
      boolean openTrace​(java.lang.Object identifier, java.lang.String fileName)
      version for backwards compatibility -- docs and original code were mismatched
      static boolean out​(java.lang.String msg)
      punts to static call dotraceln("out", msg) to print msg to the "out" trace stream
      static void outTraceException​(java.lang.Throwable th)
      Print the stack trace for th to the "out" trace stream
      protected void printFrame​(java.lang.StringBuffer buffer, java.lang.StackTraceElement frame)
      print the details of stack frame to buffer
      protected void printlnFrame​(java.lang.StringBuffer buffer, java.lang.StackTraceElement frame)
      print the details of stack frame followed by a newline to buffer by calling printlnFrame(buffer, frame) then buffer.append('\n')
      int readCounter​(java.lang.Object o)
      read the value of the counter associated with given identifier, creating a new one with count zero if none exists
      int readCounter​(java.lang.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 removeWaiter​(java.lang.Object object)
      remove the waiter object used to target wait and signal requests associated with a specific identifying object
      int rendezvous​(java.lang.Object identifier)
      meet other threads at a given rendezvous returning only when the expected number have arrived
      int rendezvous​(java.lang.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 resetTimer​(java.lang.Object o)
      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​(java.lang.Object identifier)
      for backwards compatibility
      boolean signalKill​(java.lang.Object identifier, boolean mustMeet)
      for backwards compatibility
      boolean signalThrow​(java.lang.Object identifier)
      call signalThrow(Object, boolean) defaulting the second argument to false
      boolean signalThrow​(java.lang.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​(java.lang.Object identifier)
      call signalWake(Object, boolean) defaulting the second argument to false
      boolean signalWake​(java.lang.Object identifier, boolean mustMeet)
      signal an event identified by the supplied object, causing all waiting threads to resume rule processing and clearing the event.
      java.lang.String toString()
      return a unique name for the trigger point associated with this rule.
      boolean trace​(java.lang.Object identifier, java.lang.String message)
      punts to static call Helper.dotrace(identifier, message).
      boolean trace​(java.lang.String message)
      equivalent to calling trace("out", message).
      void traceAllStacks()
      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 traceAllStacks​(java.lang.String prefix)
      print trace of all threads' stacks to System.out by calling traceAllStacks(prefix, "out")
      void traceAllStacks​(java.lang.String prefix, int maxFrames)
      print trace of all threads' stacks to System.out by calling traceAllStacks(prefix, "out", maxFrames)
      void traceAllStacks​(java.lang.String prefix, java.lang.Object key)
      print trace of all threads' stacks to the trace stream identified by key by calling traceAllStacks(prefix, key, 0)
      void traceAllStacks​(java.lang.String prefix, java.lang.Object key, int maxFrames)
      print trace of all threads' stacks to the trace stream identified by key
      boolean traceClose​(java.lang.Object identifier)
      builtin to close the trace output stream identified by identifier flushing any pending output.
      boolean traceln​(java.lang.Object identifier, java.lang.String message)
      punts to static call dotraceln(identifier, message).
      boolean traceln​(java.lang.String message)
      equivalent to calling traceln("out", message).
      boolean traceOpen​(java.lang.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​(java.lang.Object identifier, java.lang.String fileName)
      builtin to open a trace output stream which is redirected to a file in the current directory if specified.
      void traceStack()
      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 traceStack​(java.lang.String prefix)
      print a stack trace to System.out by calling traceStack(prefix, "out")
      void traceStack​(java.lang.String prefix, int maxFrames)
      print a stack trace to System.out by calling traceStack(prefix, "out", maxFrames)
      void traceStack​(java.lang.String prefix, java.lang.Object key)
      print a stack trace to the trace stream identified by key by calling traceStack(prefix, key, 0)
      void traceStack​(java.lang.String prefix, java.lang.Object key, int maxFrames)
      print a stack trace to the trace stream identified by key
      void traceStackBetween​(java.lang.String from, java.lang.String to)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetween(from, to, null)
      void traceStackBetween​(java.lang.String from, java.lang.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​(java.lang.String from, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, boolean includePackage, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, boolean includePackage, java.lang.String prefix, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, java.lang.String prefix, java.lang.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​(java.lang.String from, java.lang.String to, java.lang.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​(java.lang.String from, java.lang.String to, java.lang.String prefix, java.lang.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 traceStackBetweenMatches​(java.lang.String from, java.lang.String to)
      print all stack frames between the frames which match start and end to System.out by calling traceStackBetweenMatches(from, to, null)
      void traceStackBetweenMatches​(java.lang.String from, java.lang.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​(java.lang.String from, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, boolean includePackage, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, boolean includePackage, java.lang.String prefix, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, java.lang.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​(java.lang.String from, java.lang.String to, boolean includeClass, java.lang.String prefix, java.lang.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 traceStackBetweenMatches​(java.lang.String from, java.lang.String to, java.lang.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")
      void traceStackBetweenMatches​(java.lang.String from, java.lang.String to, java.lang.String prefix, java.lang.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)
      void traceStackMatching​(java.lang.String regExp)
      print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, null)
      void traceStackMatching​(java.lang.String regExp, boolean includeClass)
      print all stack frames which match pattern to System.out by calling traceStackMatching(pattern, includeClass, false)
      void traceStackMatching​(java.lang.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​(java.lang.String regExp, boolean includeClass, boolean includePackage, java.lang.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​(java.lang.String regExp, boolean includeClass, boolean includePackage, java.lang.String prefix, java.lang.Object key)
      print all stack frames which match pattern to the trace stream identified by key preceded by prefix.
      void traceStackMatching​(java.lang.String regExp, boolean includeClass, java.lang.String prefix)
      print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, includeClass, false, prefix)
      void traceStackMatching​(java.lang.String regExp, boolean includeClass, java.lang.String prefix, java.lang.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​(java.lang.String regExp, java.lang.String prefix)
      print all stack frames which match pattern to System.out preceded by prefix by calling traceStackMatching(pattern, prefix, "out")
      void traceStackMatching​(java.lang.String regExp, java.lang.String prefix, java.lang.Object key)
      print all stack frames which match pattern to System.out preceded by prefix by calling
      void traceStackRange​(java.lang.String from, java.lang.String to, boolean isRegExp, boolean includeClass, boolean includePackage, java.lang.String prefix, java.lang.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 traceThreadStack​(java.lang.String threadName)
      print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, null)
      void traceThreadStack​(java.lang.String threadName, int maxFrames)
      print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, null, maxFrames)
      void traceThreadStack​(java.lang.String threadName, java.lang.String prefix)
      print a stack trace of a specific thread to System.out by calling traceThreadStack(threadName, prefix, "out")
      void traceThreadStack​(java.lang.String threadName, java.lang.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​(java.lang.String threadName, java.lang.String prefix, java.lang.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​(java.lang.String threadName, java.lang.String prefix, java.lang.Object key, int maxFrames)
      print a stack trace to the trace stream identified by key
      protected int triggerIndex​(java.lang.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
      static void uninstalled​(Rule rule)  
      java.lang.Object unlink​(java.lang.Object name)
      delete a link from the default LinkMap by calling unlink("default", name)
      java.lang.Object unlink​(java.lang.Object mapName, java.lang.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 verbose​(java.lang.String msg)
      punts to static call dotraceln("vrb", msg) to print msg to the "vrb" trace stream when the verbose log level is enabled
      static void verboseTraceException​(java.lang.Throwable th)
      Print the stack trace for th to System.out when the verbose log level is enabled
      void waitFor​(java.lang.Object identifier)
      wait for another thread to signal an event with no timeout.
      void waitFor​(java.lang.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​(java.lang.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 Detail

      • rule

        protected Rule rule
      • joinerMap

        private static java.util.HashMap<java.lang.Object,​Joiner> joinerMap
      • stack

        private java.lang.StackTraceElement[] stack
      • RULE_CLASS_NAME

        private static java.lang.String RULE_CLASS_NAME
      • RULE_EXECUTE_METHOD_NAME

        private static java.lang.String RULE_EXECUTE_METHOD_NAME
      • nextFileIndex

        private static int nextFileIndex
      • traceMap

        private static final java.util.concurrent.ConcurrentMap<java.lang.Object,​java.io.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 java.util.Set<java.lang.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 java.util.HashMap<java.lang.Object,​CountDown> countDownMap
        a hash map used to identify countdowns from their identifying objects
      • counterMap

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

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

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

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

        private static java.util.concurrent.ConcurrentHashMap<java.lang.Object,​java.util.HashMap<java.lang.Object,​java.lang.Object>> linkMaps
        a hash map used to identify maps from their identifying objects
    • Constructor Detail

      • Helper

        protected Helper​(Rule rule)
    • Method Detail

      • debug

        public boolean debug​(java.lang.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​(java.lang.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​(java.lang.Object identifier,
                                 java.lang.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​(java.lang.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​(java.lang.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​(java.lang.Object identifier,
                             java.lang.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​(java.lang.String message)
        equivalent to calling traceln("out", message).
        Parameters:
        message - the message to be traced
        Returns:
        true
      • traceln

        public boolean traceln​(java.lang.Object identifier,
                               java.lang.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​(java.lang.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​(java.lang.Object identifier,
                                 java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.Throwable th)
        Print the stack trace for th to the "out" trace stream
        Parameters:
        th - the throwable stack trace
      • errTraceException

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

        public static void verboseTraceException​(java.lang.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​(java.lang.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​(java.lang.Object identifier,
                                           java.lang.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​(java.lang.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​(java.lang.Object identifier,
                                       java.lang.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​(java.lang.Object identifier,
                                         java.lang.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​(java.lang.Object id,
                                             java.lang.Throwable th)
        Parameters:
        id - the tracestream to write to
        th - the throwable to dump a stacktrace for
      • flag

        public boolean flag​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.Object key,
                                  int max)
      • isJoin

        public boolean isJoin​(java.lang.Object key,
                              int max)
      • joinEnlist

        public boolean joinEnlist​(java.lang.Object key)
      • joinWait

        public boolean joinWait​(java.lang.Object key,
                                int count)
      • joinWait

        public boolean joinWait​(java.lang.Object key,
                                int count,
                                long millis)
      • createCounter

        public boolean createCounter​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.Object link​(java.lang.Object mapName,
                                     java.lang.Object name,
                                     java.lang.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 java.lang.Object linked​(java.lang.Object mapName,
                                       java.lang.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 java.lang.Object unlink​(java.lang.Object mapName,
                                       java.lang.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 java.util.List<java.lang.Object> linkNames​(java.lang.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 java.util.List<java.lang.Object> linkValues​(java.lang.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​(java.lang.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 java.lang.Object link​(java.lang.Object name,
                                     java.lang.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 java.lang.Object linked​(java.lang.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 java.lang.Object unlink​(java.lang.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 java.util.List<java.lang.Object> linkNames()
        retrieve all keys in the default linkmap by indirectly calling linkNames("default")
        Returns:
        all current keys in the default linkmap
      • linkValues

        public java.util.List<java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String prefix,
                               java.lang.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​(java.lang.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​(java.lang.String prefix,
                               java.lang.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​(java.lang.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​(java.lang.String prefix,
                                   java.lang.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​(java.lang.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​(java.lang.String prefix,
                                   java.lang.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​(java.lang.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​(java.lang.String threadName,
                                     java.lang.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​(java.lang.String threadName,
                                     java.lang.String prefix,
                                     java.lang.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​(java.lang.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​(java.lang.String threadName,
                                     java.lang.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​(java.lang.String threadName,
                                     java.lang.String prefix,
                                     java.lang.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​(java.lang.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​(java.lang.String regExp,
                                       java.lang.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​(java.lang.String regExp,
                                       java.lang.String prefix,
                                       java.lang.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​(java.lang.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​(java.lang.String regExp,
                                       boolean includeClass,
                                       java.lang.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​(java.lang.String regExp,
                                       boolean includeClass,
                                       java.lang.String prefix,
                                       java.lang.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​(java.lang.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​(java.lang.String regExp,
                                       boolean includeClass,
                                       boolean includePackage,
                                       java.lang.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​(java.lang.String regExp,
                                       boolean includeClass,
                                       boolean includePackage,
                                       java.lang.String prefix,
                                       java.lang.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​(java.lang.String from,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.String to,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.String to,
                                      java.lang.String prefix,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.String to,
                                      boolean includeClass,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.String to,
                                      boolean includeClass,
                                      java.lang.String prefix,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.String to,
                                      boolean includeClass,
                                      boolean includePackage,
                                      java.lang.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​(java.lang.String from,
                                      java.lang.String to,
                                      boolean includeClass,
                                      boolean includePackage,
                                      java.lang.String prefix,
                                      java.lang.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​(java.lang.String from,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.String to,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.String to,
                                             java.lang.String prefix,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.String to,
                                             boolean includeClass,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.String to,
                                             boolean includeClass,
                                             java.lang.String prefix,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.String to,
                                             boolean includeClass,
                                             boolean includePackage,
                                             java.lang.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​(java.lang.String from,
                                             java.lang.String to,
                                             boolean includeClass,
                                             boolean includePackage,
                                             java.lang.String prefix,
                                             java.lang.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​(java.lang.String from,
                                    java.lang.String to,
                                    boolean isRegExp,
                                    boolean includeClass,
                                    boolean includePackage,
                                    java.lang.String prefix,
                                    java.lang.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 java.lang.String formatStack()
        return a stack trace by calling formatStack(null)
        Returns:
        a stack trace formatted as a String
      • formatStack

        public java.lang.String formatStack​(java.lang.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 java.lang.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 java.lang.String formatStack​(java.lang.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 java.lang.String formatAllStacks()
        return all stack traces by calling formatAllStacks(null)
        Returns:
        all thread stack traces formatted as a String
      • formatAllStacks

        public java.lang.String formatAllStacks​(java.lang.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 java.lang.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 java.lang.String formatAllStacks​(java.lang.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 java.lang.String formatThreadStack​(java.lang.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 java.lang.String formatThreadStack​(java.lang.String threadName,
                                                  java.lang.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 java.lang.String formatThreadStack​(java.lang.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 java.lang.String formatThreadStack​(java.lang.String threadName,
                                                  java.lang.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​(java.lang.StringBuffer buffer,
                                 java.lang.String prefix,
                                 int maxFrames,
                                 java.lang.Thread thread,
                                 java.lang.StackTraceElement[] stack)
      • formatStackMatching

        public java.lang.String formatStackMatching​(java.lang.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 java.lang.String formatStackMatching​(java.lang.String regExp,
                                                    java.lang.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 java.lang.String formatStackMatching​(java.lang.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 java.lang.String formatStackMatching​(java.lang.String regExp,
                                                    boolean includeClass,
                                                    java.lang.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 java.lang.String formatStackMatching​(java.lang.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 java.lang.String formatStackMatching​(java.lang.String regExp,
                                                    boolean includeClass,
                                                    boolean includePackage,
                                                    java.lang.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 java.lang.String formatStackBetween​(java.lang.String from,
                                                   java.lang.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 java.lang.String formatStackBetween​(java.lang.String from,
                                                   java.lang.String to,
                                                   java.lang.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 java.lang.String formatStackBetween​(java.lang.String from,
                                                   java.lang.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 java.lang.String formatStackBetween​(java.lang.String from,
                                                   java.lang.String to,
                                                   boolean includeClass,
                                                   java.lang.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 java.lang.String formatStackBetween​(java.lang.String from,
                                                   java.lang.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 java.lang.String formatStackBetween​(java.lang.String from,
                                                   java.lang.String to,
                                                   boolean includeClass,
                                                   boolean includePackage,
                                                   java.lang.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 java.lang.String formatStackBetweenMatches​(java.lang.String from,
                                                          java.lang.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 java.lang.String formatStackBetweenMatches​(java.lang.String from,
                                                          java.lang.String to,
                                                          java.lang.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 java.lang.String formatStackBetweenMatches​(java.lang.String from,
                                                          java.lang.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 java.lang.String formatStackBetweenMatches​(java.lang.String from,
                                                          java.lang.String to,
                                                          boolean includeClass,
                                                          java.lang.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 java.lang.String formatStackBetweenMatches​(java.lang.String from,
                                                          java.lang.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 java.lang.String formatStackBetweenMatches​(java.lang.String from,
                                                          java.lang.String to,
                                                          boolean includeClass,
                                                          boolean includePackage,
                                                          java.lang.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 java.lang.String formatStackRange​(java.lang.String from,
                                                 java.lang.String to,
                                                 boolean isRegExp,
                                                 boolean includeClass,
                                                 boolean includePackage,
                                                 java.lang.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​(java.lang.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 java.lang.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 java.lang.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 java.lang.StackTraceElement[] getStack()
        access to the current stack frames
        Returns:
        an array of stack trace elements for the current stack
      • triggerIndex

        protected int triggerIndex​(java.lang.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​(java.lang.StackTraceElement[] stack,
                                 java.lang.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​(java.lang.StringBuffer buffer,
                                    java.lang.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​(java.lang.StringBuffer buffer,
                                  java.lang.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​(java.lang.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​(java.lang.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 java.lang.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