Java Language Debug Interfaces Reference

Registration Interfaces
Notification Interfaces

Registration Interfaces

Use these interfaces to register Java classes for debugging and to receive notification when new Java processes are created.

IRemoteDebugManager : IUnknown

The IRemoteDebugManager interface provides access to all Java processes that are currently running. This interface also provides a way to debug new Java processes that are created.

IRemoteDebugManager::RegisterCallback

The RegisterCallback method is called by a debugger program to register a callback for receiving notification when new Java processes are created. The debugger must pass an interface to its own COM object that implements IRemoteDebugManagerCallback. The Microsoft Win32 Virtual Machine for Java (Microsoft VM) communicates with the debugger by calling various methods on this callback interface.

HRESULT RegisterCallback(IRemoteDebugManagerCallback *pCallback)

IRemoteDebugManager::Detach

The Detach method is called by a debugger program to detach its callback (IRemoteDebugManagerCallback) that was registered by some previous call to RegisterCallback. This method should be called before the debugger exits.

HRESULT Detach(void)

IRemoteDebugManager::GetActiveProcesses

This GetActiveProcesses method is used to return an interface to an enumerator object (IJavaEnumRemoteProcess) for all Java processes currently running in the Microsoft VM.

HRESULT GetActiveProcesses(IJavaEnumRemoteProcess **ppEnum)

IRemoteDebugManager::RequestCreateEvent

The RequestCreateEvent method notifies the Debug Manager in the Microsoft VM that a debugger program will be debugging a specific Java class. The debugger can specify a Java class name (for an applet or application) or request interest in debugging all Java classes. The debugger can also specify interest in Java classes run in a specific host Win32 process or any Win32 process.

HRESULT RequestCreateEvent(LPCOLESTR pcszProcessName,
     DWORD wParentProcessId)

The RequestCreateEvent method takes two parameters that allow the debugger to register to receive notifications of all new processes created, or in a specific process (a particular Java class) when it is created within a particular Win32 process. There are four possible combinations of these two parameters. The debugger can pass –1 for the process ID registering to receive notifications for any Win32 process. Any other value for the dwProcessID parameter indicates a specific Win32 process. The debugger can pass a zero-length string for the process name (Java class name) registering to receive notification of any Java process that is started. Any other value for the pcszProcessName parameter indicates a specific Java class name passed as a Unicode string.

IEnumRemoteProcess : IUnknown 

The IEnumRemoteProcess interface is used to enumerate all Java processes currently running in the Microsoft VM.

IEnumRemoteProcess::Next

The Next method is used to retrieve an array of IRemoteProcess objects that represent active Java processes. The number of Java processes to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

HRESULT Next(ULONG celt, IRemoteProcess *rgelt[], ULONG *pceltFetched)

IEnumRemoteProcess::Skip

The Skip method moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

IEnumRemoteProcess::Reset

The Reset method sets or resets the positions of the enumerator to the beginning of the list of Java processes.

HRESULT Reset(void)

IEnumRemoteProcess::Clone

The Clone method copies a pointer to the current position in the list to another enumerator object.

HRESULT Clone(IJavaEnumRemoteProcess **ppEnum)

IJavaEnumRemoteProcess : IEnumRemoteProcess

The IJavaEnumRemoteProcess interface is used to enumerate all Java processes currently running in the Microsoft VM.

IJavaEnumRemoteProcess::Next

The Next method is used to retrieve an array of IRemoteProcess objects that represent active Java processes. The number of Java processes to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

HRESULT Next(ULONG celt, IRemoteProcess *rgelt[], ULONG *pceltFetched)

IJavaEnumRemoteProcess::Skip

The Skip method moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

IJavaEnumRemoteProcess::Reset

The Reset method sets or resets the positions of the enumerator to the beginning of the list of Java processes.

HRESULT Reset(void)

IJavaEnumRemoteProcess::Clone

The Clone method copies a pointer to the current position in the list to another enumerator object.

HRESULT Clone(IJavaEnumRemoteProcess **ppEnum)

