SourceDebugExtension

Motivation

Debugger applications frequently need debugging information about the source that exceeds what is delivered by the existing JavaTM Virtual Machine class file attributes (SourceFile, LineNumber, and LocalVariable). This is particularly true for debugging the source of other languages which are compiled to Java Virtual Machine bytecodes. In a distributed environment side files may not be accessible, the information must be directly associated with the class.

Solution

The solution is both simple and flexible - a class file attribute which holds a string is added; this string is made opaquely accessible at the three layers of the Java Platform Debugger Architecture (JPDA). The string contains debugging information in a standardized format which allows for evolution and vendor extension.

The remainder of this document describes these additions in detail:

The SourceDebugExtension Attribute

The SourceDebugExtension attribute is an optional attribute in the attributes table of the ClassFile structure. There can be no more than one SourceDebugExtension attribute in the attributes table of a given ClassFile structure.

The SourceDebugExtension attribute has the following format:


    SourceDebugExtension_attribute {      u2 attribute_name_index;      u4 attribute_length;      u1 debug_extension[attribute_length];     }
The items of the SourceDebugExtension_attribute structure are as follows:

attribute_name_index
The value of the attribute_name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing the string < code>"SourceDebugExtension".

attribute_length
The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes. The value of the attribute_length item is thus the number of bytes in the debug_extension[] item.

debug_extension[]
The debug_extension array holds a string, which must be in UTF-8 format. There is no terminating zero byte.

The string in the debug_extension item will be interpreted as extended debugging information. The content of this string has no semantic effect on the Java Virtual Machine.

JVMDI Function

The following function has been added to the Java Virtual Machine Debug Interface (JVMDI):
jvmdiError
GetSourceDebugExtension(jclass clazz, char **sourceDebugExtensionPtr)
For the class indicated by clazz, return the debug extension via sourceDebugExtensionPtr. The returned UTF-8 string contains exactly the debug extension information present in the class file of clazz.

Parameters:

clazz
the class to query
sourceDebugExtensionPtr
on return, refers to a pointer to the class's debug extension name (UTF-8). The returned debug extension string should be freed with Deallocate

This function returns either a universal error or one of the following errors:

JVMDI_ERROR_NULL_POINTER
Invalid pointer.

JVMDI_ERROR_INVALID_CLASS
Invalid clazz.

JVMDI_ERROR_ABSENT_INFORMATION
Class information does not include a debug extension.

JDWP Command

The following command has been added to the Java Debug Wire Protocol (JDWP) specification (in the ReferenceType command set):
SourceDebugExtension Command (12)
Returns the debug extension for this reference type.
Out Data
referenceTypeIDrefTypeThe reference type ID. 
Reply Data
stringsourceDebugExtensionThe debug extension string. 

JDI Method

The following method has been added to the Java Debug Interface (JDI) on ReferenceType:
sourceDebugExtension
public String sourceDebugExtension()
                  throws AbsentInformationException
Gets the debug extension string.
Returns:
the debug extension string
Throws:
AbsentInformationException - if the debug extension string is not specified
ObjectCollectedException - if this reference type has been unloaded.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. 

Please send comments to: java-debugger@sun.com 

Sun