Package stdlib

Class 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 Detail

      • 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.
      • clearCallTree

        public static void clearCallTree()
        Clear the call tree, removing all previous entries. 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.
      • 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).
      • 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 "".
      • 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 "".
      • 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 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 the given arguments.
      • 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.
      • 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.
      • 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.*"
         
      • drawCallTree

        public static void drawCallTree​(boolean value)
        When the debugged program ends, create a graphviz file showing the call tree (default==false).
      • graphvizNodeArrowAttributes

        public static void graphvizNodeArrowAttributes​(String value)
        Extra Graphviz style for an arrow from an non-node to a node object.
      • 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".
      • 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).
      • 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").