IJavaEnumRemoteProcess::GetNext

The GetNext method is used to retrieve the next IRemoteProcess object being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(IRemoteProcess **ppirp)

IRemoteProcess : IUnknown

An IRemoteProcess object represents a single Java process running within the Microsoft VM. Note that it does not represent the operating system process that the VM is being run in.

Once a debugger has obtained a list of active Java processes—either through enumeration or from receiving ProcessCreateEvent method calls—it can attach to and debug a specific Java process.

To debug a specific process, a debugger program must first register a callback to receive notifications and information from the Microsoft VM regarding that process. The IRemoteProcess object, another registration interface, is used for this task.

IRemoteProcess::RegisterCallback

The RegisterCallback method is called by a debugger program to register a callback that should receive notification and information regarding this active Java process. The debugger must pass an interface to its own COM object that implements IRemoteProcessCallback. This is the primary interface that the Microsoft VM communicates with the debugger. The VM sends information to the debugger regarding this process by calling various methods on this callback interface.

HRESULT RegisterCallback(IRemoteProcessCallback *pCallback)

IRemoteProcess::Detach

The Detach method is called by a debugger program to detach its callback (IRemoteProcessCallback) that was registered by some previous call to RegisterCallback.

HRESULT Detach(void)

IRemoteProcess::Break

The Break method issues a break on all threads in this Java process, resulting in all threads being stopped. This method is asynchronous, so threads will not necessarily stop immediately.

HRESULT Break(void)

IRemoteProcess::GetGlobalContainerObject

The GetGlobalContainer method returns a pointer to an IRemoteContainerObject, representing the root of all objects in this Java process. This method is usually used by a debugger to collect static information on all class objects in a Java process.

HRESULT GetGlobalContainerObject(IRemoteContainerObject **ppGlobalContainerObject)

IRemoteProcess::FindClass

The FindClass method is used to find a specific Java class. If the class isn't already loaded in the Java process, it’s loaded by the Microsoft VM.

HRESULT FindClass(LPCOLESTR pcszClassName, IRemoteClassField **ppClassType)

IRemoteProcess::TraceMethods

The TraceMethods method enables or disables IRemoteProcessCallback::TraceEvent callbacks used for notification of method calls when method call tracing is enabled. This method is being deprecated. Developers should use the newer Java Profiler interfaces.

HRESULT TraceMethods(BOOL bTraceOn)

IRemoteProcess::GetThreadGroups

The GetThreadGroups method returns an enumerator object (IJavaEnumRemoteThreadGroup) for all the thread groups in the Java process. This method is usually used by a debugger to collect dynamic information on all threads and class objects in a Java process.

HRESULT GetThreadGroups(IJavaEnumRemoteThreadGroup **ppEnum)

These interfaces are implemented by the debugger and are used to notify the debugger when new Java processes are created and when events occur on a specific Java process.

IRemoteDebugManagerCallback : IUnknown

This IRemoteDebugManager object is the initial callback through which the Microsoft VM communicates with the debugger. This callback must be registered by the debugger with the Java Debug Manager. This object has a single method that receives notification from the VM when new Java processes are created. The IRemoteDebugManager interface is used to notify the debugger when new Java processes are created. The debugger can register an interest in receiving these notifications on all Java processes or specific Java processes. An interest in only specific Java processes can be registered by Java class name and/or by a specific Win32 process (Win32 process ID). Notifications sent on this interface will only be for those processes that the Java debugger has registered an interest in.

IRemoteDebugManagerCallback::ProcessCreateEvent

The ProcessCreateEvent method notifies the debugger that a new Java process has been created and passes back a pointer to the IRemoteProcess object for this new Java class.

HRESULT ProcessCreateEvent(IRemoteProcess *pProcessNew,
     IRemoteProcess *pProcessParent)

IRemoteDebugManagerCallbackEx : IRemoteDebugManagerCallback

