Chapter 35

Package sun.tools.debug

CONTENTS

• RemoteArray
• RemoteBoolean
• RemoteByte
• RemoteChar
• RemoteClass
• RemoteDebugger
• RemoteDouble
• RemoteField
• RemoteFloat
• RemoteInt
• RemoteLong
• RemoteObject
• RemoteShort
• RemoteStackFrame
• RemoteStackVariable
• RemoteString
• RemoteThread
• RemoteThreadGroup
• RemoteValue
• StackFrame
• DebuggerCallback
• NoSessionException
• NoSuchFieldException
• NoSuchLineNumberException

The sun.tools.debug package contains the classes used for Java debugging and object inspection tools. The sun.tools.debug package's classes and interfaces are described in detail throughout the remainder of this chapter. Table 35.1 contains all the classes and interfaces that have public members. Figure 35.1 shows graphically the hierarchy of the contents of this package. The remainder of the chapter shows the member variables and methods of each class, interface, and exception in the sun.tools.debug package.

Figure 35.1: Contents of package sun.tools.debug.

RemoteArray

The class hierarchy for the RemoteArray class derives from class sun.tools.debug.RemoteObject. The RemoteArray class is provided to allow remote debugging of arrays. RemoteArray's overall derivation is shown in Figure 35.1 and its public members are shown in Listing 35.1.

Listing 35.1. Public members of sun.tools.debug.RemoteArray.

public class RemoteArray {
  public final int getSize()
  public String typeName()
  public String arrayTypeName(int type)
  public final int getElementType() throws Exception
  public final RemoteValue getElement(int index)
  Â throws ArrayIndexOutOfBoundsException
  public final RemoteValue[] getElements()
  Â throws ArrayIndexOutOfBoundsException
  public final RemoteValue[] getElements(int beginIndex, int endIndex)
  Â throws Exception
  public String description()
  public String toString()
}

public final int getSize()

The getSize() method is used to return the number of elements in the remote array.

An integer value representing the number of elements in the array.

public String typeName()

The typeName() method returns this RemoteValue object's type ("Array").

typeName() produces a String object corresponding to the RemoteValue object's type.

public String arrayTypeName(int type)

The arrayTypeName() method returns the element type as a string based on the specified integer type.

type is an integer value representing the element type (TC_chAR, for instance).

public final int getElementType() throws Exception

The getElementType() method returns the integer constant for the element type.

getElementType() returns an integer value representing the element type.

public final RemoteValue getElement(int index)
 throws ArrayIndexOutOfBoundsException

The getElement() method returns the RemoteValue at the array's specified index. For more information on the RemoteValue class, see the documentation later in this chapter.

Index is an integer value representing the index into the array.

public final RemoteValue[] getElements() throws ArrayIndexOutOfBoundsException

The getElements() method returns the contents of the array as an array of RemoteValue objects. For more information on the RemoteValue class, see the documentation later in this chapter.

getElements() creates an array of RemoteValue objects.

public final RemoteValue[] getElements(int beginIndex, int endIndex)
 throws ArrayIndexOutOfBoundsException

The getElements() method returns a subset of the contents of the array as an array of RemoteValue objects. For more information on the RemoteValue class, see the documentation later in this chapter.

beginIndex is an integer value representing the beginning element of the array to copy

to the RemoteValue array.

public String description()

The description() method returns a string description of the array.

description() produces a String object containing a description of the array.

public String toString()

The toString() method returns a string version of the array's contents.

toString() returns a String object containing a textual version of the array.

RemoteBoolean

The class hierarchy for the RemoteBoolean class derives from class sun.tools.debug.RemoteValue. The RemoteBoolean class is provided to allow remote debugging of Boolean values. RemoteBoolean's overall derivation is shown in Figure 35.1, and its public members appear in Listing 35.2.

Listing 35.2. Public members of sun.tools.debug.RemoteBoolean.

