stdlib

Class Trace

java.lang.Object

stdlib.Trace

public class Trace
extends java.lang.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.

Author:

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Trace.OptionalClassNameWithRequiredMethodName

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	BAD_ERROR_MESSAGE
private static java.lang.String	BIN_CLASSPATH
protected static java.lang.String	CALLBACK_CLASS_NAME
protected static java.lang.String	CALLBACK_CLEAR_CALL_TREE
protected static java.lang.String	CALLBACK_DRAW_ALL_FRAMES
protected static java.lang.String	CALLBACK_DRAW_OBJECT
protected static java.lang.String	CALLBACK_DRAW_OBJECT_NAMED
protected static java.lang.String	CALLBACK_DRAW_OBJECTS
protected static java.lang.String	CALLBACK_DRAW_OBJECTS_NAMED
protected static java.lang.String	CALLBACK_DRAW_STEPS_BEGIN
protected static java.lang.String	CALLBACK_DRAW_STEPS_END
protected static java.lang.String	CALLBACK_DRAW_STEPS_OF_METHOD
protected static java.lang.String	CALLBACK_DRAW_STEPS_OF_METHODS
protected static java.lang.String	CALLBACK_DRAW_THIS_FRAME
protected static java.util.HashSet<java.lang.String>	CALLBACKS
protected static int	CONSOLE_MAX_ARRAY_ELEMENTS_OBJECT
protected static int	CONSOLE_MAX_ARRAY_ELEMENTS_PRIMITIVE
protected static int	CONSOLE_MAX_FIELDS
protected static boolean	CONSOLE_SHOW_CALLS
protected static boolean	CONSOLE_SHOW_CLASSES
protected static boolean	CONSOLE_SHOW_NESTED_ARRAY_IDS
protected static boolean	CONSOLE_SHOW_STEPS
protected static boolean	CONSOLE_SHOW_STEPS_VERBOSE
protected static boolean	CONSOLE_SHOW_THREADS
protected static boolean	CONSOLE_SHOW_TYPE_IN_OBJECT_NAME
protected static boolean	CONSOLE_SHOW_VARIABLES
protected static boolean	DEBUG
protected static java.util.HashSet<java.lang.String>	DRAWING_INCLUDE_GLOBS
protected static java.util.HashSet<java.lang.String>	EXCLUDE_GLOBS
protected static java.lang.String	GRAPHVIZ_ARRAY_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_ARRAY_BOX_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_CALL_TREE_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_CALL_TREE_BOX_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_CLASS_NAME
private static java.lang.String	GRAPHVIZ_DIR
protected static java.lang.String	GRAPHVIZ_FRAME_BOX_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_FRAME_EXCEPTION_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_FRAME_FRAME_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_FRAME_OBJECT_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_FRAME_RETURN_ATTRIBUTES
protected static java.util.ArrayList<java.lang.String>	GRAPHVIZ_IGNORED_FIELDS
protected static java.lang.String	GRAPHVIZ_LABEL_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_LABEL_BOX_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_OBJECT_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_OBJECT_BOX_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_OUTPUT_FORMAT
protected static java.util.ArrayList<java.lang.String>	GRAPHVIZ_POSSIBLE_DOT_LOCATIONS
protected static boolean	GRAPHVIZ_PUT_LINE_NUMBER_IN_FILENAME
protected static boolean	GRAPHVIZ_REMOVE_GV_FILES
protected static boolean	GRAPHVIZ_RUN_GRAPHVIZ
protected static boolean	GRAPHVIZ_SHOW_BOXED_PRIMITIVES_SIMPLY
protected static boolean	GRAPHVIZ_SHOW_FIELD_NAMES_IN_LABELS
protected static boolean	GRAPHVIZ_SHOW_FILENAMES_ON_CONSOLE
protected static boolean	GRAPHVIZ_SHOW_FRAME_NUMBERS
protected static boolean	GRAPHVIZ_SHOW_NULL_FIELDS
protected static boolean	GRAPHVIZ_SHOW_NULL_VARIABLES
protected static boolean	GRAPHVIZ_SHOW_OBJECT_IDS
protected static boolean	GRAPHVIZ_SHOW_STEPS
protected static java.util.Set<Trace.OptionalClassNameWithRequiredMethodName>	GRAPHVIZ_SHOW_STEPS_OF
protected static java.lang.String	GRAPHVIZ_STATIC_CLASS_ARROW_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_STATIC_CLASS_BOX_ATTRIBUTES
protected static java.lang.String	GRAPHVIZ_WRAPPER_BOX_ATTRIBUTES
private static java.lang.String	IN_DEBUGGER Macintosh OS-X sometimes sets the hostname to an unroutable name and this may cause the socket connection to fail.
protected static java.util.ArrayList<java.lang.String>	PREFIX_ARGS_FOR_VM
private static boolean	REPRESS_RETURN_ON_GRAPHVIZ_SHOW_STEPS_OF
protected static boolean	SHOW_BOXED_PRIMITIVES_AS_PRIMITIVE
protected static boolean	SHOW_CALL_TREE
protected static boolean	SHOW_OUTER_CLASS_IN_CLASS_NAME
protected static boolean	SHOW_PACKAGE_IN_CLASS_NAME
protected static boolean	SHOW_STRINGS_AS_PRIMITIVE
protected static boolean	SHOW_SYNTHETIC_FIELDS
protected static boolean	SHOW_SYNTHETIC_METHODS

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Trace()