This IRemoteDebugManagerCallbackEx object is the initial callback through which the Microsoft VM communicates with the debugger. This callback must be registered by the debugger with the Java Debug Manager. This object inherits from and is a replacement for the IRemoteDebugManagerCallback object. This interface and is only necessary if the debugger wants to support Just-In-Time (JIT) debugging.

This object receives notification from the VM when new Java processes are created. The IRemoteDebugManagerEx interface is used to notify the debugger when new Java processes are created. The debugger can register an interest in receiving these notifications on all Java processes or specific Java processes. An interest in only specific Java processes can be registered by Java class name and/or by a specific Win32 process (Win32 process ID). Notifications sent on this interface will only be for those processes that the Java debugger has registered an interest in.

IRemoteDebugManagerCallbackEx::ProcessCreateEvent

The ProcessCreateEvent method notifies the debugger that a new Java process has been created and passes back a pointer to the IRemoteProcess object for this new Java class.

HRESULT ProcessCreateEvent(IRemoteProcess *pProcessNew,
     IRemoteProcess *pProcessParent)

IRemoteDebugManagerCallbackEx::StartClassEvent

The StartClassEvent method notifies the debugger regarding the Java class that the VM was started for. For example, if the VM was started with JView using the command line "JView Hello", the start class would be Hello.

HRESULT StartClassEvent(LPCOLESTR *pcstrStartClass)

IRemoteProcessCallback : IUnknown

The IRemoteProcessCallback object is the primary callback through which the VM communicates with the debugger and passes notifications and information requested concerning a specific Java process. No execution of the Java process occurs during the handling of these events. The debugger returns S_OK to leave execution suspended in the Java process, or S_FALSE to continue execution in the Java process. The pThread input argument to each event notification method is a thread object that represents the thread that generated the event.

When a Java process starts in the Microsoft VM, the debugger will be notified through its IRemoteDebugManagerCallback::ProcessCreateEvent method that a new Java process has been created. If the debugger decides to, it can register to receive notifications regarding this specific Java process. The IRemoteProcessCallback (or the IRemoteProcessCallbackEx) object is the primary way the Microsoft VM communicates with the debugger about a specific Java process. This callback has a large number of methods that must be implemented by the debugger.

IRemoteProcessCallback::DebugStringEvent

The DebugStringEvent method notifies the debugger when the Java process being debugged outputs a string.

HRESULT DebugStringEvent(IRemoteThread *pThread,
     LPCOLESTR pcszDebugString)

IRemoteProcessCallback::CodeBreakpointEvent

The CodeBreakpointEvent method notifies the debugger when a code breakpoint is hit by the Java process being debugged.

HRESULT CodeBreakpointEvent(IRemoteThread *pThread)

IRemoteProcessCallback::DataBreakpointEvent

The DataBreakpointEvent method notifies the debugger when a data breakpoint is hit by the Java process being debugged.

HRESULT DataBreakpointEvent(IRemoteThread *pThread,
     IRemoteObject *pObject)

IRemoteProcessCallback::ExceptionEvent

The ExceptionEvent method notifies the debugger when an exception occurs in the Java process being debugged.

HRESULT ExceptionEvent(IRemoteThread *pThread, IRemoteClassField *pExceptionClass,
     EXCEPTIONKIND exceptionKind)

typedef enum exceptionkind {
   EXCEPTION_KIND_FIRST_CHANCE   = 0x01,
   EXCEPTION_KIND_LAST_CHANCE   = 0x02,
} EXCEPTIONKIND;

IRemoteProcessCallback::StepEvent

The StepEvent method notifies the debugger when an execution step completes in the Java process being debugged.

HRESULT StepEvent(IRemoteThread *pThread)

IRemoteProcessCallback::CanStopEvent

The CanStopEvent method notifies the debugger during a range step when the Java process being debugged makes a function call.

HRESULT CanStopEvent(IRemoteThread *pThread)

IRemoteProcessCallback::BreakEvent

The BreakEvent method notifies the debugger when an asynchronous break occurs in response to the debugger calling IRemoteProcess:Break.

HRESULT BreakEvent(IRemoteThread *pThread)

IRemoteProcessCallback::ThreadCreateEvent