public class RemoteBoolean {
  public boolean get()
  public String typeName()
  public String toString()
 }

public boolean get()

The get() method returns the Boolean value of the RemoteBoolean object.

get() produces a Boolean value representing the value of the RemoteBoolean object.

public String typeName()

The typeName() method returns a String object containing the type name of the remote object.

typeName() produces a String object containing this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

toString() creates a String object containing a textual representation of this RemoteValue.

RemoteByte

The class hierarchy for the RemoteByte class derives from class sun.tools.debug.RemoteValue. The RemoteByte class is provided to allow remote debugging of byte values. RemoteByte's overall derivation is shown in Figure 35.1. Listing 35.3 shows its public members.

Listing 35.3. Public members of sun.tools.debug.RemoteByte.

public class RemoteByte {
  public byte get()
  public String typeName()
  public String toString()
 }

public byte get()

The get() method returns the byte value of the RemoteByte object.

get() produces a byte value representing the value of the RemoteByte object.

public String typeName()

The typeName() method returns a String object containing the type name of the remote object.

typeName() produces a String object containing this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

toString() creates a String object containing a textual representation of this RemoteValue.

RemoteChar

The class hierarchy for the RemoteChar class derives from class sun.tools.debug.RemoteValue. The RemoteBoolean class enables remote debugging of character values. RemoteChar's overall derivation is shown in Figure 35.1. Listing 35.4 shows its public members.

Listing 35.4. Public members of sun.tools.debug.RemoteChar.

public class RemoteChar {
  public char get()
  public String typeName()
  public String toString()
 }

public char get()

The get() method returns the character value of the RemoteChar object.

get() retrieves a char value representing the value of the RemoteChar object.

public String typeName()

The typeName() method returns a String object containing the type name of the remote object.

typeName() produces a String object containing this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

ToString() creates a String object containing a textual representation of this RemoteValue.

RemoteClass

The class hierarchy for the RemoteClass class derives from class sun.tools.debug.RemoteObject. The RemoteClass class enables remote debugging of class objects. RemoteClass's overall derivation is shown in Figure 35.1. Listing 35.5 shows its public members.

Listing 35.5. Public members of sun.tools.debug.RemoteClass.

public class RemoteClass {
  public String getName() throws Exception
  public String typeName() throws Exception
  public boolean isInterface() throws Exception
  public RemoteClass getSuperclass() throws Exception
  public RemoteObject getClassLoader() throws Exception
  public RemoteClass[] getInterfaces() throws Exception
  public String getSourceFileName()
  public InputStream getSourceFile() throws Exception
  public RemoteField[] getFields() throws Exception
  public RemoteField[] getStaticFields() throws Exception
  public RemoteField[] getInstanceFields() throws Exception
  public RemoteField getField(int n) throws ArrayIndexOutOfBoundsException
  public RemoteField getField(String name) throws Exception
  public RemoteField getInstanceField(int n)
   Â throws ArrayIndexOutOfBoundsException
  public RemoteValue getFieldValue(int n) throws Exception
  public RemoteValue getFieldValue(String name) throws Exception
  public RemoteField getMethod(String name) throws Exception
  public RemoteField[] getMethods() throws Exception
  public String[] getMethodNames() throws Exception
  public String setBreakpointLine(int lineno) throws Exception
  public String setBreakpointMethod(RemoteField method) throws Exception
  public String clearBreakpoint(int pc) throws Exception
  public String clearBreakpointLine(int lineno) throws Exception
  public String clearBreakpointMethod(RemoteField method) throws Exception
  public void catchExceptions() throws Exception
  public void ignoreExceptions() throws ClassCastException
  public String description()
  public String toString()
  }

public String getName() throws Exception

The getName() method returns the name of the remote class.

GetName() produces a String object containing the name of the class.

public String typeName() throws Exception

The typeName() method returns the name of the class as its type.

TypeName()produces a String object containing the type of the class.

