SourceDebugExtension Class File Attribute

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.

Timing

A solution is needed in Merlin (J2SE SDK 1.4) which is controlled by JSR-059.

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:

     An attribute added to the class file format
     Access to this attribute from each level of JPDA:
         JVMDI
         JDWP
         JDI

The SourceDebugExtension Attribute

The following attribute must be added to the Java Virtual Machine Specification.

The SourceDebugExtension attribute is an optional fixed-length 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;
        u2 debug_extension_index;
    }

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
     "SourceDebugExtension".

attribute_length
     The value of the attribute_length item of a
     SourceDebugExtension_attribute structure must be 2.

debug_extension_index
     The value of the debug_extension_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 a string.

     The string referenced by the debug_extension_index 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 must be 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 must be 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
     referenceTypeID
                  refType
                          The reference type ID.

Reply Data
     string
               sourceDebugExtension
                               The debug extension string.


JDI Method

The following method must be 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 and garbage collected.


robert.field@Eng 2000-11-20