The ThreadCreateEvent method notifies the debugger when a thread is created.

HRESULT ThreadCreateEvent(IRemoteThread *pThread)

IRemoteProcessCallback::ThreadDestroyEvent

The ThreadDestroyEvent method notifies the debugger when a thread is destroyed.

HRESULT ThreadDestroyEvent(IRemoteThread *pThread)

IRemoteProcessCallback::ThreadGroupCreateEvent

The ThreadGroupCreateEvent method notifies the debugger when a thread group is created.

HRESULT ThreadGroupCreateEvent(IRemoteThread *pThread,
      IRemoteThreadGroup *pThreadGroup)

RemoteProcessCallback::ThreadGroupDestroyEvent

The ThreadGroupDestroyEvent method notifies the debugger when a thread group is destroyed.

HRESULT ThreadGroupDestroyEvent(IRemoteThread *pThread,
     IRemoteThreadGroup *pThreadGroup)

IRemoteProcessCallback::ClassLoadEvent

The ClassLoadEvent method notifies the debugger when a Java class is loaded and indicates the thread on which the class was loaded.

HRESULT ClassLoadEvent(IRemoteThread *pThread, IRemoteClassField *pClassType)

IRemoteProcessCallback:: LoadCompleteEvent

The LoadCompleteEvent method notifies the debugger when all Java class have been loaded.

HRESULT LoadCompleteEvent(IRemoteThread *pThread)

IRemoteProcessCallback::ClassUnloadEvent

The ClassUnloadEvent method notifies the debugger when a Java class has been unloaded.

HRESULT ClassUnloadEvent(IRemoteThread *pThread, IRemoteClassField *pClassType)

IRemoteProcessCallback::TraceEvent

The TraceEvent method notifies the debugger while tracing is enabled when a method is entered in a Java class. This method is being deprecated. Developers should use the newer Java Profiler interfaces.

HRESULT TraceEvent(IRemoteThread *pThread)

IRemoteProcessCallback::ProcessDestroyEvent

The ProcessDestroyEvent method notifies the debugger when a Java process terminates. No further notifications are sent to the debugger regarding this Java process after this method is called.

HRESULT ProcessDestroyEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx : IRemoteProcessCallback

The IRemoteProcessCallbackEx object is the primary callback through which the VM communicates with the debugger and passes notifications and information requested concerning a specific Java process. No execution of the Java process occurs during the handling of these events. The debugger returns S_OK to leave execution suspended in the Java process, or S_FALSE to continue execution in the Java process. The pThread input argument to each event notification method is a thread object that represents the thread that generated the event.

When a Java process starts in the Microsoft VM, the debugger will be notified through its IRemoteDebugManagerCallback::ProcessCreateEvent method that a new Java process has been created. If the debugger decides to, it can register to receive notifications regarding this specific Java process. The IRemoteProcessCallbackEx (or the IRemoteProcessCallback) object is the primary way the Microsoft VM communicates with the debugger about a specific Java process. This callback has a large number of methods that must be implemented by the debugger.

A debugger will normally implement either the IRemoteProcessCallback or the IRemoteProcessCallbackEx interface (which extends the former interface by adding one new method). The Microsoft VM senses which interface the debugger supports by calling QueryInterface on the callback object passed to IRemoteProcess::RegisterCallback.

IRemoteProcessCallbackEx::DebugStringEvent

The DebugStringEvent method notifies the debugger when the Java process being debugged outputs a string.

HRESULT DebugStringEvent(IRemoteThread *pThread, LPCOLESTR pcszDebugString)

IRemoteProcessCallbackEx::CodeBreakpointEvent

The CodeBreakpointEvent method notifies the debugger when a code breakpoint is hit by the Java process being debugged.

HRESULT CodeBreakpointEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::DataBreakpointEvent

The DataBreakpointEvent method notifies the debugger when a data breakpoint is hit by the Java process being debugged.

HRESULT DataBreakpointEvent(IRemoteThread *pThread, IRemoteObject *pObject)

IRemoteProcessCallbackEx::ExceptionEvent