public boolean isInterface() throws Exception

The isInterface() method is used to determine if the remote class is an interface.

IsInterface() returns a Boolean value that is true if the class is an interface, false if not.

public RemoteClass getSuperclass() throws Exception

The getSuperclass() method returns the superclass of the RemoteClass as a RemoteClass object.

getSuperclass() produces a RemoteClass object representing this RemoteClass's superclass.

public RemoteObject getClassLoader() throws Exception

The getClassLoader() method returns the classloader of the RemoteClass as a RemoteObject object.

getClassLoader() retrieves a RemoteObject object representing this RemoteClass's classloader.

public RemoteClass[] getInterfaces() throws Exception

The getInterfaces() method returns the interfaces of this RemoteClass as an array of RemoteClass objects.

GetInterfaces() creates an array of RemoteClass objects representing this RemoteClass's interfaces.

public String getSourceFileName()

The getSourceFileName() method returns the name of the source file referenced by this RemoteClass object.

getSourceFileName() produces a String object representing the name of the source file referenced by this RemoteClass object.

public InputStream getSourceFile() throws Exception

The getSourceFile() method returns the source file referenced by this RemoteClass object as an InputStream. For more information on the InputStream class, see the documentation in Chapter 31, "Package java.io."

getSourceFile() returns an InputStream representing this RemoteClass's source file.

public RemoteField[] getFields() throws Exception

The getFields() method returns all of the static fields of this object as an array of RemoteField objects. For more information on the RemoteField class, see the documentation later in this chapter.

GetFields() creates an array of RemoteField objects representing the fields of this RemoteClass object.

public RemoteField[] getStaticFields() throws Exception

The getStaticFields() method returns all the static fields of this object as an array of RemoteField objects. For more information on the RemoteField class, see the documentation later in this chapter.

GetStaticFields() creates an array of RemoteField objects representing the fields of this RemoteClass object.

An Exception if the fields could not be returned.

public RemoteField[] getInstanceFields() throws Exception

The getInstanceFields() method returns all of the instance fields of this object as an array of RemoteField objects. Because this is a RemoteClass method, only the name and type methods will be valid (not the data). For more information on the RemoteField class, see the documentation later in this chapter.

GetInstanceFields() creates an array of RemoteField objects representing the instance fields of this RemoteClass object.

public RemoteField getField(int n) throws ArrayIndexOutOfBoundsException

The getField() method returns the static field at the specified index of the RemoteClass. For more information on the RemoteField class, see the documentation later in this chapter.

n is an integer value representing the index of the field to be returned.

An Exception if the field at the specified index could not be returned.

public RemoteField getField(String name) throws Exception

The getField() method returns the static field using the specified field name. For more information on the RemoteField class, see the documentation later in this chapter.

name is a String object containing the name of the static field to be returned.

public RemoteField getInstanceField(int n) throws ArrayIndexOutOfBoundsException

The getInstanceField() method returns the instance field at the specified index of the RemoteClass. For more information on the RemoteField class, see the documentation later in this chapter.

n is an integer value representing the index of the field to be returned.

public RemoteValue getFieldValue(int n) throws Exception

The getFieldValue() method returns the RemoteValue of the static field at the specified index. For more information on the RemoteValue class, see the documentation later in this chapter.

n is an integer value representing the index of the field to be returned.

public RemoteValue getFieldValue(String name) throws Exception

The getFieldValue() method returns the RemoteValue of the static field using the specified name. For more information on the RemoteValue class, see the documentation later in this chapter.

name is a String object representing the name of the static field whose value will be returned.

public RemoteField getMethod(String name) throws Exception

The getMethod() method returns the method using the specified method name. For more information on the RemoteField class, see the documentation later in this chapter.

name is a String object representing the name of the method to be returned.

public RemoteField[] getMethods() throws Exception

The getMethods() method returns all of a class's methods in an array of RemoteField objects. For more information on the RemoteField class, see the documentation later in this chapter.