Method Summary

Modifier and Type	Method and Description
static void	addDrawingIncludePattern(java.lang.String value) Add an include pattern for drawing.
static void	addExcludePattern(java.lang.String value) Add an exclude pattern.
static void	addGraphvizIgnoredFields(java.lang.String value) Do not display any fields with this name (default includes only "$assertionsDisabled").
static void	addPrefixOptionsForVm(java.lang.String value) Prefix options for the debugger VM.
static void	clearCallTree() Clear the call tree, removing all previous entries.
static void	consoleMaxArrayElementsObject(int value) The maximum number of displayed elements when printing an object array on the console (default==8).
static void	consoleMaxArrayElementsPrimitive(int value) The maximum number of displayed elements when printing a primitive array on the console (default==15).
static void	consoleMaxFields(int value) The maximum number of displayed fields when printing an object on the console (default==8).
static void	consoleShow(boolean value) Show events on the console (default==false).
static void	consoleShowNestedArrayIds(boolean value) Show object ids inside multidimensional arrays (default==false).
static void	consoleShowTypeInObjectName(boolean value) Show the object type in addition to its id (default==false).
static void	consoleShowVerbose(boolean value) Show events on the console, including code (default==false).
static void	debug(boolean value) Turn on debugging information (default==false).
static void	draw() Draw all stack frames and static variables, as well as all reachable objects.
static void	drawCallTree(boolean value) When the debugged program ends, create a graphviz file showing the call tree (default==false).
static void	drawObject(java.lang.Object object) Draw the given object.
static void	drawObjects(java.lang.Object... objects) Draw the given objects.
static void	drawObjectsWithNames(java.lang.Object... namesAndObjects) Draw the given objects, labeling them with the given names.
static void	drawObjectWithName(java.lang.String name, java.lang.Object object) Draw the given object, labeling it with the given name.
static void	drawSteps() Start drawing steps.
static void	drawStepsEnd() Stop drawing steps.
protected static boolean	drawStepsOfInternal(java.util.List<com.sun.jdi.StackFrame> frames, com.sun.jdi.Value returnVal)
protected static boolean	drawStepsOfInternal(java.lang.String className, java.lang.String methodName)
protected static boolean	drawStepsOfInternal(com.sun.jdi.ThreadReference thr)
static void	drawStepsOfMethod(java.lang.String methodName) Create a new graphviz drawing for every step of the named method.
protected static void	drawStepsOfMethodBegin(java.lang.String methodName)
protected static void	drawStepsOfMethodEnd()
static void	drawStepsOfMethods(java.lang.String... methodName) Create a new graphviz drawing for every step of the named methods.
static void	drawThisFrame() Draw the current frame, as well as all reachable objects.
private static com.sun.jdi.connect.LaunchingConnector	getCommandLineConnector()
static void	graphvizAddPossibleDotLocation(java.lang.String value) Add a filesystem location to search for the dot executable that comes with graphviz.
static void	graphvizArrayArrowAttributes(java.lang.String value) Graphviz style for an arrow from an array to an Object.
static void	graphvizArrayBoxAttributes(java.lang.String value) Graphviz style for an array.
static void	graphvizCallTreeArrowAttributes(java.lang.String value) Graphviz style for a call tree arrow.
static void	graphvizCallTreeBoxAttributes(java.lang.String value) Graphviz style for a call tree node.
static void	graphvizFrameBoxAttributes(java.lang.String value) Graphviz style for a frame.
static void	graphvizFrameExceptionAttributes(java.lang.String value) Graphviz style for an arrow from an exception to a frame.
static void	graphvizFrameFrameArrowAttributes(java.lang.String value) Graphviz style for an arrow from a frame to another frame.
static void	graphvizFrameObjectArrowAttributes(java.lang.String value) Graphviz style for an arrow from a frame to an Object.
static void	graphvizFrameReturnAttributes(java.lang.String value) Graphviz style for an arrow from a return value to a frame.
static void	graphvizLabelArrowAttributes(java.lang.String value) Graphviz style for arrow labels.
static void	graphvizLabelBoxAttributes(java.lang.String value) Graphviz style for box labels.
static void	graphvizObjectArrowAttributes(java.lang.String value) Graphviz style for an arrow from an object to an object.
static void	graphvizObjectBoxAttributes(java.lang.String value) Graphviz style for an object (non-array).
static void	graphvizOutputFormat(java.lang.String value) The graphviz format -- see http://www.graphviz.org/doc/info/output.html .
static void	graphvizPutLineNumberInFilename(boolean value) Include line number in graphviz filename (default==true).
static void	graphvizRemoveGvFiles(boolean value) Remove graphviz files for which graphic files have been successfully generated.
static void	graphvizRunGraphviz(boolean value) Run graphviz "dot" program to produce an output file (default==true).
static void	graphvizSetFieldAttribute(java.lang.String field, java.lang.String attrib) Set the graphviz attributes for all fields with the given name.
static void	graphvizSetFrameAttribute(java.lang.Class<?> cz, java.lang.String attrib) Set the graphviz attributes for frames of the given class.
static void	graphvizSetObjectAttribute(java.lang.Class<?> cz, java.lang.String attrib) Set the graphviz attributes for objects of the given class.
static void	graphvizSetStaticClassAttribute(java.lang.Class<?> cz, java.lang.String attrib) Set the graphviz attributes for objects of the given class.
static void	graphvizStaticClassArrowAttributes(java.lang.String value) Graphviz style for an arrow from a static class to an object.
static void	graphvizStaticClassBoxAttributes(java.lang.String value) Graphviz style for a static class.
static void	graphvizWrapperBoxAttributes(java.lang.String value) Graphviz style for a wrapper object (in simple form).
private static boolean	insideTestVM()
private static void	internalPrepAndRun(java.lang.String mainClassName, java.lang.String[] args, boolean terminateAfter) Prepares the args and then calls internalRun.
private static void	internalRun(java.lang.String mainClassName, java.lang.String[] allArgs, boolean terminateAfter) This is the function that starts the JVM.
private static com.sun.jdi.VirtualMachine	launchConnect(java.lang.String[] args)
static void	main(java.lang.String[] args) The debugger can be invoked from the command line using this method.
private static void	monitorJVM(com.sun.jdi.VirtualMachine vm)
static void	removeDrawingIncludePattern(java.lang.String value) Add an include pattern.
static void	removeExcludePattern(java.lang.String value) Remove an exclude pattern.
static void	run() Run the debugger on the current class.
static void	run(java.lang.Class<?> mainClass) Run the debugger on the given class.
static void	run(java.lang.Class<?> mainClass, java.lang.String[] args) Run the debugger on the given class.
static void	run(java.lang.String mainClassName) Run the debugger on the given class.
static void	run(java.lang.String[] args) Run the debugger on the current class.
static void	run(java.lang.String mainClassName, java.lang.String[] args) Run the debugger on the given class.
static void	runWithArgs(java.lang.Class<?> mainClass, java.lang.String... args) Run the debugger on the given class.
static void	runWithArgs(java.lang.String mainClassName, java.lang.String... args) Run the debugger on the given class.
static void	setConsoleFilename() Sets the console output to the default (the terminal).
static void	setConsoleFilename(java.lang.String filename) Sets the console output to the given filename.
static void	setConsoleFilenameRelativeToUserHome(java.lang.String filename) Sets the console output to the given filename.
static void	setGraphizOutputDir(java.lang.String dirName) Sets the graphviz output directory.
private static java.util.Map<java.lang.String,com.sun.jdi.connect.Connector.Argument>	setMainArgs(com.sun.jdi.connect.LaunchingConnector conn, java.lang.String[] args)
static void	showBuiltInObjects(boolean value) Show String, Integer, Double, etc as simplified objects (default==false).
static void	showBuiltInObjectsVerbose(boolean value) Show String, Integer, Double, etc as regular objects (default==false).
static void	showFieldNamesInLabels(boolean value) In graphviz, show field name in the label of an object (default==true).
static void	showFilenamesOnConsole(boolean value) Show file names on the console (default==false).
static void	showFrameNumbers(boolean value) In graphviz, show stack frame numbers (default==true).
static void	showNullFields(boolean value) In graphviz, show null fields (default==true).
static void	showNullVariables(boolean value) In graphviz, show null variabels (default==true).
static void	showObjectIds(boolean value) In graphviz, show object ids (default==false).
static void	showOuterClassInClassName(boolean value) Include fully qualified class names (default==false).
static void	showPackageInClassName(boolean value) Show fully qualified class names (default==false).
static void	showSyntheticFields(boolean value) Show fields introduced by the compiler (default==true);
static void	showSyntheticMethods(boolean value) Show methods introduced by the compiler (default==true);

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CALLBACK_CLASS_NAME

