The debugger interfaces assist in the detection, location, and correction of logical or syntactical errors in Java applications, applets, and COM objects that are run in the Microsoft virtual machine (Microsoft VM). These interfaces can also be used for debugging Java code that mixes Java classes with native Microsoft® Win32® code.
This overview contains the following topics:
Enabling Debugging in the Microsoft VM describes the ways to enable debugging by means of registry settings and environment variables.
Enumerating Debuggable Service Processes describes how to allow enumeration of all debuggable Java service processes.
Registering with the Debugger Manager provides the basics of registration interface methods.
Implementing Callback Notification Interfaces introduces the concept of notification interfaces, pointers to which the debugger passes to the debugger manager.
Retrieving Static Information discusses the cacheable class and class member information available through the IRemoteField hierarchy of interfaces.
Retrieving Dynamic Information discusses the non-cacheable information available through the IRemoteObject hierarchy of interfaces.
Controlling Execution explains the interfaces that provide access to the Java method call stacks of the threads executing in the Java process being debugged.
The debugger interfaces are Component Object Model (COM) objects and interfaces. A debugger application communicates with the Microsoft VM and controls the Java execution environment by accessing these COM objects and interfaces. You can extend debugger programs to allow remote debugging using Distributed COM (DCOM). You can write debugger programs in Java by using the classes in the com.ms.debug package. These classes provide wrapped COM interfaces.
The debugger requests information and communicates with the Microsoft VM by calling methods on COM objects implemented by the VM. Similarly, the Microsoft VM runtime notifies the debugger program of events, and provides requested information to the debugger by calling methods on COM objects that the debugger implements. The debugger registers its callbacks by calling register callback methods IRemoteDebugManagerCallbackEx and IRemoteProcessCallbackEx2.
The COM objects implemented by the Microsoft VM use a consistent method pattern to handle lists of similar objects. Various Getxx methods (GetContainer, GetSuperClass, and so on) allow the debugger program to move up the object hierarchy. Many of the Getxx methods return an enumerator object. These different enumerator objects (for processes, threads, fields, and so on) implement a nearly identical set of methods, based on the common COM IEnumXXXX enumerator paradigm. The enumeration methods allow the debugger program to move down the object hierarchy. The IEnumXXXX methods return an array of objects, skip some number of objects, reset the enumerator to the beginning of the list, or create a copy (clone) of the current enumerator.
Any memory that the Microsoft VM allocates as an output parameter from a debug interface method (an [out] parameter as documented in the reference section on the debugger interfaces) is allocated using the CoTaskMemAlloc function. When this memory is no longer needed by the debugger, it must be released using the CoTaskMemFree function.
If the debugger program continues to use a COM object that was created as output parameters from a method, the reference count for that object may need to be incremented to ensure that the object remains viable for the duration of the debugger’s use. This can be accomplished by calling the object's AddRef method. The debugger program decrements the reference count on the object using the Release method when the object is no longer needed.
The debugger interfaces use the apartment-threading model. The Microsoft VM uses a single apartment thread to dispatch all debugger events
The examples in the following topics use C++ and local COM objects to illustrate the use of the debugger interfaces. One sample is written in C++ using these debugger interfaces. A second example is written in Java using the com.ms.debug package, which consists of a set of Java-wrapped classes for these COM interfaces. These samples are installed under the %SDKDIR%\Samples\Debugger subdirectory of the Microsoft SDK for Java. For more information about other samples in this SDK, see the Samples Overview.
To use these debugger interfaces, enable debugging in the Microsoft VM through environment variables or Win32 registry settings.
The debugger interfaces are categorized as shown in the following table.
Category | Purpose |
Registration Interfaces | Register the debugger program with the Microsoft VM and request to be notified when specific events occur. |
Notification Interfaces | Notify the debugger of various events and return requested information. |
Static Information Interfaces | Gather static information about the Java code. |
Dynamic Information Interfaces | Gather dynamic information about a Java process when it is executing. |
Execution Control Interfaces | Control the execution of a Java process. |
Debugging and Profiling Java Applications