getMethods() produces an array of RemoteField objects representing all of the RemoteClass's methods.

public String[] getMethodNames() throws Exception

The getMethodNames() returns an array containing the names of the RemoteClass's methods.

getMethodNames() creates an array of String objects containing the name of the RemoteClass's methods.

public String setBreakpointLine(int lineno) throws Exception

The setBreakpointLine() method sets a breakpoint at the specified line number of the RemoteClass.

lineno is an integer value representing the line number at which to set the breakpoint.

public String setBreakpointMethod(RemoteField method) throws Exception

The setBreakpointMethod() method sets the breakpoint at the first line of a class method specified by the RemoteField parameter. For more information on the RemoteField class, see the documentation later in this chapter.

method is a RemoteField object specifying the method at which to set the breakpoint.

public String clearBreakpoint(int pc) throws Exception

The clearBreakpoint() method clears the breakpoint at the specified class address.

pc is an integer value representing the class address at which to clear the breakpoint.

public String clearBreakpointLine(int lineno) throws Exception

The clearBreakpointLine() method clears the breakpoint at the specified line number.

lineno is an integer value representing the line number at which to clear the breakpoint.

public String clearBreakpointMethod(RemoteField method) throws Exception

The clearBreakpointMethod() method is used to clear a breakpoint for a specified method. For more information on the RemoteField class, see the documentation later in this chapter.

method is a RemoteField object specifying the method at which to clear the breakpoint.

public void catchExceptions() throws ClassCastException

The catchExceptions() method enters the debugger when an instance of this class is thrown.

A ClassCastException if this RemoteClass isn't an exception class.

ignoreExceptions

RemoteClass

public void ignoreExceptions() throws ClassCastException

The ignoreExceptions() method prevents the entering of the debugger when an instance of this class is thrown.

A ClassCastException if this RemoteClass isn't an exception class.

public String description()

The description() method returns a String description of the class. This method overrides the description() method in class RemoteObject.

Description() produces a String object that describes the remote class.

public String toString()

The toString() method returns a String description of the class.

A String object that describes the remote class.

RemoteDebugger

The class hierarchy for the RemoteDebugger class derives from class java.lang.Object. The RemoteDebugger class is provided to define a client interface to the Java debugging classes. RemoteDebugger's overall derivation is shown in Figure 35.1, and its members appear in Listing 35.6.

Listing 35.6. Public members of sun.tools.debug.RemoteDebugger.

public class RemoteDebugger {
  public RemoteDebugger(String host, String password, DebuggerCallback client,
      Â boolean verbose) throws Exception
  public RemoteDebugger(String javaArgs, DebuggerCallback client,
      Â boolean verbose) throws Exception
  public void close()
  public RemoteObject get(Integer id)
  public RemoteClass[] listClasses() throws Exception
  public RemoteClass findClass(String name) throws Exception
  public RemoteThreadGroup[] listThreadGroups(RemoteThreadGroup tg)
      Â throws Exception
  public void gc(RemoteObject save_list[]) throws Exception
  public void trace(boolean traceOn) throws Exception
  public void itrace(boolean traceOn) throws Exception
  public int totalMemory() throws Exception
  public int freeMemory() throws Exception
  public RemoteThreadGroup run(int argc, String argv[]) throws Exception
  public String[] listBreakpoints() throws Exception
  public String[] getExceptionCatchList() throws Exception
  public String getSourcePath() throws Exception
  public void setSourcePath(String pathList) throws Exception
}

public RemoteDebugger(String host, String password, DebuggerCallback client,
 boolean verbose) throws Exception

This RemoteDebugger() constructor creates a RemoteDebugger object using the Java interpreter and the specified host, password, and client method.

host is a String object that contains the name of the host where the debuggable Java instance is running.

public RemoteDebugger(String javaArgs, DebuggerCallback client,
 boolean verbose) throws Exception