protected static final java.lang.String CALLBACK_CLASS_NAME

GRAPHVIZ_CLASS_NAME

protected static final java.lang.String GRAPHVIZ_CLASS_NAME

CALLBACK_DRAW_OBJECT

protected static final java.lang.String CALLBACK_DRAW_OBJECT

See Also:

Constant Field Values

CALLBACKS

protected static final java.util.HashSet<java.lang.String> CALLBACKS

CALLBACK_DRAW_OBJECT_NAMED

protected static final java.lang.String CALLBACK_DRAW_OBJECT_NAMED

See Also:

Constant Field Values

CALLBACK_DRAW_OBJECTS

protected static final java.lang.String CALLBACK_DRAW_OBJECTS

See Also:

Constant Field Values

CALLBACK_DRAW_OBJECTS_NAMED

protected static final java.lang.String CALLBACK_DRAW_OBJECTS_NAMED

See Also:

Constant Field Values

CALLBACK_DRAW_THIS_FRAME

protected static final java.lang.String CALLBACK_DRAW_THIS_FRAME

See Also:

Constant Field Values

CALLBACK_DRAW_STEPS_END

protected static final java.lang.String CALLBACK_DRAW_STEPS_END

See Also:

Constant Field Values

CALLBACK_DRAW_STEPS_BEGIN