The ExceptionEvent method notifies the debugger when an exception occurs in the Java process being debugged.

HRESULT ExceptionEvent(IRemoteThread *pThread, IRemoteClassField *pExceptionClass,
     EXCEPTIONKIND exceptionKind)

typedef enum exceptionkind {
   EXCEPTION_KIND_FIRST_CHANCE   = 0x01,
   EXCEPTION_KIND_LAST_CHANCE   = 0x02,
} EXCEPTIONKIND;

IRemoteProcessCallbackEx::StepEvent

The StepEvent method notifies the debugger when an execution step completes in the Java process being debugged.

HRESULT StepEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::CanStopEvent

The CanStopEvent method notifies the debugger during a range step when the Java process being debugged makes a function call.

HRESULT CanStopEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::BreakEvent

The BreakEvent method notifies the debugger when an asynchronous break occurs in response to the debugger calling IRemoteProcess:Break.

HRESULT BreakEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::ThreadCreateEvent

The ThreadCreateEvent method notifies the debugger when a thread is created.

HRESULT ThreadCreateEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::ThreadDestroyEvent

The ThreadDestroyEvent method notifies the debugger when a thread is destroyed.

HRESULT ThreadDestroyEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::ThreadGroupCreateEvent

The ThreadGroupCreateEvent method notifies the debugger when a thread group is created.

HRESULT ThreadGroupCreateEvent(IRemoteThread *pThread,
     IRemoteThreadGroup *pThreadGroup)

RemoteProcessCallbackEx::ThreadGroupDestroyEvent

The ThreadGroupDestroyEvent method notifies the debugger when a thread group is destroyed.

HRESULT ThreadGroupDestroyEvent(IRemoteThread *pThread,
     IRemoteThreadGroup *pThreadGroup)

IRemoteProcessCallbackEx::ClassLoadEvent

The ClassLoadEvent method notifies the debugger when a Java class is loaded and indicates the thread on which the class was loaded.

HRESULT ClassLoadEvent(IRemoteThread *pThread,
     IRemoteClassField *pClassType)

After a debugger registers an interest in a particular Java process (IRemoteProcess), it will begin to receive a large number of calls to its LoadClassEvent method for each class that was loaded before the debugger was attached. The debugger might receive over 100 calls for a typical Java process. These notifications to the debugger are initially made asynchronously by the Microsoft VM. After notifications are made for all the currently loaded classes, a LoadCompleteEvent is received. After this notification, any other ClassLoadEvent notifications are sent synchronously for the thread that caused the class to be loaded.

If the debugger returns S_OK from a ClassLoadEvent method, this Java process is suspended and class loading by the Microsoft VM becomes synchronous. The execution of the Java process can be resumed once the debugger calls IRemoteThread::Go. If the debugger returns S_FALSE from each ClassLoadEvent call, the process of loading Java classes continues.

IRemoteProcessCallbackEx:: LoadCompleteEvent

The LoadCompleteEvent method notifies the debugger when all Java classes have been loaded.

HRESULT LoadCompleteEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::ClassUnloadEvent

The ClassUnloadEvent method notifies the debugger when a Java class has been unloaded.

HRESULT ClassUnloadEvent(IRemoteThread *pThread,
     IRemoteClassField *pClassType)

IRemoteProcessCallbackEx::TraceEvent

The TraceEvent method notifies the debugger while tracing is enabled when a method is entered in a Java class. This method is being deprecated. Developers should use the newer Java Profiler interfaces.

HRESULT TraceEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::ProcessDestroyEvent

The ProcessDestroyEvent method notifies the debugger when a Java process terminates. No further notifications are sent to the debugger regarding this Java process after this method is called.

HRESULT ProcessDestroyEvent(IRemoteThread *pThread)

IRemoteProcessCallbackEx::StartClassEvent

The StartClassEvent method notifies the debugger regarding the Java class that the VM was started for. This method is only implemented by the IRemoteProcessCallbackEx object.

HRESULT StartClassEvent(IRemoteThread *pThread)