This RemoteDebugger() constructor is used to create a RemoteDebugger object using a new client interpreter.

JavaArgs is a String object containing optional Java command-line parameters.

public void close()

The close() method closes the connection to the remote debugging tool.

None.

public RemoteObject get(Integer id)

The get() method retrieves an object from the remote debugging object store.

id is the remote object's identification number.

public RemoteClass[] listClasses() throws Exception

The listClasses() method lists the currently known classes.

An array of RemoteClass objects. For more information on the RemoteClass class, see the documentation earlier in this chapter.

public RemoteClass findClass(String name) throws Exception

The findClass() method returns the specified RemoteClass. For more information on the RemoteClass class, see the documentation earlier in this chapter.

name is a String object specifying the name of the remote class to be returned.

public RemoteThreadGroup[] listThreadGroups(RemoteThreadGroup tg)
 throws Exception

The listThreadGroups() method returns either part or all of the RemoteThreadGroup objects available.

tg is the thread group that holds the groups to be listed or null for all of the thread groups.

public void gc(RemoteObject save_list[]) throws Exception

The gc() method frees all objects referenced by the debugger except for those objects specified to save.

Save_list is an array of RemoteObject objects that are not to be deleted by the gc() method. For more information on the RemoteObject class, see the documentation later in this chapter.

public void trace(boolean traceOn) throws Exception

The trace() method allows call tracing to be turned on or off.

TraceOn is a Boolean value that is true if tracing is to be turned on, false if tracing is to be turned off.

public void itrace(boolean traceOn) throws Exception

The itrace() method allows instruction tracing to be turned on or off.

TraceOn is a Boolean value that is true if tracing is to be turned on, false if it is to be turned off.

public int totalMemory() throws Exception

The totalMemory() returns the total memory usage of the Java interpreter being debugged.

An integer value representing the total number of bytes being used by the Java interpreter.

public int freeMemory() throws Exception

The freeMemory() method returns the free memory that is available to the Java interpreter being debugged.

An integer value representing the number of free memory bytes available to the Java interpreter being debugged.

public RemoteThreadGroup run(int argc, String argv[]) throws Exception

The run() method loads and runs a Java class using the specified parameters. The Java interpreter being debugged creates a new thread group to run the class inside.

argc is an integer value representing the number of arguments passed to the interpreter.

public String[] listBreakpoints() throws Exception

The listBreakpoints() method returns a list of the breakpoints that are currently set.

An array of String objects containing the class and line number for each breakpoint that is currently set.

An Exception if the list of breakpoints cannot be retrieved.

public String[] getExceptionCatchList() throws Exception

The getExceptionCatchList() method returns the list of exceptions that the debugger will halt on.

An array of String objects that represent exception class names.

public String getSourcePath() throws Exception

The getSourcePath() method returns a String object containing the source file path that the debugging agent is currently using.

A String object containing the source file path.

public void setSourcePath(String pathList) throws Exception

The setSourcePath() method uses the specified pathList to set the source file path used by the debugging agent.

PathList is a String object containing a list of colon-delimited paths for use by the debugging agent.

RemoteDouble

The class hierarchy for the RemoteDouble class derives from class sun.tools.debug.RemoteValue. The RemoteDouble class enables remote debugging of double values. RemoteDouble's overall derivation is shown in Figure 35.1. Listing 35.7 shows its public members.

Listing 35.7. Public members of sun.tools.debug.RemoteDouble.

public class RemoteDouble {
  public double get()
  public String typeName()
  public String toString()
 }

public double get()

The get() method returns the double value of the RemoteDouble object.

A double value representing the value of the RemoteDouble object.

public String typeName()

The typeName() method returns a String object containing the type name of the remote object.

A String object containing this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

A String object containing a textual representation of this RemoteValue.

RemoteField