protected static final java.lang.String CALLBACK_DRAW_STEPS_BEGIN

See Also:

Constant Field Values

CALLBACK_DRAW_ALL_FRAMES

protected static final java.lang.String CALLBACK_DRAW_ALL_FRAMES

See Also:

Constant Field Values

CALLBACK_CLEAR_CALL_TREE

protected static final java.lang.String CALLBACK_CLEAR_CALL_TREE

See Also:

Constant Field Values

GRAPHVIZ_RUN_GRAPHVIZ

protected static boolean GRAPHVIZ_RUN_GRAPHVIZ

GRAPHVIZ_OUTPUT_FORMAT

protected static java.lang.String GRAPHVIZ_OUTPUT_FORMAT

GRAPHVIZ_DIR

private static java.lang.String GRAPHVIZ_DIR

GRAPHVIZ_SHOW_STEPS

protected static boolean GRAPHVIZ_SHOW_STEPS

CALLBACK_DRAW_STEPS_OF_METHOD

protected static final java.lang.String CALLBACK_DRAW_STEPS_OF_METHOD

See Also:

Constant Field Values

CALLBACK_DRAW_STEPS_OF_METHODS

protected static final java.lang.String CALLBACK_DRAW_STEPS_OF_METHODS

See Also:

Constant Field Values

GRAPHVIZ_SHOW_STEPS_OF

protected static java.util.Set<Trace.OptionalClassNameWithRequiredMethodName> GRAPHVIZ_SHOW_STEPS_OF

REPRESS_RETURN_ON_GRAPHVIZ_SHOW_STEPS_OF

private static boolean REPRESS_RETURN_ON_GRAPHVIZ_SHOW_STEPS_OF

CONSOLE_SHOW_THREADS

protected static boolean CONSOLE_SHOW_THREADS

CONSOLE_SHOW_CLASSES

protected static boolean CONSOLE_SHOW_CLASSES

CONSOLE_SHOW_CALLS

protected static boolean CONSOLE_SHOW_CALLS

CONSOLE_SHOW_STEPS

protected static boolean CONSOLE_SHOW_STEPS

