Package stdlib

Class Trace

java.lang.Object
stdlib.Trace
public class Trace extends Object

Traces the execution of a target program.

See http://fpl.cs.depaul.edu/jriely/visualization/

Command-line usage: java Trace [OptionalJvmArguments] fullyQualifiedClassName

Starts a new JVM (java virtual machine) running the main program in fullyQualifiedClassName, then traces it's behavior. The OptionalJvmArguments are passed to this underlying JVM.

Example usages: 

   java Trace MyClass
   java Trace mypackage.MyClass
   java Trace -cp ".:/pathTo/Library.jar" mypackage.MyClass  // mac/linux
   java Trace -cp ".;/pathTo/Library.jar" mypackage.MyClass  // windows

Two types of display are support: console and graphviz In order to use graphziv, you must install http://www.graphviz.org/ and perhaps call graphvizAddPossibleDotLocation to include the location of the "dot" executable.

You can either draw the state at each step --- drawSteps() --- or you can draw states selectively by calling Trace.draw() from the program you are tracing. See the example in ZTraceExample.java.

Classnames that end in "Node" are drawn using rounded rectangles by default. This does not work until the class is loaded; thus, null references may show up as inline fields for a while, until the class is loaded.

Author:
James Riely, jriely@cs.depaul.edu, 2014-2015

  • Method Details

    • drawObject

      public static void drawObject(Object object)
      Draw the given object. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • drawObjectWithName

      public static void drawObjectWithName(String name, Object object)
      Draw the given object, labeling it with the given name. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • drawObjects

      public static void drawObjects(Object... objects)
      Draw the given objects. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • drawObjectsWithNames

      public static void drawObjectsWithNames(Object... namesAndObjects)
      Draw the given objects, labeling them with the given names. The array of namesAndObjects must alternate between names and objects, as in Trace.drawObjects("x", x, "y" y). This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • drawThisFrame

      public static void drawThisFrame()
      Draw the current frame, as well as all reachable objects. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • drawStepsEnd

      public static void drawStepsEnd()
      Stop drawing steps. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger.

    • drawSteps

      public static void drawSteps()
      Start drawing steps. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger.

    • draw

      public static void draw()
      Draw all stack frames and static variables, as well as all reachable objects. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • drawAll

      public static void drawAll()
      Draw all stack frames and static variables, as well as all reachable objects, overriding showStaticClasses() if it is false. This is a stub method, which is trapped by the debugger. It only has an effect if a variant of Trace.run() has been called to start the debugger and Trace.drawSteps() is false.

    • graphvizRunGraphviz

      public static void graphvizRunGraphviz(boolean value)
      Run graphviz "dot" program to produce an output file (default==true). If false, a graphviz source file is created, but no graphic file is generated.

    • graphvizOutputFormat

      public static void graphvizOutputFormat(String value)
      The graphviz format -- see http://www.graphviz.org/doc/info/output.html . (default=="png").

    • setGraphizOutputDir

      public static void setGraphizOutputDir(String dirName)
      Sets the graphviz output directory. Creates the directory if necessary. Relative pathnames are interpreted with respect to the user's "Desktop" directory. Default is "GraphvizOutput".

    • setConsoleFilenameRelativeToUserDesktop

      public static void setConsoleFilenameRelativeToUserDesktop(String filename)
      Sets the console output to the given filename. Console output will be written to: 
       (user home directory)/(filename)

    • setConsoleFilename

      public static void setConsoleFilename(String filename)
      Sets the console output to the given filename.

    • setConsoleFilename

      public static void setConsoleFilename()
      Sets the console output to the default (the terminal).

    • showOnlyTopFrame

      public static void showOnlyTopFrame(boolean value)
      Run graphviz "dot" program to produce an output file (default==true). If false, a graphviz source file is created, but no graphic file is generated.

    • drawStepsOfMethod

      public static void drawStepsOfMethod(String methodName)
      Create a new graphviz drawing for every step of the named method. The methodName does not include parameters. In order to show a constructor, use the method name <init>.

    • drawStepsOfMethods

      public static void drawStepsOfMethods(String... methodName)
      Create a new graphviz drawing for every step of the named methods. The methodName does not include parameters. In order to show a constructor, use the method name <init>.

    • consoleShow

      public static void consoleShow(boolean value)
      Show events on the console (default==false).

    • consoleShowVerbose

      public static void consoleShowVerbose(boolean value)
      Show events on the console, including code (default==false).

    • showBuiltInObjects

      public static void showBuiltInObjects(boolean value)
      Show String, Integer, Double, etc as simplified objects (default==false).

    • showBuiltInObjectsVerbose

      public static void showBuiltInObjectsVerbose(boolean value)
      Show String, Integer, Double, etc as regular objects (default==false).

    • run

      public static void run()
      Run the debugger on the current class. Execution of the current program ends and a new JVM is started under the debugger. The debugger will execute the main method of the class that calls run. The main method is run with no arguments.

    • run

      public static void run(String[] args)

    • run

      public static void run(String mainClassName)
      Run the debugger on the given class. The current program will continue to execute after this call to run has completed. The main method of the given class is called with no arguments.

    • run

      public static void run(Class<?> mainClass)
      Run the debugger on the given class. The current program will continue to execute after this call to run has completed. The main method of the given class is called with no arguments.

    • run

      public static void run(String mainClassName, String[] args)
      Run the debugger on the given class. The current program will continue to execute after this call to run has completed. The main method of the given class is called with the given arguments.

    • run

      public static void run(Class<?> mainClass, String[] args)
      Run the debugger on the given class. The current program will continue to execute after this call to run has completed. The main method of the given class is called with the given arguments.

    • runWithArgs

      public static void runWithArgs(Class<?> mainClass, String... args)
      Run the debugger on the given class. The current program will continue to execute after this call to run has completed. The main method of the given class is called with the given arguments.

    • runWithArgs

      public static void runWithArgs(String mainClassName, String... args)
      Run the debugger on the given class. The current program will continue to execute after this call to run has completed. The main method of the given class is called with the given arguments.

    • main

      public static void main(String[] args)
      The debugger can be invoked from the command line using this method. The first argument must be the fully qualified name of the class to be debugged. Addition arguments are passed to the main method of the class to be debugged.

    • addPossibleSrcLocation

      public static void addPossibleSrcLocation(String value)
      Possible location of java source files. By default this includes "src" (for eclipse) and "src/main/java" (for maven).

    • addPossibleBinLocation

      public static void addPossibleBinLocation(String value)
      Possible location of binary class files. By default this includes the system classpath, "./bin" (for eclipse), "./target/classes" (for maven), and ".".

    • addPrefixOptionsForVm

      public static void addPrefixOptionsForVm(String value)
      Prefix options for the debugger VM. By default, the classpath is set to the current classpath. Other options can be provided here.

    • debug

      public static void debug(boolean value)
      Turn on debugging information (default==false). Intended for developers.

    • addExcludePattern

      public static void addExcludePattern(String value)
      Add an exclude pattern. Classes whose fully qualified name matches an exclude pattern are ignored by the debugger. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*". This limitation is inherited from com.sun.jdi.request.WatchpointRequest. The default exclude patterns include: 
        "*$$Lambda$*" "java.*" "jdk.*" "sun.*"  "com.*"  "org.*"  "javax.*"  "apple.*"  "Jama.*"  "qs.*"
  "stdlib.A*" "stdlib.B*" "stdlib.C*" "stdlib.D*" "stdlib.E*" "stdlib.F*" "stdlib.G*" "stdlib.H*" 
  "stdlib.I*" "stdlib.J*" "stdlib.K*" "stdlib.L*" "stdlib.M*" "stdlib.N*" "stdlib.O*" "stdlib.P*" 
  "stdlib.Q*" "stdlib.R*" "stdlib.S*" 
  "stdlib.U*" "stdlib.V*" "stdlib.W*" "stdlib.X*" "stdlib.Y*"
      The JDI excludes classes, but does not allow exceptions. This is the reason for the unusual number of excludes for stdlib. It is important that stdlib.Trace not be excluded --- if it were, then callBacks to Trace.draw would not function. As a result, all classes in stdlib that start with a letter other than T are excluded. Be careful when adding classes to stdlib. Exclude patterns must include 
        "*$$Lambda$*" "java.*" "jdk.*" "sun.*"
      otherwise the Trace code itself will fail to run.

    • removeExcludePattern

      public static void removeExcludePattern(String value)
      Remove an exclude pattern.
      See Also:

    • addDrawingIncludePattern

      public static void addDrawingIncludePattern(String value)
      Add an include pattern for drawing. These are classes that should be shown in drawing and console logs, which would otherwise be excluded. The default is: 
        "java.util.*"

    • removeDrawingIncludePattern

      public static void removeDrawingIncludePattern(String value)
      Remove an include pattern.
      See Also:

    • graphvizArrayBoxAttributes

      public static void graphvizArrayBoxAttributes(String value)
      Graphviz style for an array.

    • graphvizArrayArrowAttributes

      public static void graphvizArrayArrowAttributes(String value)
      Graphviz style for an arrow from an array to an Object.

    • graphvizFrameBoxAttributes

      public static void graphvizFrameBoxAttributes(String value)
      Graphviz style for a frame.

    • graphvizFrameObjectArrowAttributes

      public static void graphvizFrameObjectArrowAttributes(String value)
      Graphviz style for an arrow from a frame to an Object.

    • graphvizFrameReturnAttributes

      public static void graphvizFrameReturnAttributes(String value)
      Graphviz style for an arrow from a return value to a frame.

    • graphvizFrameExceptionAttributes

      public static void graphvizFrameExceptionAttributes(String value)
      Graphviz style for an arrow from an exception to a frame.

    • graphvizFrameFrameArrowAttributes

      public static void graphvizFrameFrameArrowAttributes(String value)
      Graphviz style for an arrow from a frame to another frame.

    • graphvizObjectBoxAttributes

      public static void graphvizObjectBoxAttributes(String value)
      Graphviz style for an object (non-array).

    • graphvizWrapperBoxAttributes

      public static void graphvizWrapperBoxAttributes(String value)
      Graphviz style for a wrapper object (in simple form).

    • graphvizNodeBoxAttributes

      public static void graphvizNodeBoxAttributes(String value)
      Graphviz style for a wrapper object (in simple form).

    • graphvizObjectArrowAttributes

      public static void graphvizObjectArrowAttributes(String value)
      Graphviz style for an arrow from an object to an object.

    • graphvizNodeArrowAttributes

      public static void graphvizNodeArrowAttributes(String value)
      Extra Graphviz style for an arrow from an non-node to a node object.

    • graphvizStaticClassBoxAttributes

      public static void graphvizStaticClassBoxAttributes(String value)
      Graphviz style for a static class.

    • graphvizStaticClassArrowAttributes

      public static void graphvizStaticClassArrowAttributes(String value)
      Graphviz style for an arrow from a static class to an object.

    • graphvizLabelBoxAttributes

      public static void graphvizLabelBoxAttributes(String value)
      Graphviz style for box labels.

    • graphvizLabelArrowAttributes

      public static void graphvizLabelArrowAttributes(String value)
      Graphviz style for arrow labels.

    • graphvizAddPossibleDotLocation

      public static void graphvizAddPossibleDotLocation(String value)
      Add a filesystem location to search for the dot executable that comes with graphviz. The default is system dependent.

    • graphvizRemoveGvFiles

      public static void graphvizRemoveGvFiles(boolean value)
      Remove graphviz files for which graphic files have been successfully generated.

    • graphvizAddNodeClass

      public static void graphvizAddNodeClass(String value)
      Add classname to be drawn as a simple oval, with null as a dot. Any classname with value as a suffix will be treated as a Node. Default value includes "Node".

    • graphvizRemoveNodeClass

      public static void graphvizRemoveNodeClass(String value)
      Remove a node class.
      See Also:

    • showNodesAsRegularObjects

      public static void showNodesAsRegularObjects()
      Remove all node classes.
      See Also:

    • showPackageInClassName

      public static void showPackageInClassName(boolean value)
      Show fully qualified class names (default==false). If showPackageInClassName is true, then showOuterClassInClassName is ignored (taken to be true).

    • showStaticClasses

      public static void showStaticClasses(boolean value)
      Show static classes (default==true).

    • showOuterClassInClassName

      public static void showOuterClassInClassName(boolean value)
      Include fully qualified class names (default==false).

    • consoleShowTypeInObjectName

      public static void consoleShowTypeInObjectName(boolean value)
      Show the object type in addition to its id (default==false).

    • consoleMaxFields

      public static void consoleMaxFields(int value)
      The maximum number of displayed fields when printing an object on the console (default==8).

    • consoleMaxArrayElementsPrimitive

      public static void consoleMaxArrayElementsPrimitive(int value)
      The maximum number of displayed elements when printing a primitive array on the console (default==15).

    • consoleMaxArrayElementsObject

      public static void consoleMaxArrayElementsObject(int value)
      The maximum number of displayed elements when printing an object array on the console (default==8).

    • consoleShowNestedArrayIds

      public static void consoleShowNestedArrayIds(boolean value)
      Show object ids inside multidimensional arrays (default==false).

    • showSyntheticFields

      public static void showSyntheticFields(boolean value)
      Show fields introduced by the compiler (default==true);

    • showSyntheticMethods

      public static void showSyntheticMethods(boolean value)
      Show methods introduced by the compiler (default==true);

    • showFilenamesOnConsole

      public static void showFilenamesOnConsole(boolean value)
      Show file names on the console (default==false).

    • showFieldNamesInLabels

      public static void showFieldNamesInLabels(boolean value)
      In graphviz, show field name in the label of an object (default==true).

    • showFieldNamesInNodeLabels

      public static void showFieldNamesInNodeLabels(boolean value)
      In graphviz, show field name in the label of a node object (default==false).

    • showFieldNamesInNodeArrows

      public static void showFieldNamesInNodeArrows(boolean value)
      In graphviz, show field name on the arrow of a node object (default==true).

    • showObjectIds

      public static void showObjectIds(boolean value)
      In graphviz, show object ids (default==false).

    • showObjectIdsRedundantly

      public static void showObjectIdsRedundantly(boolean value)
      In graphviz, show object ids and redundant variables for arrows (default==false). This also sets showBuiltInObjects to value.

    • showFrameNumbers

      public static void showFrameNumbers(boolean value)
      In graphviz, show stack frame numbers (default==true).

    • showNullFields

      public static void showNullFields(boolean value)
      In graphviz, show null fields (default==true).

    • showNullVariables

      public static void showNullVariables(boolean value)
      In graphviz, show null variables (default==true).

    • graphvizPutLineNumberInFilename

      public static void graphvizPutLineNumberInFilename(boolean value)
      Include line number in graphviz filename (default==true).

    • addGraphvizIgnoredFields

      public static void addGraphvizIgnoredFields(String value)
      Do not display any fields with this name (default includes only "$assertionsDisabled").

    • graphvizSetObjectAttribute

      public static void graphvizSetObjectAttribute(Class<?> cz, String attrib)
      Set the graphviz attributes for objects of the given class.

    • graphvizSetStaticClassAttribute

      public static void graphvizSetStaticClassAttribute(Class<?> cz, String attrib)
      Set the graphviz attributes for objects of the given class.

    • graphvizSetFrameAttribute

      public static void graphvizSetFrameAttribute(Class<?> cz, String attrib)
      Set the graphviz attributes for frames of the given class.

    • graphvizSetFieldAttribute

      public static void graphvizSetFieldAttribute(String field, String attrib)
      Set the graphviz attributes for all fields with the given name.