The class hierarchy for the RemoteField class derives from class sun.tools.debug.Field. The RemoteField class enables remote debugging of field values of an object in a Java interpreter. RemoteField's overall derivation is shown in Figure 35.1. Listing 35.8 shows its public members.

Listing 35.8. Public members of sun.tools.debug.RemoteField.

public class RemoteField {
  public String getName()
  public String getType()
  public String getModifiers()
  public boolean isStatic()
  public String toString()
 }

public String getName()

The getName() method returns a string containing the field's name.

A String object that contains the field's name.

public String getType()

The getType() method returns a String object containing information about the field's type.

A String object that describes the field.

public String getModifiers()

The getModifiers() method returns a string containing information about the field.

A String object that contains the field's modifiers.

public boolean isStatic()

The isStatic() method can be called to determine whether or not the field is static.

A Boolean value that is true if the field is static, false if not.

public String toString()

The toString() method returns a textual representation of the field.

A String object that represents the value of this RemoteField.

RemoteFloat

The class hierarchy for the RemoteFloat class derives from class sun.tools.debug.RemoteValue. The RemoteFloat class allows remote debugging of float values. RemoteFloat's overall derivation appears in Figure 35.1 and its public members in Listing 35.9.

Listing 35.9. Public members of sun.tools.debug.RemoteFloat.

public class RemoteFloat {
  public float get()
  public String typeName()
  public String toString()
 }

public float get()

The get() method returns the float value of the RemoteFloat object.

A float value representing the value of the RemoteFloat object.

public String typeName()

The typeName() method returns a String object containing the type name of the remote object.

A String object containing this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

A String object containing a textual representation of this RemoteValue.

RemoteInt

The class hierarchy for the RemoteInt class derives from class sun.tools.debug.RemoteValue. The RemoteInt class allows remote debugging of int values. RemoteInt's overall derivation appears in Figure 35.1. Listing 35.10 shows its public members.

Listing 35.10. Public members of sun.tools.debug.RemoteInt.

public class RemoteInt {
  public int get()
  public String typeName()
  public String toString()
 }

public int get()

The get() method returns the int value of the RemoteInt object.

An int value representing the value of the RemoteInt object.

public String typeName()

The typeName() method returns a String object containing the type name of the remote object.

A String object that contains this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

A String object that contains a textual representation of this RemoteValue.

RemoteLong

The class hierarchy for the RemoteLong class derives from class sun.tools.debug.RemoteValue. The RemoteLong class allows remote debugging of long values. RemoteLong's overall derivation is shown in Figure 35.1. Listing 35.11 shows its public members.

Listing 35.11. Public members of sun.tools.debug.RemoteLong.

public class RemoteLong {
  public long get()
  public String typeName()
  public String toString()
 }

public long get()

The get() method returns the long value of the RemoteLong object.

A long value representing the value of the RemoteLong object.

public String typeName()

The typeName() method returns a String object that contains the type name of the remote object.

A String object containing this RemoteValue's type.

public String toString()

The toString() method returns a string representation of this RemoteValue.

A String object that contains a textual representation of this RemoteValue.

RemoteObject

The class hierarchy for the RemoteObject class derives from class sun.tools.debug.RemoteValue. The RemoteObject class enables remote debugging of objects. RemoteObject's overall derivation appears in Figure 35.1. Listing 35.12 shows its public members.

Listing 35.12. Public members of sun.tools.debug.RemoteObject.

public class RemoteObject {
  public String typeName() throws Exception
  public final int getId()
  public final RemoteClass getClazz()
  public RemoteValue getFieldValue(int n) throws Exception
  public RemoteValue getFieldValue(String name) throws Exception
  public RemoteField[] getFields() throws Exception
  public RemoteField getField(int n) throws Exception
  public RemoteField getField(String name) throws Exception
  public String description()
  public String toString()
  }

public String typeName() throws Exception

The typeName() method returns the RemoteObject's type name.

A String value that contains the RemoteObject's type name ("Object").