CONSOLE_SHOW_STEPS_VERBOSE

protected static boolean CONSOLE_SHOW_STEPS_VERBOSE

CONSOLE_SHOW_VARIABLES

protected static boolean CONSOLE_SHOW_VARIABLES

SHOW_STRINGS_AS_PRIMITIVE

protected static boolean SHOW_STRINGS_AS_PRIMITIVE

SHOW_BOXED_PRIMITIVES_AS_PRIMITIVE

protected static boolean SHOW_BOXED_PRIMITIVES_AS_PRIMITIVE

GRAPHVIZ_SHOW_BOXED_PRIMITIVES_SIMPLY

protected static boolean GRAPHVIZ_SHOW_BOXED_PRIMITIVES_SIMPLY

IN_DEBUGGER

private static java.lang.String IN_DEBUGGER

Macintosh OS-X sometimes sets the hostname to an unroutable name and this may cause the socket connection to fail. To see your hostname, open a Terminal window and type the "hostname" command. On my machine, the terminal prompt is "$", and so the result looks like this:

   $ hostname
   escarole.local
   $
 

To see that this machine is routable, I can "ping" it:

   $ ping escarole.local
   PING escarole.local (192.168.1.109): 56 data bytes
   64 bytes from 192.168.1.109: icmp_seq=0 ttl=64 time=0.046 ms
   64 bytes from 192.168.1.109: icmp_seq=1 ttl=64 time=0.104 ms
   ^C
   --- escarole.local ping statistics ---
   2 packets transmitted, 2 packets received, 0.0% packet loss
   round-trip min/avg/max/stddev = 0.046/0.075/0.104/0.029 ms
 

When I am connected to some networks, the result is like this:

   $ hostname
   loop-depaulsecure-182-129.depaulsecure-employee.depaul.edu
   $ ping loop-depaulsecure-182-129.depaulsecure-employee.depaul.edu
   ping: cannot resolve loop-depaulsecure-182-129.depaulsecure-employee.depaul.edu: Unknown host
 

Or this:

   $ hostname
   asteelembook.cstcis.cti.depaul.edu
   $ ping asteelembook.cstcis.cti.depaul.edu
   PING asteelembook.cstcis.cti.depaul.edu (140.192.38.100): 56 data bytes
   Request timeout for icmp_seq 0
   Request timeout for icmp_seq 1
   ^C
   --- asteelembook.cstcis.cti.depaul.edu ping statistics ---
   3 packets transmitted, 0 packets received, 100.0% packet loss
 

To stop OS-X from taking bogus hostname like this, you can fix the hostname, as follows:

   $ scutil --set HostName escarole.local
   $
 

Where "escarole" is your computer name (no spaces or punctuation). You will be prompted for your password in order to modify the configuration. To reset OS-X to it's default behavior, do this:

   $ scutil --set HostName ""
   $
 

On OSX 10.10 (Yosemite), apple seems to have turned of DNS lookup for .local addresses. https://discussions.apple.com/thread/6611817?start=13 To fix this, you need to

 sudo vi /etc/hosts
 

and change the line

   127.0.0.1       localhost
 

to

   127.0.0.1       localhost escarole.local
 

More robustly, the following "patch" fixes the JDI so that it uses the ip address, rather than the hostname. The code is called from

 com.sun.tools.jdi.SunCommandLineLauncher.launch ()
 

which calls

 com.sun.tools.jdi.SocketTransportService.SocketListenKey.address ()
 

Here is the patch. Just compile this and put in your classpath before tools.jar.

 package com.sun.tools.jdi;

 import java.net.*;

 class SocketTransportService$SocketListenKey extends com.sun.jdi.connect.spi.TransportService.ListenKey {
     ServerSocket ss;
     SocketTransportService$SocketListenKey (ServerSocket ss) {
         this.ss = ss;
     }
     ServerSocket socket () {
         return ss;
     }
     public String toString () {
         return address ();
     }

     // Returns the string representation of the address that this listen key represents.
     public String address () {
         InetAddress address = ss.getInetAddress ();

         // If bound to the wildcard address then use current local hostname. In
         // the event that we don't know our own hostname then assume that host
         // supports IPv4 and return something to represent the loopback address.
         if (address.isAnyLocalAddress ()) {
             // JWR: Only change is to comment out the lines below
             // try {
             //     address = InetAddress.getLocalHost ();
             // } catch (UnknownHostException uhe) {
             byte[] loopback = { 0x7f, 0x00, 0x00, 0x01 };
             try {
                 address = InetAddress.getByAddress ("127.0.0.1", loopback);
             } catch (UnknownHostException x) {
                 throw new InternalError ("unable to get local hostname");
             }
             //  }
         }

         // Now decide if we return a hostname or IP address. Where possible
         // return a hostname but in the case that we are bound to an address
         // that isn't registered in the name service then we return an address.
         String result;
         String hostname = address.getHostName ();
         String hostaddr = address.getHostAddress ();
         if (hostname.equals (hostaddr)) {
             if (address instanceof Inet6Address) {
                 result = "[" + hostaddr + "]";
             } else {
                 result = hostaddr;
             }
         } else {
             result = hostname;
         }

         // Finally return "hostname:port", "ipv4-address:port" or "[ipv6-address]:port".
         return result + ":" + ss.getLocalPort ();
     }
 }
 

BIN_CLASSPATH

private static java.lang.String BIN_CLASSPATH

PREFIX_ARGS_FOR_VM

protected static java.util.ArrayList<java.lang.String> PREFIX_ARGS_FOR_VM

DEBUG

protected static boolean DEBUG

EXCLUDE_GLOBS

protected static java.util.HashSet<java.lang.String> EXCLUDE_GLOBS

DRAWING_INCLUDE_GLOBS

protected static java.util.HashSet<java.lang.String> DRAWING_INCLUDE_GLOBS

SHOW_CALL_TREE

protected static boolean SHOW_CALL_TREE

GRAPHVIZ_CALL_TREE_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_CALL_TREE_BOX_ATTRIBUTES

GRAPHVIZ_CALL_TREE_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_CALL_TREE_ARROW_ATTRIBUTES

GRAPHVIZ_ARRAY_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_ARRAY_BOX_ATTRIBUTES

GRAPHVIZ_ARRAY_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_ARRAY_ARROW_ATTRIBUTES

GRAPHVIZ_FRAME_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_FRAME_BOX_ATTRIBUTES

GRAPHVIZ_FRAME_OBJECT_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_FRAME_OBJECT_ARROW_ATTRIBUTES

GRAPHVIZ_FRAME_RETURN_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_FRAME_RETURN_ATTRIBUTES

GRAPHVIZ_FRAME_EXCEPTION_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_FRAME_EXCEPTION_ATTRIBUTES

GRAPHVIZ_FRAME_FRAME_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_FRAME_FRAME_ARROW_ATTRIBUTES

GRAPHVIZ_OBJECT_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_OBJECT_BOX_ATTRIBUTES

GRAPHVIZ_WRAPPER_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_WRAPPER_BOX_ATTRIBUTES

GRAPHVIZ_OBJECT_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_OBJECT_ARROW_ATTRIBUTES

GRAPHVIZ_STATIC_CLASS_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_STATIC_CLASS_BOX_ATTRIBUTES

GRAPHVIZ_STATIC_CLASS_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_STATIC_CLASS_ARROW_ATTRIBUTES

GRAPHVIZ_LABEL_BOX_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_LABEL_BOX_ATTRIBUTES

GRAPHVIZ_LABEL_ARROW_ATTRIBUTES

protected static java.lang.String GRAPHVIZ_LABEL_ARROW_ATTRIBUTES

GRAPHVIZ_POSSIBLE_DOT_LOCATIONS

protected static java.util.ArrayList<java.lang.String> GRAPHVIZ_POSSIBLE_DOT_LOCATIONS

GRAPHVIZ_REMOVE_GV_FILES

protected static boolean GRAPHVIZ_REMOVE_GV_FILES

SHOW_PACKAGE_IN_CLASS_NAME

protected static boolean SHOW_PACKAGE_IN_CLASS_NAME

SHOW_OUTER_CLASS_IN_CLASS_NAME

protected static boolean SHOW_OUTER_CLASS_IN_CLASS_NAME

CONSOLE_SHOW_TYPE_IN_OBJECT_NAME

protected static boolean CONSOLE_SHOW_TYPE_IN_OBJECT_NAME

CONSOLE_MAX_FIELDS

protected static int CONSOLE_MAX_FIELDS

CONSOLE_MAX_ARRAY_ELEMENTS_PRIMITIVE

protected static int CONSOLE_MAX_ARRAY_ELEMENTS_PRIMITIVE

CONSOLE_MAX_ARRAY_ELEMENTS_OBJECT

protected static int CONSOLE_MAX_ARRAY_ELEMENTS_OBJECT

CONSOLE_SHOW_NESTED_ARRAY_IDS

protected static boolean CONSOLE_SHOW_NESTED_ARRAY_IDS

SHOW_SYNTHETIC_FIELDS

protected static boolean SHOW_SYNTHETIC_FIELDS

SHOW_SYNTHETIC_METHODS

protected static boolean SHOW_SYNTHETIC_METHODS

GRAPHVIZ_SHOW_FILENAMES_ON_CONSOLE

protected static boolean GRAPHVIZ_SHOW_FILENAMES_ON_CONSOLE

GRAPHVIZ_SHOW_FIELD_NAMES_IN_LABELS

protected static boolean GRAPHVIZ_SHOW_FIELD_NAMES_IN_LABELS

GRAPHVIZ_SHOW_OBJECT_IDS

protected static boolean GRAPHVIZ_SHOW_OBJECT_IDS

GRAPHVIZ_SHOW_FRAME_NUMBERS

protected static boolean GRAPHVIZ_SHOW_FRAME_NUMBERS

GRAPHVIZ_SHOW_NULL_FIELDS

protected static boolean GRAPHVIZ_SHOW_NULL_FIELDS

GRAPHVIZ_SHOW_NULL_VARIABLES

protected static boolean GRAPHVIZ_SHOW_NULL_VARIABLES

GRAPHVIZ_PUT_LINE_NUMBER_IN_FILENAME

protected static boolean GRAPHVIZ_PUT_LINE_NUMBER_IN_FILENAME

GRAPHVIZ_IGNORED_FIELDS

protected static java.util.ArrayList<java.lang.String> GRAPHVIZ_IGNORED_FIELDS

BAD_ERROR_MESSAGE

protected static java.lang.String BAD_ERROR_MESSAGE

Constructor Detail

Trace

private Trace()

Method Detail

drawObject

public static void drawObject(java.lang.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(java.lang.String name,
                                      java.lang.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(java.lang.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(java.lang.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(java.lang.String value)

The graphviz format -- see http://www.graphviz.org/doc/info/output.html . (default=="png").

setGraphizOutputDir

public static void setGraphizOutputDir(java.lang.String dirName)

Sets the graphviz output directory. Creates the directory if necessary. Relative pathnames are interpreted with respect to the user's home directory. Default is "Desktop".

setConsoleFilenameRelativeToUserHome

public static void setConsoleFilenameRelativeToUserHome(java.lang.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(java.lang.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(java.lang.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(java.lang.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 "".

drawStepsOfMethodBegin

protected static void drawStepsOfMethodBegin(java.lang.String methodName)

drawStepsOfMethodEnd

protected static void drawStepsOfMethodEnd()

drawStepsOfInternal

protected static boolean drawStepsOfInternal(com.sun.jdi.ThreadReference thr)

drawStepsOfInternal

protected static boolean drawStepsOfInternal(java.util.List<com.sun.jdi.StackFrame> frames,
                                             com.sun.jdi.Value returnVal)

drawStepsOfInternal

protected static boolean drawStepsOfInternal(java.lang.String className,
                                             java.lang.String methodName)

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(java.lang.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(java.lang.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(java.lang.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(java.lang.String mainClassName,
                       java.lang.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(java.lang.Class<?> mainClass,
                       java.lang.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(java.lang.Class<?> mainClass,
                               java.lang.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(java.lang.String mainClassName,
                               java.lang.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(java.lang.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.

insideTestVM

private static boolean insideTestVM()

internalPrepAndRun

private static void internalPrepAndRun(java.lang.String mainClassName,
                                       java.lang.String[] args,
                                       boolean terminateAfter)

Prepares the args and then calls internalRun.

internalRun

private static void internalRun(java.lang.String mainClassName,
                                java.lang.String[] allArgs,
                                boolean terminateAfter)

This is the function that starts the JVM. If terminateAfter is true, then the current thread is killed after the debug JVM terminates.

addPrefixOptionsForVm

public static void addPrefixOptionsForVm(java.lang.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(java.lang.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(java.lang.String value)

Remove an exclude pattern.

See Also:

addExcludePattern

addDrawingIncludePattern

public static void addDrawingIncludePattern(java.lang.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(java.lang.String value)

Add an include pattern.

See Also:

addDrawingIncludePattern

drawCallTree

public static void drawCallTree(boolean value)

When the debugged program ends, create a graphviz file showing the call tree (default==false).

graphvizCallTreeBoxAttributes

public static void graphvizCallTreeBoxAttributes(java.lang.String value)

Graphviz style for a call tree node.

graphvizCallTreeArrowAttributes

public static void graphvizCallTreeArrowAttributes(java.lang.String value)

Graphviz style for a call tree arrow.

graphvizArrayBoxAttributes

public static void graphvizArrayBoxAttributes(java.lang.String value)

Graphviz style for an array.

graphvizArrayArrowAttributes

public static void graphvizArrayArrowAttributes(java.lang.String value)

Graphviz style for an arrow from an array to an Object.

graphvizFrameBoxAttributes

public static void graphvizFrameBoxAttributes(java.lang.String value)

Graphviz style for a frame.

graphvizFrameObjectArrowAttributes

public static void graphvizFrameObjectArrowAttributes(java.lang.String value)

Graphviz style for an arrow from a frame to an Object.

graphvizFrameReturnAttributes

public static void graphvizFrameReturnAttributes(java.lang.String value)

Graphviz style for an arrow from a return value to a frame.

graphvizFrameExceptionAttributes

public static void graphvizFrameExceptionAttributes(java.lang.String value)

Graphviz style for an arrow from an exception to a frame.

graphvizFrameFrameArrowAttributes

public static void graphvizFrameFrameArrowAttributes(java.lang.String value)

Graphviz style for an arrow from a frame to another frame.

graphvizObjectBoxAttributes

public static void graphvizObjectBoxAttributes(java.lang.String value)

Graphviz style for an object (non-array).

graphvizWrapperBoxAttributes

public static void graphvizWrapperBoxAttributes(java.lang.String value)

Graphviz style for a wrapper object (in simple form).

graphvizObjectArrowAttributes

public static void graphvizObjectArrowAttributes(java.lang.String value)

Graphviz style for an arrow from an object to an object.

graphvizStaticClassBoxAttributes

public static void graphvizStaticClassBoxAttributes(java.lang.String value)

Graphviz style for a static class.

graphvizStaticClassArrowAttributes

public static void graphvizStaticClassArrowAttributes(java.lang.String value)

Graphviz style for an arrow from a static class to an object.

graphvizLabelBoxAttributes

public static void graphvizLabelBoxAttributes(java.lang.String value)

Graphviz style for box labels.

graphvizLabelArrowAttributes

public static void graphvizLabelArrowAttributes(java.lang.String value)

Graphviz style for arrow labels.

graphvizAddPossibleDotLocation

public static void graphvizAddPossibleDotLocation(java.lang.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.

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).

showObjectIds

public static void showObjectIds(boolean value)

In graphviz, show object ids (default==false).

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 variabels (default==true).

graphvizPutLineNumberInFilename

public static void graphvizPutLineNumberInFilename(boolean value)

Include line number in graphviz filename (default==true).

addGraphvizIgnoredFields

public static void addGraphvizIgnoredFields(java.lang.String value)

Do not display any fields with this name (default includes only "$assertionsDisabled").

graphvizSetObjectAttribute

public static void graphvizSetObjectAttribute(java.lang.Class<?> cz,
                                              java.lang.String attrib)

Set the graphviz attributes for objects of the given class.

graphvizSetStaticClassAttribute

public static void graphvizSetStaticClassAttribute(java.lang.Class<?> cz,
                                                   java.lang.String attrib)

Set the graphviz attributes for objects of the given class.

graphvizSetFrameAttribute

public static void graphvizSetFrameAttribute(java.lang.Class<?> cz,
                                             java.lang.String attrib)

Set the graphviz attributes for frames of the given class.

graphvizSetFieldAttribute

public static void graphvizSetFieldAttribute(java.lang.String field,
                                             java.lang.String attrib)

Set the graphviz attributes for all fields with the given name.

launchConnect

private static com.sun.jdi.VirtualMachine launchConnect(java.lang.String[] args)

getCommandLineConnector

private static com.sun.jdi.connect.LaunchingConnector getCommandLineConnector()

setMainArgs

private static java.util.Map<java.lang.String,com.sun.jdi.connect.Connector.Argument> setMainArgs(com.sun.jdi.connect.LaunchingConnector conn,
                                                                                                  java.lang.String[] args)

monitorJVM

private static void monitorJVM(com.sun.jdi.VirtualMachine vm)