About the Microsoft Virtual Machine

Welcome
Release Notes
Download the SDK
Articles
Packages
Tools
Microsoft VM
AFC
J/Direct
Java & Native Code
Package Manager
Security
Internationalization

Microsoft VM | Welcome!
 | Welcome!

About the Microsoft Virtual Machine

The Microsoft Win32 Virtual Machine (VM) for Java provides a variety of APIs that give ISVs and tools vendors access to the VM's underlying features. This information is especially useful if you are developing Java development tools for use with the Microsoft VM for Java.

Microsoft VM for Java Object Model
Describes the benefits of the VM Object Model as it applies to object decomposition and performance.
Java Debugger Interfaces
Describes the debugging APIs provided by the Microsoft VM for Java. Use these to implement your Java debugger.
Java Language Debug Reference Overview
This topic provides details about registration, notification, static information, and dynamic information interfaces.
Invocation Interfaces
Describes the invocation APIs provided by the VM.
Just-In-Time Compilation and the Microsoft VM for Java
Describes the Just-In-Time (JIT) compiler used by the Microsoft VM for Java for improved performance.
Overview of the COM Attributes for Java Class Files
Describes the extended Microsoft COM attributes.
Release Notes for Microsoft VM
Provides general information and details about what is supported by the Microsoft VM.
Package com.ms.vm
Describes the com.ms.vm package.


Introduction

The following sections describe the benefits of the object model as it applies to object decomposition and performance.
Goals of the Object Model
Object Components


Goals of the Object Model

This object model facilitates efficient decomposition of objects into their member components. It enhances operational performance by providing very fast and deterministic access to multiply inherited interface members (abstract members and constant fields) and singly inherited virtual methods, while conforming to the current Java language and VM specification.

The Microsoft VM Object Model also provides very low per-object overhead while still containing information required for distinguishing between objects and arrays, synchronizing objects through monitors and Wait and Notify functionality. This additional information is allocated in a "lazy" fashion, requiring additional overhead only as necessary.

Operations that this model optimizes include:

  • Fast resolution of an object's interface vtables, which you can use to access interface methods quickly and efficiently.
  • Accessing data fields in the object.
  • Accessing virtual methods of the class or interface hierarchy.
  • Entering an object's monitor.
  • Blocking a thread on an object until that object has been "notified."


Object Components

In the Microsoft VM for Java, a class is a description of an object type that includes declarations of data and method members. Classes can inherit all types of members from parent classes including constants (static final fields), static fields and methods that exist once for all instances of a class in one namespace and are shared between instances, dynamic fields that exist separately in every instance of the class type, and dynamic methods that operate on specific instances of a class through a "this" pointer.

Interfaces declare only abstract, dynamic methods, constants fields, and properties (which you can think of as "virtual fields"). The methods declared in an interface can be implemented only in a class, not in an interface. When a class implements an interface, it is guaranteed to contain an implementation for every method in that interface, and all interfaces that the interface extends.

This object model specifies layout of the following object components.

  • Synchronization block
  • Methods
  • Interfaces
  • Dynamic fields

When a base interface is loaded, vtables are created for its member methods, fields, and interfaces that it extends. The field tables are simply arrays of the field description structures; methods also are described by arrays of methods descriptions, but have vtables associated with them that can be accessed by indexes that remain constant throughout the hierarchy of a class.

When a base class is loaded, the Microsoft VM creates tables just as with interfaces for its member fields and methods. The class vtable differs from an interface vtable only in that its header contains the number of interface slots found below the object, and a pointer to the actual class descriptor that owns the vtable. These elements are followed by interface vtables and then by method pointers which are not declared in any of the implemented interfaces. Method pointers are pointers to the native Just-In-Time (JIT) code entry points or a native interpreter stub (call compatible with JIT code) of methods implemented in the class or its superclasses. An interface vtable consists simply of an array of methods.

Now that you know what a vtable looks like, look at how it is used in the context of creating an object—treating it as an instance of one of its superclasses, or treating it as an instance of one of its implemented interfaces.

The following example class contains one field and one method. The class, "foo", looks like the following:

public class foo {

public int Field1;

    void Method1()  {}
}

Normally, a Java-compatible compiler will create a constructor for this class, and the object will inherit methods from the Object class. For the purpose of this example, pretend that all you get is one field, Field1, and one method, Method1. The vtable for this class would look like:

An object of type foo would contain space for Field1, a main vtable pointer, and a pointer to the synchronization block. Note that the synchronization block for an object is not really present unless it is used. It is created "lazily" to conserve space in nonsynchronized objects. The vtable exists only once per class and is shared among objects of that class type, but the synchronization block is per instance.

The following illustration shows an object of type foo.

If you declare two interfaces, IFCA and IFCB, IFCA contains one method, Method2; IFCB contains two methods, Method3 and Method4. If you then declare another class, "bar", which extends foo and implements IFCA and IFCB, you get an object that looks like the following illustration.

An interface's vtable is simply an array of Just-In-Time–compiled, code-callable methods. If an interface extends other interfaces, it has those interface vtables inside it. When the Microsoft VM for Java resolves an object that implements an interface, that interface vtable is copied to the main vtable when it is encountered. The nested interface offsets are calculated by adding their offsets in the implemented interface to the current position in the new vtable.

Since some aspects of the object model used internally in the Microsoft VM for Java are subject to change, all data structures besides the object data itself should be considered abstract and accessed only through functions available in Java.


Introduction

The following sections describe the debugging APIs provided by the Microsoft Win32 VM for Java.


Java Language Debug Reference

Working with MS VM

Microsoft VM | Previous | VM | Next
Java Language Debug Interfaces | Previous | VM | Next

Overview

The Java debug interfaces allow developers to write sophisticated programs for debugging Java applications and applets run in the Microsoft Win32 Virtual Machine for Java (Microsoft VM). These interfaces can also be used for debugging Java applications and applets that mix Java classes with native code for Win32.

The Java debug interfaces consist of a series of Component Object Model (COM) objects and interfaces implemented by the Microsoft VM. A debugger application is usually written in C, C++, or some other language that can access these published COM interfaces and objects for communicating with the Microsoft VM and control the Java execution environment. A debugger program written to use these COM interfaces must also implement two COM interfaces that are used as callback interfaces through which the Microsoft VM communicates with the debugger. Because these debug interfaces are all based on COM, debugger programs can be easily extended to allow remote debugging using Distributed COM (DCOM). These debug interfaces are also provided as wrapped COM interfaces in Java as a set of classes under the com.ms.debug package, enabling developers to write debugger programs in Java as well as C++. For simplicity, the examples that follow are written using C++ and local COM objects to illustrate the use of the Java debug interfaces.

To use these Java debug interfaces, debugging must be enabled in the Microsoft VM before the Java application or applet begins its execution. Debugging can be enabled in the Microsoft VM through particular environment variables or with Win32 registry settings.

The debug interfaces used by the Microsoft VM can be organized into several categories as shown in the following table.

Category | Purpose
Registration | Interfaces called by the debugger program to register with the Microsoft VM and request to be notified when specific events occur.
Notification | Callback interfaces that must be implemented by the debugger through which the Microsoft VM notifies the debugger of various events and returns requested information.
Static Information | Interfaces used by the debugger program to gather static information about the Java application or applet.
Dynamic Information | Interfaces used by the debugger program to gather dynamic information about the Java application or applet when it is executing.
Execution Control | Interfaces used by the debugger program to control the execution of a Java application or applet within the Microsoft VM.

The Microsoft VM includes sample code for two debugger applications that illustrate how to use these Java debug interfaces. One sample is written in C++ using these 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 interface objects. These samples are installed under the Samples\Debugger subdirectory of the SDK for Java.


Using the Java Debug Interfaces

The following sections describe in detail how to use the Java debug interfaces. They include discussion of the following topics:

General Considerations when Using the Java Debug Interfaces
Enabling Debugging in the Microsoft VM
Registering with the Java Debug Manager
Enumerating Active Java Processes
Registering with a Remote Process
Implementing Callback Notification Interfaces
Retrieving Static Information
Enumerating Static Fields
Enumerating Line Number Information
Retrieving Dynamic Information
Enumerating Dynamic Fields
Controlling Execution
Enumerating Thread Groups, Threads, and Stack Frames
Controlling Execution with Remote Threads
Accessing Call Stacks

General Considerations when Using the Java Debug Interfaces

The Java debug interfaces consist of a large collection of COM objects with many methods. The design of many of these interfaces and methods, however, follow a consistent design pattern.

Communication between the debugger and the VM is handled through COM interfaces. The debugger requests information and communicates with the VM by calling methods on COM objects implemented by the VM. Similarly, the Microsoft VM runtime notifies the debugger program of events, and then and provides the requested information by calling methods on COM objects that the debugger implements. The debugger registers these callbacks by calling a register callback method.

The COM objects implemented by the Microsoft VM use consistent class factory and get methods to handle lists of similar objects. 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. These methods support returning an array of objects, skipping some number of objects, resetting the enumerator to the beginning of the list, copying the current enumerator position to another object (cloning), and getting only the next object.

The Java debug interfaces use a consistent hierarchy of objects. The enumeration methods allow the debugger program to move down the hierarchy of objects. Various Getxx methods (GetContainer, GetSuperClass, and so on) allow the debugger program to move up the hierarchy.

Because the Java debug interfaces are based on COM, some general considerations apply when calling the interfaces that are implemented by the Microsoft VM.

Any memory that a debugger program allocates for use as a buffer that is passed as a parameter to any of these COM interfaces (an [in,out] or an [out] parameter as documented in the reference section on the Java debug interfaces) must be allocated using the CoTaskMemAlloc function. When this memory is no longer needed, it must be released using the CoTaskMemFree function. This is a COM requirement because the memory is being allocated across processes. It is also a necessity for DCOM compatibility.

If the debugger program continues to use any COM objects that are created as parameters to 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 method call. This can be accomplished by calling the Addref method on the COM interface. The debugger program decrements the reference count on the object using the Release method when this object is no longer needed.

Enabling Debugging in the Microsoft VM

For the Java debug interfaces to be used, debugging must be enabled in the Microsoft VM before the Java application or applet begins execution. Debugging can be enabled in the Microsoft VM for Java in two ways:

  • Defining particular environment variables

  • Creating particular Win32 registry settings

The preferred method to enable debugging is to set special environment variables before starting the Microsoft VM (before launching Microsoft® Internet Explorer, for example) and executing the Java application or applet. Note that the value of these environment variables (when set) override the equivalent settings in the registry. The environment variables that may be used by a debugger are shown in the following table.

Environment Variable | Description and Values
MSJAVA_ENABLE_DEBUGGING | Enables debugging when set to some value greater than 0. Valid values must be less than the value of a GUID.
MSJAVA_DEBUGGING_FLAGS | Specifies options for debugging, most of which deal with issues when debugging a mixture of native code and Java.
MSJAVA_ENABLE_FI | Enables the fast interpreter when set to some value that is non-zero. If this environment variable is not set and the equivalent registry value is not set, the fast interpreter is enabled by default.
MSJAVA_ENABLE_JIT | Enables the Just-In-Time (JIT) compiler when set to some value that is non-zero. If this environment variable is not set and the equivalent registry value is not set, JIT is enabled by default.

If the MSJAVA_ENABLE_DEBUGGING string exists in the Win32 environment space and is set to some value greater than 0 for a process, debugging is enabled in any Microsoft VM that subsequently begins executing within this environment.

If the MSJAVA_DEBUGGING_FLAGS string exists in the Win32 environment space, the value it is set to specifies a set of options that control special features of the Microsoft VM. These options can be a combination of the following.

Option | Value | Description
MSJDBG_AD2_DEBUGGING | 0x04 | When set, this enables additional semantics, enabling some new Java interfaces and changing the behavior of some older Java interfaces.
MSJDBG_NO_HARDWARE_BREAKPOINTS | 0x08 | When set, this notifies the Microsoft VM that hardware breakpoints should not be used on Microsoft® Windows NT® being run on Intel processors. If this value and the following value are not set, data breakpoints are available. When using a native debugger, such as Microsoft® Visual C++®, set this value. This option is ignored on DEC alpha systems running Windows NT. Hardware breakpoints are not used on Microsoft® Windows 95®.
MSJDBG_NO_PAGE_BREAKPOINTS | 0x10 | When set, this notifies the Microsoft VM that memory page faults for data breakpoints should not be used (applies to both Microsoft® Windows 95 and Windows NT being run on Intel processors). If this value and the previous value are not set, data breakpoints are available. When using Visual C++ for debugging, set this value. This option is ignored on DEC alpha systems running Windows NT.
MSJDBG_ENABLE_JIT_COMPILED_CODE_DEBUGGING | 0x40 | When set, this notifies the Microsoft VM that Just-In-Time (JIT) code debugging is disabled.

Debugging can also be enabled and debug options can be configured through the use of registry settings on Windows 95 and Windows NT. The registry settings that affect the Microsoft VM when used with these debug interfaces are located under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM

Note the presence of a space between Java and VM in this registry node.

Under this node, the following entries and values may be entered or modified.

Debug

When this key exists before the Microsoft VM begins execution, debugging will be enabled.

DebuggingFlags

Set the value of this entry to a DWORD that indicates the value of the debug options.

MSDebug

When this key exists before the Microsoft VM begins execution, active debugging (AD2) will be enabled.

By default, when the Microsoft VM is installed, these registry entries are not created.

HKEY_LOCAL_MACHINE\CurrentUser\Software\Microsoft\Java VM

Note the presence of a space between Java and VM in this registry node.

Under this node, the following entries and values may be entered or modified.

EnableFI

Set the value of this entry to a DWORD that indicates whether the fast interpreter is enabled. A non-zero value enables the fast interpreter, while a value of zero disables this feature. The default value for this option is enabled.

EnableJIT

Set the value of this entry to a DWORD that indicates whether the Just-In-Time (JIT) compiler is enabled. A non-zero value enables the JIT compiler, while a value of zero disables this feature. The default value for this option is enabled.

EnableJitCompiledCodeDebugging

Set the value of this entry to a DWORD that indicates whether Just-In-Time (JIT) code debugging is enabled. A non-zero value enables JIT code debugging, while a value of zero disables this feature. The default value for this option is enabled. By default, when the Microsoft VM is installed, these registry entries are not created. Registry settings can be set using code similar to the following:

const char s_cszDebugKey[] = "Software\\Microsoft\\Java VM\\Debug";

// Create the Microsoft VM Debug key; return TRUE on success.
static BOOL CreateDebugKey(void)
{
    BOOL bResult;
    DWORD dwDisposition;
    HKEY hkeyDebug;

    bResult = ( RegCreateKeyEx(HKEY_LOCAL_MACHINE, s_cszDebugKey, 0,
                NULL, 0, KEY_WRITE, NULL, &hkeyDebug, &dwDisposition)
                == ERROR_SUCCESS);

    if (bResult) RegCloseKey(hkeyDebug);

    return(bResult);
}

Exercise caution when using these registry settings for enabling use of the Java debug interfaces because these settings will affect all Java applications and applets started under the Microsoft VM. Enabling debugging disables certain optimizations in the Microsoft VM and requires more resources to be used. This option may disable the JIT compiler and invoke a slower than usual version of the Java bytecode interpreter, which will slow down the execution of all Java applications and applets. If the Debug registry entry is not explicitly removed when debugging is no longer needed, the execution performance of all Java applications and applets will be adversely affected. Registry settings can be removed using code similar to the following.

// Delete the Microsoft VM Debug key; return TRUE is successful.
static BOOL DeleteDebugKey(void)
{
    return ( RegDeleteKey(HKEY_LOCAL_MACHINE, s_cszDebugKey) ==
           ERROR_SUCCESS);
}

Registry entries can also be removed or modified using the regedit.exe utility that is included with Windows 95 and Windows NT.

Registering with the Java Debug Manager

To use the Java debug interfaces, a debugger program must call specific methods of the registration interfaces implemented by the Microsoft VM. Its registration interfaces are implemented as follows.

Registration Interfaces | Inherits From | Description
IRemoteDebugManager | IUnknown | This object manages all the processes that can be debugged and connects a debugger program to them when requested. This COM object must be initialized first before any other registration interfaces are used. The debugger program must then call the RegisterCallback method on this object's interface to provide a callback through which the Microsoft VM communicates with the debugger.
IEnumRemoteProcess | IUnknown | This object allows a debugger to enumerate all Java processes currently running in the Microsoft VM.
IJavaEnumRemoteProcess | IEnumRemoteProcess | This object inherits from the IEnumRemoteProcess interface (adds one new method) and allows a debugger to enumerate all Java processes currently running in the Microsoft VM.
IRemoteProcess | IUnknown | The interface pointer to this object represents a single Java process running within the Microsoft VM. Note that this object does not represent the Win32 operating system process that the Microsoft VM is being run in.
IRemoteProcessEx | IRemoteProcess | The interface pointer to this object represents a single Java process running within the Microsoft VM. Note that this object does not represent the Win32 operating system process that the Microsoft VM is being run in. This interface inherits from IRemoteProcess and adds one new method.

To register with the Microsoft VM, an application must first call the COM library function CoCreateInstance or CoCreateInstanceEx, passing in the class identifier (CLSID) of the debug manager, CLDID_RemoteJavaDebugManager, and interface identifier (IID) of the IRemoteDebugManager interface. CoCreateInstanceEx takes an additional parameter that specifies the host for use with DCOM. The COM library then uses the CLSID to find the entry for this object’s class in the system registry and starts the appropriate COM server.

The CLSID for the IRemoteDebugManager is defined in the JDbgGUID.h file. The IID for the IRemoteDebugManager object and the other Java debug interfaces are defined in the JavaDbg.h file that is installed in the Include directory of the SDK for Java. The JavaDbg.h include file also contains function prototypes for the methods supported by these interfaces.

The following sample code illustrates how these functions might be used to start a local server.

#include <JavaDbg.h>
#include <JDbgGUID.h

    HRESULT hr;
    hr = CoInitialize(NULL);   // Initialize OLE on this thread.

    if (SUCCEEDED(hr)) {
        IRemoteDebugManager *pirdm;

        // Create a RemoteJavaDebugManager to initiate debugging.

        hr = CoCreateInstance(CLSID_RemoteJavaDebugManager, NULL,
                              CLSCTX_LOCAL_SERVER,
                              IID_IRemoteDebugManager,
                              (PVOID *)&pirdm);

        if (hr == S_OK) {
            // Continue working if okay.
        }
        // Uninitialize OLE on this thread when done.
        CoUninitialize();

The debugger program must then register with the Debug Manager in the Microsoft VM, passing its own callback interface pointer through which this virtual machine will communicate with the debugger. The callback functions provided by the debugger must be implemented as methods on COM objects that represent the Notification interfaces, which will be addressed later in this topic.

The IRemoteDebugManager interface implements the following methods that may be called by a debugger.

Method | Description
RegisterCallback | The debugger program calls this method to provide 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 VM communicates with the debugger by calling various methods on this callback interface.
Detach | The debugger program calls this method to detach its callback (IRemoteDebugManagerCallback) that was attached by some previous call to RegisterCallback. Call this method before the debugger exits.
GetActiveProcesses | This method is used to return an interface to an enumerator object (IJavaEnumRemoteProcess) for all the Java processes currently running in the Microsoft VM.
RequestCreateEvent | This 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 an 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.

Once an interface pointer to IRemoteDebugManager object has been obtained, the debugger program must call the RegisterCallback method on this interface. The following code illustrates registering a callback in a sample Initialize method of a Java debugger class.

// Initialize is passed. The interface pointer to
//    IRemoteDebugManager is called.
HRESULT JavaDebugger::Initialize(IRemoteDebugManager *pirdm)
{
    HRESULT hr;

    // Register this JavaDebugger's IRemoteDebugManagerCallback with the
    // debug manager so it can be notified when new processes are run.

    hr = pirdm->RegisterCallback(this);

    if (hr == S_OK) {
        m_pirdm = pirdm;
        m_pirdm->AddRef();    // Increment the reference count.
    }
    return(hr);
}

Once a debugger has registered its callback interface, it can request that it be notified when new Java processes are started. The debugger calls the RequestCreateEvent method of the IRemoteDebugManager interface to request being informed when the Microsoft VM creates new Java processes. 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.

The sample code below illustrates registering an interest to receive all process create events.

// Ask the debug manager to notify us when any Java class is run.
HRESULT hr;
DWORD dwProcessID = -1;             // For any Win32 process ID,
                                    // use –1.
LPCOLESTR pcszProcessName = ""; // Zero-length string for all processes.

hr = m_pirdm->RequestCreateEvent(&pcszProcessName, dwProcessID);

At this point, a Java applet or application that is to be debugged can be started. If the Java application or applet was previously started using the Win32 CreateProcess function was in a suspended state, it can now be resumed. When any new Java processes are started, the debugger is notified through its IRemoteDebugManagerCallback interface.

Enumerating Active Java Processes

Using the RequestCreateEvent method of the IRemoteDebugManager object, a debugger can request to be informed of new Java processes that are created. A debugger program can also keep track of active processes by the calling GetActiveProcesses method on this object to retrieve a pointer to an enumerator object (IJavaEnumRemoteProcess) for all active Java processes. Two other registration interfaces, IJavaEnumRemoteProcess and IEnumRemoteProcess, can be used to enumerate all Java processes currently running in the Microsoft VM.

These interfaces implement the following methods that may be called by a debugger.

Method | Description
Next | Used to retrieve IRemoteProcess objects that represent active Java processes into an array. The number of Java processes to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.
Skip | Moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.
Reset | Sets or resets the positions the enumerator to the beginning of the list of Java processes.
Clone | Copies a pointer to the current position in the list to another enumerator object.
GetNext | Retrieves the next IRemoteProcess object being pointed to by the enumerator object and increments the enumeration pointer by one. Note that this method is only implemented by the IJavaEnumRemoteProcess object.

Registering with a Remote Process

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.

The IRemoteProcess interface implements the following methods that can be called by a debugger.

Methods | Description
RegisterCallback | The debugger program calls this method to provide 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.
Detach | The debugger program calls this method to detach its callback (IRemoteProcessCallback) that was attached by some previous call to RegisterCallback.
Break | This method issues a break on all threads in this Java process, resulting in all threads being stopped. This method is asynchronous, so threads won't necessarily stop immediately.
GetGlobalContainerObject | This method returns a pointer to an IRemoteContainerObject, representing the root of all objects in this Java process. This method is used by a debugger to collect static information on all class objects in a Java process.
FindClass | This method finds a specific Java class. If the class isn't already loaded in the Java process, it’s loaded by the Microsoft VM.
TraceMethods | This method enables or disables TraceEvent callbacks used for notification of method calls. It is being deprecated. Developers should use the newer Java Profiler interfaces.
GetThreadGroups | This method returns an enumerator object (IJavaEnumRemoteThreadGroup) for all the thread groups in the Java process. The method is used by a debugger to collect dynamic information on all threads and class objects in a Java process.

Implementing Callback Notification Interfaces

For the Microsoft VM to communicate with a debugger, it registers with the Java Debug Manager and passes in pointers to COM objects that implement its notification interfaces. The Java debugger must implement two COM objects for this callback mechanism. The first provides global notification of new process creation. The second interface is used for debugging a specific Java process.

The notification interfaces that must be implemented by the debugger are as follows.

Notification Interfaces | Description
IRemoteDebugManagerCallback | This 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.
IRemoteProcessCallback | This object is the primary callback through which the VM communicates with the debugger and passes notifications and information requested concerning a specific Java process.
IRemoteDebugManagerCallbackEx | This COM object is not required to be implemented. This object inherits from and is a replacement for the IRemoteDebugManagerCallback object. This interface and is only necessary if the debugger wants to support JIT debugging.
IRemoteProcessCallbackEx | This COM object is not required to be implemented. This object is a replacement for the IRemoteProcessCallback object and is only necessary if the debugger wants to receive notification of the class for which the Microsoft VM was started.

A debugger will normally implement either the IRemoteDebugManager interface or the IRemoteDebugManagerEx interface, which extends the former interface by adding one new method. Under normal circumstances, JIT debugging is disabled when a Java process is being debugged. The IRemoteDebugManagerEx interface is only used when the debugger wants to receive notification of the classes for which the Microsoft VM started to support JIT debugging.

When the debugger program starts execution, it must register with the Java Debug Manager in the VM passing its own callback interface pointer to IRemoteDebugManagerCallback (or IRemoteDebugManagerCallbackEx).

The IRemoteDebugManagerCallback and IRemoteDebugManagerCallbackEx interfaces implement the following methods that may be called by the Microsoft VM.

Method | Description
ProcessCreateEvent | 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.
StartClassEvent | Only implemented by the IRemoteDebugManagerEx object. Notifies the debugger regarding the Java class it has started that the VM was started. For example, if the VM was started with JView using the command line “JView Hello,” the start class would be Hello. This method is only used for JIT debugging.

When a Java process starts in the Microsoft VM, the debugger will be notified through its 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.

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.

The IRemoteProcessCallback and the IRemoteProcessCallbackEx interfaces implement the following methods that may be called by the Microsoft VM.

Method | Description
DebugStringEvent | Notifies the debugger when the Java process being debugged outputs a string.
CodeBreakPointEvent | Notifies the debugger when a code breakpoint is hit by the Java process being debugged.
DataBreakPointEvent | Notifies the debugger when a data breakpoint is hit by the Java process being debugged.
ExceptionEvent | Notifies the debugger when an exception occurs in the Java process being debugged.
StepEvent | Notifies the debugger when an execution step completes in the Java process being debugged.
CanStopEvent | Notifies the debugger during a range step when the Java process being debugged makes a function call.
BreakEvent | Notifies the debugger when an asynchronous break occurs in response to the debugger calling IRemoteProcess:Break.
ThreadCreateEvent | Notifies the debugger when a thread is created.
ThreadDestroyEvent | Notifies the debugger when a thread is destroyed.
ThreadGroupCreateEvent | Notifies the debugger when a thread group is created.
ThreadGroupDestroyEvent | Notifies the debugger when a thread group is destroyed.
ClassLoadEvent | Notifies the debugger when a Java class is loaded and indicates the thread on which the class was loaded.
LoadCompleteEvent | Notifies the debugger when all Java class have been loaded.
ClassUnloadEvent | Notifies the debugger when a Java class is unloaded.
TraceEvent | 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.
ProcessDestroyEvent | 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.
StartClassEvent | Only implemented by the IRemoteDebugManagerEx object; notifies the debugger regarding the Java class it has started. This method is only used for JIT debugging.

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 a flurry of 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.

All these callback methods implemented by the debugger use the same return values. If the debugger returns S_FALSE, execution of the Java process continues. If the debugger returns S_OK, the Java process is suspended. This process can be resumed once the debugger calls IRemoteThread::Go.

The IRemoteProcess:FindClass method can be used to force a class to be loaded into the Microsoft VM if it is not already loaded. This method has side effects and the debugger will receive ClassLoadEvent method calls. The initializer for the Java class may also run and the debugger will not receive events during execution of the initializer. For example, if an exception occurs in the initializer, the debugger won't receive an exception event.

Thread groups are used to group threads together. Thread groups have special meaning for security purposes. Each Java applet is given its own thread group, and the applet can only manipulate threads within that group. These thread groups may be used to differentiate threads between multiple applets.

The debugger will receive notifications for a large number of events. The debugger is notified when thread groups and individual threads are created and destroyed. Threads are used extensively to get dynamic information when debugging a Java applet or application.

The debugger will also receive notifications on breakpoint and step events. The debugger sets breakpoints and controls execution by calling methods on the execution control interfaces. The objects to control execution control are also based using threads. In this case, threads are used to retrieve stack frames, calling frames and program counters.

Retrieving Static Information

Static information on a Java process is available through the IRemoteField hierarchy of interfaces. These interfaces represent fields that are members of classes. These fields can be methods, objects, inner classes, or nested class definitions. Because all the attributes of a field are constant during the lifetime of the field, this information can be cached by the debugger.

Global classes (classes not defined within other classes) can be thought of as fields of a global class. Access to static information in a Java process is based on using the IRemoteClassField and thread passed on each ClassLoadEvent notification to the debugger. The IRemoteProcess:GetGlobalContainerObject method (one of the interfaces used for retrieving dynamic information) can also be used to access the root of this object hierarchy and descend down it to retrieve IRemoteClassField objects.

The static information interfaces consist primarily of the IRemoteField interface and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, classes, methods, and so on) that inherit from IRemoteField or from other interfaces that extend IRemoteField. The static information interfaces implemented by the Microsoft VM are as follows.

Static Information Interfaces | Inherits From | Description
IRemoteField | IUnknown | This object represents a field in a Java process.
IRemoteDataField | IRemoteField | This object represents a field that is not a method or a class definition. This interface inherits from IRemoteField. This interface is not used except as a base interface for IRemoteArrayField.
IRemoteArrayField | IRemoteDataField | This object represents arrays (special data fields). The only major difference between data and arrays (IRemoteDataField and IRemoteArrayField) is that arrays have a size. This interface inherits from IRemoteDataField.
IRemoteContainerField | IRemoteField | The object represents fields that contain other fields. This interface inherits from IRemoteField.
IRemoteClassField | IRemoteContainerField | This object represents a class definition. This interface inherits from IRemoteContainerField.
IRemoteClassFieldEx | IRemoteClassField | This object represents a class definition. This interface inherits from IRemoteClassField and adds one new method.
IRemoteInnerClassField | IRemoteClassFieldEx | This objects represents an inner class definition. This interface inherits from IRemoteClassFieldEx and adds several new method.
IRemoteMethodField | IRemoteContainerField | This object represents a method within a class. This interface inherits from IRemoteContainerField.
IEnumRemoteField | IUnknown | This object allows a debugger to enumerate fields in a Java process running in the Microsoft VM.
IJavaEnumRemoteField | IEnumRemoteField | This object extends the IEnumRemoteField interface (adds one new method) and allows a debugger to enumerate fields in a Java process running in the Microsoft VM.
IEnumLINEINFO | IUnknown | This object enumerates line number information for a method.

Fields are classified and defined by the FIELDKIND enum as follows:

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | An Java inner class.

If a field is not FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS, it may be a class field or an array element. This may be determined by getting the kind of the field’s container. For an array element, the container field is FIELD_KIND_ARRAY. For a class field, the container field is FIELD_KIND_CLASS.

The following Java code sample illustrates the FIELDKINDs for a sample Java class.

class <globals>                           // FIELD_KIND_CLASS
{
    class FooClass                        // FIELD_KIND_CLASS
   {
       boolean bDone;                     // FIELD_KIND_DATA_PRIMITIVE
       class BarClass                     // FIELD_KIND_CLASS
      {
           String username[20];           // FIELD_KIND_ARRAY
      }
      BarClass mybar;                     // FIELD_KIND_DATA_OBJECT
      int BarMethod();                    // FIELD_KIND_METHOD
    };
};

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELD_ACC enum as follows:

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

The IRemoteField interface and the other IRemoteXXXField interfaces that inherit from IRemoteField implement a standard set of methods used to get the name, kind, type, and modifiers of a field as well as the field representing the class that contains the field. The GetContainer method provides a way for a debugger to maneuver up the field hierarchy in a class.

The following methods of IRemoteField (and the objects that inherit from it) can be called by a debugger.

Methods | Description
GetName | Returns the identifier (the class, variable, or method name) for this field.
GetKind | Returns the kind (FIELD_KIND enum) of this field.
GetType | Returns an IRemoteField object that represents the type of this field. The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on). When this method is called on a global container field, the method returns S_OK and IRemoteField object returned representing the type is NULL.
GetContainer | Returns the field representing the class that contains the field.
GetModifiers | Returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

The following methods are specific to the interfaces that inherit from IRemoteField and can be called by a debugger.

Methods | Description
GetSize | Returns the number of elements in an array. This method is implemented only by the IRemoteArrayField interface.
GetFields | Returns an enumerator (IJavaEnumRemoteField) for the fields that are contained by this field and match given characteristics. The characteristics are determined by three parameters passed to the method that specify the name of the field, the modifiers bitmask, and the kind. A null parameter passed for the name is used to include all names. A bitmask of 0 is used to include all modifiers. A FIELD_KIND of 0 is used to include all kinds. This method is implemented only by the IRemoteContainerField, IRemoteClassField, IRemoteClassFieldEx, IRemoteInnerClassField, and the IRemoteMethodField interfaces.
GetFileName | Returns the full name of the class if it is available (C:\classes\HelloWorld.class, for example). This method is implemented only by the IRemoteClassField, IRemoteClassFieldEx, and IRemoteInnerClassField interface.
GetSourceFileName | Returns the name of the source file attribute (SourceFile) from the class file if it is available (HelloWorld.java, for example). This method is implemented only by the IRemoteClassField, IrRemoteClassFieldEx, and IRemoteInnerClassField interfaces.
GetSourceFileDir | Returns the name of the source file directory attribute (SourceDir) from the class file if it is available. This method is implemented only by the IRemoteClassFieldEx and the IRemoteInnerClassField interfaces.
GetSuperclass | Returns the class (an IRemoteClassField) from which this class is derived. For Java.Lang.Object, the top of the hierarchy, this method returns NULL. This method is implemented only by the IRemoteClassField interface.
GetInterfaces | Returns an enumerator (IJavaEnumRemoteField) for the interfaces that this class implements. If the class has no interfaces, an enumerator is returned that enumerates nothing. This method is implemented only by the IRemoteClassField, IRemoteClassFieldEx, and IRemoteInnerClassField interface.
GetConstantPoolItem | Returns the raw contents for the constant pool and is used for disassembly. Any indices contained within the CP item are converted from big endian order to platform byte order. This method is implemented only by the IRemoteClassField, IRemoteClassFieldEx, and IRemoteInnerClassField interface.
GetIndexedField | Obtains a local variable or parameters field from a method by local variable index and byte offset.

The constant pool items are defined by an initial tag byte that indicates the format of the item stored followed the specific information for that constant entry. The constant pool tag bytes are defined as follows:

enum | Value | Description
CP_CONSTANT_UTF8 | 1 | A UCS Transformation Format (UTF-8) string used to represent constant string values encoded in a structure with a 2-byte length preceding the string.
CP_CONSTANT_UNICODE | 2 | A Unicode string with a two-byte length preceding the string.
CP_CONSTANT_INTEGER | 3 | A 32-bit integer constant.
CP_CONSTANT_FLOAT | 4 | A 32-bit single-precision floating point constant.
CP_CONSTANT_LONG | 5 | A 64-bit long constant.
CP_CONSTANT_DOUBLE | 6 | A 64-bit double precision floating-point constant.
CP_CONSTANT_CLASS | 7 | A 16-bit index to a UTF-8 constant name.
CP_CONSTANT_STRING | 8 | A 16-bit index to a UTF-8 constant string.
CP_CONSTANT_FIELDREF | 9 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_METHODREF | 10 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_ INTERFACEMETHODREF | 11 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_NAMETYPE | 12 | One 16-bit index to a name (UTF-8 constant) followed by a 16-bit index to a field or method descriptor (a UTF-8 constant) representing the type of a class or instance variable. The field or method descriptor is a series of characters defined in the Java Virtual Machine specification published by Sun Microsystems.

The following methods are specific to the IRemoteInnerClassField and can be called by a debugger.

Methods | Description
GetInnerClassName | Returns the real class name, not the mangled class name from the Java compiler.
GetInnerClassModifiers | Returns the real field modifiers for the inner class.
GetOuterClass | Returns an IRemoteClassField representing the outer class.

The IRemoteMethodField, which inherits from the IRemoteContainerField, represents a method within a class. This interface implements a number of methods that can be used by a debugger to set and clear breakpoints, get line number info, return Java bytecodes, and other information.

The following methods are specific to the IRemoteMethodField and can be called by a debugger.

Methods | Description
SetBreakpoint | Sets a code breakpoint at a given byte offset from the start of a method. The VM will not validate the given location of the breakpoint; a breakpoint may be set at any offset within the method’s bytecodes. Breakpoints are reference counted and may be set multiple times at the same byte offset.
ClearBreakpoint | Clears a code breakpoint at a given byte offset from the start of a method. This method will only clear breakpoints set by SetBreakpoint. If a breakpoint is set multiple times, it must be cleared the same number of times to eliminate it completely.
GetLineInfo | Returns an enumerator of LINEINFO structures (IJavaEnumLINEINFO objects) describing the mapping between source lines and byte offset within the Java bytecodes representing the method. This mapping is in order of increasing offsets. The last element in the list is a “dummy” node with a line number field set to the last line of the method + 1 and the offset field set to the last offset in the method +1.
GetBytes | Returns an interface (ILockBytes) that can be used to access the Java bytecode of the method. This method can be used by a debugger to display a disassembly of the bytecode.
GetScope | Returns the range of byte offsets (within which the object is in scope) that can be used by a debugger to obtain the value of some field within this method.
GetIndexedField | Obtains a local variable or parameters field from a method by local variable index and byte offset.

Enumerating Static Fields

Several of the interfaces that inherit from the IRemoteField object (IRemoteContainerField, IRemoteClassField, and IRemoteMethodField) implement a GetFields method that returns an enumerator for the fields contained by this field. Two other static information interfaces, IJavaEnumRemoteField and IEnumRemoteField, can be used to enumerate all these fields contained within a class, method, or container. The IJavaEnumRemoteField object inherits from IEnumRemoteField, extending this interface with one additional method.

These interfaces implement the following methods that may be called by a debugger.

Method | Description
Next | Used to retrieve IRemoteField objects that represent fields. The number of fields to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.
Skip | Moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.
Reset | Sets or resets the positions the enumerator to the beginning of the list of fields.
Clone | Copies a pointer to the current position in the list to another enumerator object.
GetCount | Returns the number of fields being pointed to by the enumerator object.
GetNext | Retrieves the next IRemoteField object being pointed to by the enumerator object and increments the enumeration pointer by one. Note that this method is only implemented by the IJavaEnumRemoteField object.

Enumerating Line Number Information

Line number information represents the mapping between Java source code line numbers and byte offsets in the method. This information is represented as an array of LINEINFO structures maintained for each method. The IEnumLINEINFO interface provides access to this information.

The IEnumLINEINFO interface implements the following methods that may be called by a debugger.

Method | Description
Next | Used to retrieve LINEINFO structures that represent the mapping between Java source code line numbers and byte offset in the method. The number of LINEINFO structures to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.
Skip | Moves the position of the enumeration forward. The number of LINEINFO structures to be skipped is based on a parameter passed to the method.
Reset | Sets or resets the positions the enumerator to the beginning of the list of LINEINFO structures.
Clone | Copies a pointer to the current position in the list to another enumerator object.
GetNext | Retrieves the next LINEINFO structure being pointed to by the enumerator object and increments the enumeration pointer by one. Note that this method is only implemented by the IJavaEnumLINEINFO object.
GetCount | Returns the number of fields being pointed to by the enumerator object. Note that this method is only implemented by the IJavaEnumLINEINFO object.

Retrieving Dynamic Information

Dynamic information on a Java process is available through the IRemoteObject hierarchy of interfaces. These interfaces provide bound access to objects of different types. An object does not necessarily refer to an instance of a class, but represents an instance of any type. The information obtained from an IRemoteObject is only valid during the lifetime of the actual object that it represents. Consequently, dynamic information cannot be cached by the debugger.

Access to dynamic information in a Java process is based on using the IRemoteThreadGroup and IRemoteThread passed on each ThreadGroupCreateEvent and ThreadCreateEvent notification to the debugger. The IRemoteProcess:GetGlobalContainerObject method can also be used to access the root of this object hierarchy and descend down it to retrieve IRemoteClassField objects.

The dynamic information interfaces consist primarily of the IRemoteObject, IEnumRemoteObject, and the IEnumRemoteValue interfaces and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, or classes) that inherit from IRemoteObject or IEnumRemoteValue. The dynamic information interfaces implemented by the Microsoft VM are as follows.

Dynamic Information Interfaces | Inherits From | Description
IRemoteObject | IUnknown | Represents bound access to objects of different types in a Java process.
IRemoteBooleanObject | IRemoteObject | Provides run-time access to the value of a boolean variable.
IRemoteByteObject | IRemoteObject | Provides run-time access to the value of a byte variable.
IRemoteCharObject | IRemoteObject | Provides run-time access to the value of a char variable.
IRemoteContainerObject | IRemoteObject | Provides run-time access to container objects.
IRemoteClassObject | IRemoteContainerObject | Provides run-time access to class objects.
IRemoteDoubleObject | IRemoteObject | Provides run-time access to the value of a double variable.
IRemoteFloatObject | IRemoteObject | Provides run-time access to the value of a float variable.
IRemoteIntObject | IRemoteObject | Provides run-time access to the value of an int variable.
IRemoteLongObject | IRemoteObject | Provides run-time access to the value of a long variable.
IRemoteShortObject | IRemoteObject | Provides run-time access to the value of a short variable.
IRemoteArrayObject | IRemoteObject | Provides run-time access to array objects.
IEnumRemoteObject | IUnknown | Allows a debugger to enumerate objects in a Java process running in the Microsoft VM.
IEnumRemoteValue | IUnknown | Allows a debugger to enumerate the value of a variable in a Java process running in the Microsoft VM.
IEnumRemoteBooleanValue | IEnumRemoteValue | Enumerates boolean values.
IEnumRemoteByteValue | IEnumRemoteValue | Enumerates byte values.
IEnumRemoteCharValue | IEnumRemoteValue | Enumerates char values.
IEnumRemoteDoubleValue | IEnumRemoteValue | Enumerates double values.
IEnumRemoteFloatValue | IEnumRemoteValue | Enumerates float values.
IEnumRemoteIntValue | IEnumRemoteValue | Enumerates int values.
IEnumRemoteLongValue | IEnumRemoteValue | Enumerates long values.
IEnumRemoteShortValue | IEnumRemoteValue | Enumerates short values.
IJavaEnumRemoteValue | IEnumRemoteValue | Allows a debugger to enumerate the value of a variable in a Java process running in the Microsoft VM.
IJavaEnumRemoteBooleanValue | IJavaEnumRemoteValue | Enumerates boolean values.
IJavaEnumRemoteByteValue | IJavaEnumRemoteValue | Enumerates byte values.
IJavaEnumRemoteCharValue | IJavaEnumRemoteValue | Enumerates char values.
IJavaEnumRemoteDoubleValue | IJavaEnumRemoteValue | Enumerates double values.
IJavaEnumRemoteFloatValue | IJavaEnumRemoteValue | Enumerates float values.
IJavaEnumRemoteIntValue | IJavaEnumRemoteValue | Enumerates int values.
IJavaEnumRemoteLongValue | IJavaEnumRemoteValue | Enumerates long values.
IJavaEnumRemoteShortValue | IJavaEnumRemoteValue | Enumerates short values.

Java uses a number of built-in types that can be represented by a Win32 debugger written in C and C++ as a series of typedefs as follows:

// JAVA built-in types
    typedef BYTE JAVA_BOOLEAN;
    typedef signed char JAVA_BYTE;
    typedef USHORT JAVA_CHAR;
    typedef double JAVA_DOUBLE;
    typedef float JAVA_FLOAT;
    typedef LONG JAVA_INT;
    typedef LONGLONG JAVA_LONG;
    typedef SHORT JAVA_SHORT;
    typedef LPOLESTR JAVA_STRING;

The IRemoteObject interface and the other IRemoteXXXObject interfaces that inherit from IRemoteObject implement a standard set of methods used to get the type of an object, and set or clear data breakpoints on the object. The breakpoint will fire when the value of the object changes. For classes, a data breakpoint will fire when the object references a different instance of that class. For arrays, a data breakpoint will fire when the object references a different instance of the array (when one array is assigned or copied to another). The GetFieldObject method of the IRemoteContainerObject interface provides a way for a debugger to access fields in a container (class).

The following methods of IRemoteObject (and the objects that inherit from it) can be called by a debugger.

Methods | Description
GetType | Returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on.).
SetBreakpoint | Sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.
ClearBreakpoint | Clears a data breakpoint on the object previously set with the SetBreakpoint method.
GetValue | Gets the value of a primitive Java type. This method is implemented by the IRemotexxxObject interfaces that inherit from IRemoteObject, where xxx represents one of the primitive Java data types.
SetValue | Sets the value of a primitive Java type. This method is implemented by the IRemotexxxObject interfaces that inherit from IRemoteObject, where xxx represents one of the primitive Java data types.

The following methods are unique to the IRemoteObjectEx and can be called by a debugger.

Methods | Description
IsSameObject | Indicates whether two objects are the same object.
GetContainer | Returns an IRemoteObject that represents the container for the current object. This methods allows a debugger to navigate back up the hierarchy of objects.
GetIdentity | Returns a new IRemoteObjectEx that is detached from its containers. This method is used for data breakpoints and allows a debugger to hang onto an object across execution.

The following method is unique to the IRemoteContainerObject (and the IRemoteClassObject that inherit from it) and can be called by a debugger.

Methods | Description
GetFieldObject | Returns an IRemoteObject that represents the object contained in the field of this object. The IRemoteField object that is returned is not bound to the instance of the object and can be used to extract the value of that field from many different IRemoteContainerObject in the same Java process. This method allows a debugger to navigate down the hierarchy of objects.

The following method is unique to the IRemoteClassObject and can be called by a debugger.

Methods | Description
GetDerivedMostType | Returns an IRremoteClassField that represents the object's derived-most type. An example of a derived-most type would be a MyException class derived from the java.io.IOException class.

Enumerating Dynamic Information

Several of the interfaces that inherit from the IRemoteObject object (IRemoteContainerObject and IRemoteClassObject) implement a GetFieldObject method that returns an object representing a specific field.

Several other dynamic information interfaces, IEnumRemoteObject, IEnumRemoteValue, and IJavaENumRemoteValue, can be used to enumerate objects and enumerate values. The IJavaEnumRemoteValue object inherits from IEnumRemoteValue, extending this interface with one additional method.

These interfaces implement the following methods that may be called by a debugger.

Method | Description
Next | Used to retrieve objects (IRemoteObject). The number of objects to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.
Skip | Moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.
Reset | Sets or resets the positions the enumerator to the beginning of the list of fields.
Clone | Copies a pointer to the current position in the list to another enumerator object.
GetCount | Returns the number of objects being pointed to by the enumerator object.
GetNext | Retrieves the next LINEINFO structure being pointed to by the enumerator object and increments the enumeration pointer by one. Note that this method is only implemented by the IJavaEnumRemoteValue object and the interfaces that inherit from it.

Controlling Execution

Controlling execution of a Java process is available through the IRemoteThread and IRemoteStackFrame interfaces. These interfaces provide access to call stacks within the threads of the Java process being debugged. Each stack frame represents the state of execution within a method. Consequently, execution control information cannot be cached by the debugger.

Access to execution control information in a Java process is based on using the IRemoteThreadGroup and IRemoteThread passed on each ThreadGroupCreateEvent and ThreadCreateEvent notification to the debugger. The IRemoteProcess:GetGlobalContainerObject method can also be used to access the root of this object hierarchy and descend down it to retrieve IRemoteThreadGroup and IRemoteThread objects. These IRemoteThread objects can then be used to access the IRemoteStackFrame objects

The execution control interfaces consist primarily of the IRemoteStackFrame, IRemoteThread, and the IRemoteThreadGroup interfaces and a collection of other interfaces used for enumerating threads and thread groups. The execution control interfaces implemented by the Microsoft VM are as follows.

Execution Control Interfaces | Inherits From | Description
IRemoteStackFrame | IUnknown | Provides access to call stacks within the threads of the Java process being debugged. Each stack frame represents the state of execution within a method.
IRemoteStackFrameEx | IRemoteStackFrame | Provides access to call stacks within the threads of the Java process being debugged. Each stack frame represents the state of execution within a method. This interface inherits from IRemoteStackFrame and adds two new methods.
IRemoteThreadGroup | IUnknown | Provides access to thread groups.
IRemoteThreadGroupEx | IRemoteThreadGroup | Provides access to thread groups. This interface inherits from IRemoteThreadGroup and adds one new method.
IRemoteThread | IUnknown | Provides access to threads.
IRemoteThreadEx | IRemoteThread | Provides access to threads. This interface inherits from IRemoteThread and adds several new methods.
IEnumRemoteStackFrames | IUnknown | Allows a debugger to enumerate stack frames in a Java process running in the Microsoft VM.
IEnumRemoteThreadGroup | IUnknown | Allows a debugger to enumerate thread groups in a Java process running in the Microsoft VM.
IJavaEnumRemoteThreadGroup | IEnumRemoteThreadGroup | Allows a debugger to enumerate thread groups in a Java process running in the Microsoft VM. This interface inherits from IEnumRemoteThreadGroup and adds one new method.
IEnumRemoteThread | IUnknown | Allows a debugger to enumerate threads in a Java process running in the Microsoft VM.
IJavaEnumRemoteThread | IEnumRemoteThread | Allows a debugger to enumerate threads in a Java process running in the Microsoft VM. This interface inherits from IEnumRemoteThread and adds one new method.

The IRemoteThreadGroup and the IRemoteThreadGroupEx interfaces implement a set of methods used to get the name of a thread group and enumerate the other thread groups and threads in a thread group.

The following methods of IRemoteThreadGroup (and the IRemoteThreadGroupEx objects that inherit from it) can be called by a debugger.

Methods | Description
GetName | Returns the name of this thread group.
GetThreads | Returns an enumerator for the threads in this thread group.
GetThreadGroups | Returns an enumerator for the thread groups in this thread group.
GetParent | Returns the parent thread group of this thread group. This method is implemented by the IRemoteThreadGroupEx interface that inherits from IRemoteThreadGroup.

Enumerating Thread Groups, Threads, and Stack Frames

Two execution control interfaces, IJavaEnumRemoteThreadGroup and IEnumRemoteThreadGroup, can be used to enumerate all these thread groups contained in a Java process. The IJavaEnumRemoteThreadGroup object inherits from IEnumRemoteThreadGroup, extending this interface with one additional method.

The IRemoteThreadGroup interface implements a GetThreads method that returns an enumerator for the threads in this thread group. Two other execution control interfaces, IJavaEnumRemoteThread and IEnumRemoteThread, can be used to enumerate all the threads contained within a thread group. The IJavaEnumRemoteThread object inherits from IEnumRemoteThread, extending this interface with one additional method.

These interfaces implement the following methods that may be called by a debugger.

Method | Description
Next | Used to retrieve IRemoteThread or IRemoteThreadGroup objects that represent thread groups or threads in a Java process. The number of objects to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.
Skip | Moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.
Reset | Sets or resets the positions the enumerator to the beginning of the list of fields.
Clone | Copies a pointer to the current position in the list to another enumerator object.
GetNext | Retrieves the next IRemoteThreadGroup or IRemoteThread object being pointed to by the enumerator object and increments the enumeration pointer by one. Note that this method is only implemented by the IJavaEnumRemoteThreadGroup and IJavaEnumRemoteThread object.

Controlling Execution with Remote Thread Objects

Execution of a Java process is controlled through methods implemented by the IRemoteThread and IRemoteThreadEx interfaces. Methods on these objects allow a debugger to suspend or resume execution of a thread, step through or over a method, and get the current stack frame on this thread. Other methods return the name of the thread and the thread group containing this thread, which allow a debugger to move up the hierarchy of thread objects.

For notification, many of these methods generate a StepEvent call to the debugger on its IRemoteCallBack or IRemoteCallbackEx interface. If StepEvent returns S_FALSE, execution continues. If StepEvent returns S_OK, execution of this thread is suspended until the Go or Resume method is called.

The following methods of IRemoteThread (and the IRemoteThreadEx object that inherits from it) can be called by a debugger.

Methods | Description
GetName | Returns the name of this thread.
GetCurrentStackFrame | Returns the currently executing stack frame on this thread.
GetThreadGroup | Returns the thread group (traverse up the hierarchy) that contains this thread.
Go | Continues (resumes) execution of this thread. This method clears the execution state and returns immediately.
Step | Steps a single instruction of bytecode. This method steps over method calls in a Java class. The StepEvent method exported by the debugger on the IRemoteCallback interface is called when execution is complete.
StepIn | Steps over a single bytecode instruction. The StepIn method steps into method calls in a Java class. This method return immediately. The StepEvent method exported by the debugger on the IRemoteCallback interface is called when execution is complete.
StepOut | Continues execution until the end of the current method. The next instruction to be executed is the first instruction after the call in the calling method. This method returns immediately. The StepEvent method exported by the debugger on the IRemoteCallback interface is called when execution is complete.
RangeStep | Continues execution until the PC is outside the given range. The RangeStep method steps over method calls in a Java class. The StepEvent method (exported by the debugger on the IRemoteCallback interface) is called when execution is complete. If the flow of execution enters another method, the debugger receives a CanStopEvent method call on its IRemoteCallback interface.
RangeStepIn | Continues execution until the PC is outside the given range. The RangeStep method steps into method calls in a Java class. The StepEvent method exported by the debugger on the IRemoteCallback interface is called at the first instruction of the stepped into method. If the debugger returns S_FALSE from StepEvent, the Microsoft VM continues executing to the end of this method, and continues executing within the given range. when execution is complete. If the flow of execution enters another method, the debugger receives a CanStopEvent method call on its IRemoteCallback interface.
Destroy | Destroys a thread. The ThreadDestroy method exported by the debugger on the IRemoteCallback interface is called when the operation is complete.
Suspend | Suspends execution of this thread.
Resume | Resumes execution of this thread.
GetSuspendCount | Returns a count of how many times the debugger called Suspend.
GetThreadID | Returns the actual Win32 thread ID for the thread. This method is implemented by the IRemoteThreadEx interface.
GetStackFrames | Returns an enumerator for all of the stack frames in this thread. This method is implemented by the IRemoteThreadEx interface.
IsStartBlock | Indicates if a given stack frame is at the top of the thread (the current stack frame). This method is implemented by the IRemoteThreadEx interface.
WatchForStep | This method is used for cross-language engine support (JavaScript and Microsoft® Visual Basic® Scripting Edition, for example) to watch for stepping above or below a given stack pointer. This method is implemented by the IRemoteThreadEx interface.
Continue | Continues (resumes) execution of this thread similar to the Go method, but leaves the Java process in step mode. This call returns immediately. This method is implemented by the IRemoteThreadEx interface.
AllowExecution | This method is used to control whether execution of this thread should be enabled or disabled. This method is used for function evaluation. This method is implemented by the IRemoteThreadEx interface.
PassExceptionToDebuggee | This method is used to control how exceptions are handled during an ExceptionEvent. If this method is called with FALSE as the parameter, the Microsoft VM “swallows” any exceptions that occur, ignores the exception that just occurred, and continues execution. If this method is called with TRUE as the parameter, exception handling occurs normally. If an exception is not caught by the Java process, the exception is passed to the Microsoft VM and the Java process is aborted and the thread is terminated. This method is implemented by the IRemoteThreadEx interface and may only be called during an ExceptionEvent.
ClearExecutionState | This method clears the execution state and returns immediately. Executing a Go method is the equivalent of a ClearExecution method call followed by a Continue call. This method is implemented by the IRemoteThreadEx interface.

Accessing Call Stacks

Call stacks are accessed through methods implemented by the IRemoteThread and IRemoteStackFrame and the IRemoteStackFrameEx interfaces. Stack frames can be enumerated by calling the GetStackFrames method of the IRemoteThreadEx interface. The current stack frame can be returned by calling the GetCurrentStackFrame method of the IRemoteThread or the IRemoteThreadEx interfaces.

Methods on these objects allow a debugger to view and change bytecodes that are about to be executed. Other methods return the calling frame and the method object, which allow a debugger to navigate up the hierarchy of objects.

The following methods of IRemoteStackFrame (and the IRemoteStackFrameEx object that inherits from it) can be called by a debugger.

Methods | Description
GetCallingFrame | Returns the stack frame representing the caller of this method.
GetMethodObject | Returns an IRemoteContainer object representing the instance of the method object.
GetPC | Returns the byte offset from the start of this method of the next instruction to be executed. In non-topmost stack frames, this returns the byte offset of the invoke instruction that is being executed.
SetPC | Sets the byte offset from the start of this method of the next instruction to be executed.
GetKind | Returns the FRAMEKIND of this frame stack.
GetStackRange | Returns the real Win32 pointers top the upper and lower bounds to a stack frame. This method is used for mixed language debugging, so the debugger can order the call stack. This method is implemented by the IRemoteStackFrameEx interface.
GetRealPC | Returns the return address for the stack frame (real PC byte offset from the start of this method) of where execution will resume. This method is implemented by the IRemoteStackFrameEx interface.


Execution Control Interfaces

Working with MS VM
In this topic

* IRemoteStackFrame : IUnknown

* IRemoteThreadGroup : IUnknown

* IEnumRemoteThread : IUnknown

* IEnumRemoteThreadGroup : IUnknown

* IRemoteThread : IUnknown

Microsoft VM | Previous | VM
Java Language Debug Interfaces | Previous | VM

Execution Control Interfaces

Use these interfaces to manage execution.

IRemoteStackFrame : IUnknown

Provides access to call stacks within the threads of the debuggee. Each stack frame represents the state of execution within a method.

GetCallingFrame

HRESULT GetCallingFrame(IRemoteStackFrame **ppCallingFrame)

Parameter | Description
[out] ppCallingFrame | Returns the frame representing the caller of this method.

GetMethodObject

HRESULT GetMethodObject(IRemoteContainerObject **ppMethodObject)

Parameter | Description
[out] ppMethodObject | Returns the instance of the method object

GetPC

HRESULT GetPC(UINT *offPC)

Parameter | Description
[out] offPC | Returns the byte offset from the start of this method of the next instruction to be executed.

SetPC

HRESULT SetPC(UINT offPC)

Parameter | Description
[in] offPC | Sets the byte offset from the start of this method of the next instruction to be executed.

GetKind

HRESULT GetKind(FRAMEKIND *pfk)

Parameter Description
[out] pfk Returns the kind of this stack frame.
typedef enum framekind {
    FRAME_KIND_INVALID	= 0x00,
    FRAME_KIND_INTERPRETED	= 0x01,
    FRAME_KIND_NATIVE		= 0x02,
    FRAME_KIND_JIT_COMPILED	= 0x03
} FRAMEKIND;

IRemoteThreadGroup : IUnknown

Provides access to thread groups.

GetName

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the name of this thread group.

GetThreads

HRESULT GetThreads(IEnumRemoteThread **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the threads in this thread group.

GetThreadGroups

HRESULT GetThreadGroups(IEnumRemoteThreadGroup **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the thread groups in this thread group.

IEnumRemoteThread : IUnknown

Enumerates threads.

Next

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

Skip

HRESULT Skip(ULONG celt)

Reset

HRESULT Reset(void)

Clone

HRESULT Clone(IEnumRemoteThread **ppEnum)

IEnumRemoteThreadGroup : IUnknown

Enumerates thread groups.

Next

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

Skip

HRESULT Skip(ULONG celt)

Reset

HRESULT Reset(void)

Clone

HRESULT Clone(IEnumRemoteThreadGroup **ppEnum)

IRemoteThread : IUnknown

Provides access to threads.

GetName

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the name of this thread.

GetCurrentFrame

HRESULT GetCurrentFrame(IRemoteStackFrame **ppCurrentFrame)

Parameter | Description
[out] ppCurrentFrame | Returns the currently executing stack frame on this thread.

GetThreadGroup

HRESULT GetThreadGroup(IRemoteThreadGroup **ppThreadGroup)

Parameter | Description
[out] ppThreadGroup | Returns the thread group that contains this thread.

Go

HRESULT Go(void)

Continues execution of this thread. This call returns immediately.

Step

HRESULT Step(void)

Steps a single instruction of bytecode. This call steps over method calls. It returns immediately. The StepEvent method is called when the execution is complete.

StepIn

HRESULT StepIn(void)

Steps over a single bytecode instruction. This call steps into method calls. It returns immediately. The StepEvent method is called when the execution is complete.

StepOut

HRESULT StepOut(void)

Continues execution until the end of the current method. The next instruction to be executed is the first instruction after the call in the calling method. This call returns immediately. The StepEvent method is called when the execution is complete.

RangeStep

HRESULT RangeStep(UINT offStart, UINT offEnd)

Continually steps until the PC is outside the given range. This call steps over method calls. The StepEvent method is called when the execution is complete.

Parameter | Description
[in] offStart, offEnd | Start and end byte offsets from the beginning of the current method.

RangeStepIn

HRESULT RangeStepIn(UINT offStart, UINT offEnd)

Continually steps until the PC is outside the given range. This call steps into method calls and calls StepEvent at the first instruction of the stepped-into method. If the debugger returns S_FALSE from StepEvent, then the VM continues executing to the end of this method, and continues executing within the given range. This call returns immediately. The StepEvent method is called when the execution is complete.

Parameter | Description
[in] offStart, offEnd | Start and end byte offsets from the beginning of the current method.

Destroy

HRESULT Destroy(void)

Destroys this thread. The ThreadDestroyEvent method is called when the operation is complete.

Suspend

HRESULT Suspend(void)

Suspends execution of this thread.

Resume

HRESULT Resume(void)

Resumes execution of this thread.

GetSuspendCount

HRESULT GetSuspendCount(ULONG *pcSuspend)

Parameter | Description
[out] pcSuspend | Returns this thread's current suspend count.


Using the Java Language Debug Reference

Working with MS VM

Microsoft VM | VM | Next
Java Language Debug Interfaces | VM | Next

Java Language Debug Reference Overview

This topic provides details about registration, notification, static information, and dynamic information interfaces.

Registration Interfaces

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

Notification Interfaces

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.

Static Information Interfaces

Static information on a Java process is available through the IRemoteField hierarchy of interfaces. These interfaces represent fields that are members of classes. These fields can be methods, objects, inner classes, or nested class definitions. Because all the attributes of a field are constant during its lifetime, this information can be cached by the debugger.

The static information interfaces consist primarily of the IRemoteField interface and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, classes, methods, and so on) that inherit from IRemoteField or from other interfaces that extend IRemoteField.

Dynamic Information Interfaces

Dynamic information on a Java process is available through the IRemoteObject hierarchy of interfaces. These interfaces provide bound access to objects of different types. An object does not necessarily refer to an instance of a class, but represents an instance of any type. The information obtained from an IRemoteObject is only valid during the lifetime of the actual object that it represents. Consequently, dynamic information cannot be cached by the debugger.

Access to dynamic information in a Java process is based on using the IRemoteThreadGroup and IRemoteThread passed on each ThreadGroupCreateEvent and ThreadCreateEvent notification to the debugger. The IRemoteProcess:GetGlobalContainerObject method can also be used to access the root of this object hierarchy and descend down it to retrieve IRemoteClassField objects.

The dynamic information interfaces consist primarily of IRemoteObject, IRemoteObjectEx, IEnumRemoteObject, the IEnumRemoteValue interfaces, and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, or classes) that inherit from IRemoteObject or IEnumRemoteValue.


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)
Parameter | Description
[in] pCallback | The callback that should receive notification when new Java processes are created.

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)
Parameter | Description
[out] ppEnum | Returns an enumerator object for all Java processes currently running in the Microsoft VM.

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)
Parameter | Description
[in] pcszProcessName | The name of the Java application or applet class to debug. If a null string is passed, all Java applications or applet classes.
[in] dwParentProcessId | The Win32® process ID of the process that the applet or application will be run in.

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)
Parameter | Description
[in] celt | The number of IRemoteProcess objects requested to be retrieved.
[out] drgelt | The pointer to the array of IRemoteProcess objects that is retrieved.
[out] pceltFetched | The number of actual IRemoteProcess objects that was retrieved.

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)
Parameter | Description
[in] celt | The number of IRemoteProcess objects requested to be skipped.

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)
Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to Java processes currently running in the Microsoft VM representing the current position in the list of active Java processes.

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)
Parameter | Description
[in] celt | The number of IRemoteProcess objects requested to be retrieved.
[out] drgelt | The pointer to the array of IRemoteProcess objects that is retrieved.
[out] pceltFetched | The number of actual IRemoteProcess objects that was retrieved.

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)
Parameter | Description
[in] celt | The number of IRemoteProcess objects requested to be skipped.

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)
Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the Java processes currently running in the Microsoft VM representing the current position in the list of active Java processes.

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)
Parameter | Description
[out] ppirp | The pointer to the IRemoteProcess object that is retrieved.

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)
Parameter | Description
[in] pCallback | A pointer to the COM interface implemented by the debugger that is to receive notifications for this Java process.

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)
Parameter | Description
[out] ppGlobalContainerObject | Returns a pointer to the global object for this Java process.

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)
Parameter | Description
[in] pcszClassName | The name of the class to find.
[out] ppClassType | Returns the specified class. If the class is not already loaded in the Java process, it is loaded.

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)
Parameter | Description
[in] bTraceOn | Set to TRUE to enable method call tracing, or FALSE to disable method call tracing.

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)
Parameter | Description
[out] ppEnum | Returns an enumerator for the thread groups in the Java process.

Notification Interfaces

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)
Parameter | Description
[in] pProcessNew | The Java process being created.
[in] pProcessParent | The Java process that caused the new Java process to be created. The pProcessParent parameter is NULL if the Java process is not being created as the child of another Java process.

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)
Parameter | Description
[in] pProcessNew | The Java process being created.
[in] pProcessParent | The Java process that caused the new Java process to be created. The pProcessParent parameter is NULL if the Java process is not being created as the child of another Java process.

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)
Parameter | Description
[in] pcstrStartClass | The Java class that the VM was started for.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pcszDebugString | The string from the Java process.

IRemoteProcessCallback::CodeBreakpointEvent

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

HRESULT CodeBreakpointEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pObject | The object that changed to cause the breakpoint to be triggered.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pExceptionClass | The class of the object throwing the exception.
[in] exceptionKind The kind of exception that occurred.
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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallback::ThreadCreateEvent

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

HRESULT ThreadCreateEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallback::ThreadDestroyEvent

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

HRESULT ThreadDestroyEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallback::ThreadGroupCreateEvent

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

HRESULT ThreadGroupCreateEvent(IRemoteThread *pThread,
      IRemoteThreadGroup *pThreadGroup)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pThreadGroup | The new thread group that is created.

RemoteProcessCallback::ThreadGroupDestroyEvent

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

HRESULT ThreadGroupDestroyEvent(IRemoteThread *pThread,
     IRemoteThreadGroup *pThreadGroup)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pThreadGroup | The thread group that is destroyed.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pClassType | The class that was loaded.

IRemoteProcessCallback:: LoadCompleteEvent

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

HRESULT LoadCompleteEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallback::ClassUnloadEvent

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

HRESULT ClassUnloadEvent(IRemoteThread *pThread, IRemoteClassField *pClassType)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pClassType | The class that was unloaded.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pcszDebugString | The string from the Java process.

IRemoteProcessCallbackEx::CodeBreakpointEvent

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

HRESULT CodeBreakpointEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pObject | The object that changed to cause the breakpoint to be triggered.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pExceptionClass | The class of the object throwing the exception.
[in] exceptionKind The kind of exception that occurred.
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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallbackEx::ThreadCreateEvent

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

HRESULT ThreadCreateEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallbackEx::ThreadDestroyEvent

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

HRESULT ThreadDestroyEvent(IRemoteThread *pThread)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallbackEx::ThreadGroupCreateEvent

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

HRESULT ThreadGroupCreateEvent(IRemoteThread *pThread,
     IRemoteThreadGroup *pThreadGroup)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pThreadGroup | The new thread group that is created.

RemoteProcessCallbackEx::ThreadGroupDestroyEvent

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

HRESULT ThreadGroupDestroyEvent(IRemoteThread *pThread,
     IRemoteThreadGroup *pThreadGroup)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pThreadGroup | The thread group that is destroyed.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pClassType | The class that was loaded.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

IRemoteProcessCallbackEx::ClassUnloadEvent

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

HRESULT ClassUnloadEvent(IRemoteThread *pThread,
     IRemoteClassField *pClassType)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.
[in] pClassType | The class that was unloaded.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.

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)
Parameter | Description
[in] pThread | The thread object that represents the thread that generated the event.


Static Information Interfaces

Static information on a Java process is available through the IRemoteField hierarchy of interfaces. These interfaces represent fields that are members of classes. These fields can be methods, objects, inner classes, or nested class definitions. Because all the attributes of a field are constant during its lifetime, this information can be cached by the debugger.

The static information interfaces consist primarily of the IRemoteField interface and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, classes, methods, and so on) that inherit from IRemoteField or from other interfaces that extend IRemoteField.

IRemoteField : IUnknown

The IRemoteField hierarchy of interfaces represents fields that are members of classes. These fields can be methods, objects, or nested class definitions. You can think of global classes (classes not defined within other classes) as being fields of a global class. This is shown in the following example.

class <globals>                           // FIELD_KIND_CLASS
{
    class FooClass                        // FIELD_KIND_CLASS
   {
       boolean bDone;                     // FIELD_KIND_DATA_PRIMITIVE
       class BarClass                     // FIELD_KIND_CLASS
      {
           String username[20];           // FIELD_KIND_ARRAY
      }
      BarClass mybar;                     // FIELD_KIND_DATA_OBJECT
      int BarMethod();                    // FIELD_KIND_METHOD
    };
};

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class containing the field is unloaded.

IRemoteField::GetName

The GetName method returns the identifier (the class, variable, or method name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the identifier for this field; for example, "FooClass", "m_i", "m_bar", "Method", and so on.

IRemoteField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The following Java code sample illustrates the FIELDKINDs for a sample Java class.

class <globals>                           // FIELD_KIND_CLASS
{
    class FooClass                        // FIELD_KIND_CLASS
   {
       boolean bDone;                     // FIELD_KIND_DATA_PRIMITIVE
       class BarClass                     // FIELD_KIND_CLASS
      {
           String username[20];           // FIELD_KIND_ARRAY
      }
      BarClass mybar;                     // FIELD_KIND_DATA_OBJECT
      int BarMethod();                    // FIELD_KIND_METHOD
    };
};

IRemoteField::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this field can be determined.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on). When this method is called on a global container field, the method returns S_OK and the IRemoteField object returned representing the type is NULL.

For primitive data objects, if the GetType method is called on the returned IRemoteField, this method call will return the class corresponding to the type of the object. For a boolean, it will return a boolean class. Calling GetName will returns the Unicode string “boolean” and calling GetKind will return FIELD_KIND_CLASS.

For array data objects, if the GetType method is called on the returned IRemoteField, this method call will return another IRemoteField for element type of the array. The element type can be another array, a class, or a primitive class (boolean, byte, char, and so on). Calling GetKind on this returned IRemoteField will return either the FIELD_KIND_CLASS bit set (for an arrays of classes or an array of primitives) or the FIELD_KIND_ARRAY bit set for an array of arrays.

There are two techniques that can be used to determine the element type of an array of primitives.

The debugger can call GetName on the IRemoteField of the element type of the array, which returns the primitive class name. The returned value for GetName can be compared with the eight primitive class names.

A debugger can compare the IUnknown pointer for the IRemoteField of the element type to the IUnknown pointer for a primitive class. The IUnknown pointer for this element type can be returned by calling the QueryInterface on the IRemoteField. The IUnknown pointer for the primitive classes can be determined by calling IRemoteProcess::FindClass for the primitive class (boolean, byte, char, and so on) to retrieve an IRemoteClassField. The IUnknown pointer for a primitive class can be returned by calling the QueryInterface on the IRemoteClassField. For efficiency when using this technique, a debugger might

IRemoteField::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the field. For example, calling this method on the field that represents "username" described under the GetKind method will return the field for its containing class "BarClass".

IRemoteField::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteDataField : IRemoteField

The IRemoteDataField object represents a field that is not a method or a class definition. This interface inherits from IRemoteField. This interface is not used except as a base interface for IRemoteArrayField.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class containing the field is unloaded.

IRemoteDataField::GetName

The GetName method returns the identifier (the variable name) for this data field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns a Unicode string identifier for this data field.

IRemoteDataField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this data field, which is FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ored) with FIELD_KIND_PARAM.

IRemoteDataField::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this field can be determined.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on).

IRemoteDataField::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the data field.

IRemoteDataField::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteArrayField : IRemoteDataField

The IRemoteArrayField object represents arrays (special data fields). The only major difference between data and arrays (IRemoteDataField and IRemoteArrayField) is that arrays have a size. This interface inherits from IRemoteDataField.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class containing the array field is unloaded.

A debugger application cannot access the elements of an array through an IRemoteArrayField because the field is not bound to an instance of the array. The IRemoteArrayObject interface can be used to extract the elements from an instance of an array.

IRemoteArrayField::GetName

The GetName method returns the identifier (the variable name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns a Unicode string identifier for this field.

IRemoteArrayField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field that has the FIELD_KIND_ARRAY bitmask set.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following 0two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

IRemoteArrayField::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this field can be determined.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on).

IRemoteArrayField::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the array.

IRemoteArrayField::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteArrayField::GetSize

The GetSize method returns the number of elements in an array.

HRESULT GetSize(ULONG *pcElements)

Parameter | Description
[out] pcElements | Returns the number of elements in an array.

IRemoteContainerField : IRemoteField

The IRemoteContainerField represents fields that contain other fields. This interface inherits from IRemoteField.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class containing the container field is unloaded.

IRemoteContainerField::GetName

The GetName method returns the identifier (the class, variable, or method name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the identifier for this field; for example, "FooClass".

IRemoteContainerField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ored) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The following Java code sample illustrates the FIELDKINDs for a sample Java class.

class <globals>                           // FIELD_KIND_CLASS
{
    class FooClass                        // FIELD_KIND_CLASS
   {
       boolean bDone;                     // FIELD_KIND_DATA_PRIMITIVE
       class BarClass                     // FIELD_KIND_CLASS
      {
           String username[20];           // FIELD_KIND_ARRAY
      }
      BarClass mybar;                     // FIELD_KIND_DATA_OBJECT
      int BarMethod();                    // FIELD_KIND_METHOD
    };
};

IRemoteContainerField::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this field can be determined.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on). When this method is called on a global container field, the method returns S_OK and the IRemoteField object returned representing the type is NULL.

IRemoteContainerField::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the field. For example, calling this method on the field that represents "username" described under the GetKind method will return the field for its containing class "BarClass".

IRemoteContainerField::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteContainerField::GetFields

The GetFields method returns an enumerator (IJavaEnumRemoteField) for the fields that are contained by this field and match given characteristics.

HRESULT GetFields(IEnumRemoteField **ppEnum, FIELDKIND ulKind,
     FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)

Parameter | Description
[out] ppEnum | Returns an enumerator for the fields that are contained by this field and match the given characteristics.
[in] ulKind | A bitmask of flags indicating the kinds of fields to be included in the enumeration. Use 0 (zero) to include all field kinds.
[in] ulModifiers | A bitmask of flags indicating the modifiers of fields to be included in the enumeration. Use 0 (zero) to include all field modifiers.
[in] lpcszName | The name of the field to be included in the enumeration. Use NULL to include all names.

Remarks

The characteristics are determined by three parameters passed to the method that specify the name of the field, the field modifiers bitmask, and the field kind. A null parameter passed for the name is used to include all names. A bitmask of 0is used to include all field modifiers. A FIELD_KIND of 0 is used to include all field kinds.

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The field modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteClassField : IRemoteContainerField

The IRemoteClassField represents a class definition. This interface inherits from IRemoteContainerField.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class containing the field is unloaded.

IRemoteClassField::GetName

The GetName method returns the identifier (the class name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the identifier for this field; for example, "FooClass".

IRemoteClassField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field, FIELD_KIND_CLASS.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

IRemoteClassField::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns NULL for a Class field.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on). When this method is called on a global container field, the method returns S_OK and the IRemoteField object returned representing the type is NULL.

IRemoteClassField::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the field. For example, calling this method on the field that represents "username" described under the GetKind method will return the field for its containing class "BarClass".

IRemoteClassField::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteClassField::GetFields

The GetFields method returns an enumerator (IJavaEnumRemoteField) for the fields that are contained by this class and match given characteristics.

HRESULT GetFields(IEnumRemoteField **ppEnum, FIELDKIND ulKind,
     FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)

Parameter | Description
[out] ppEnum | Returns an enumerator for the fields that are contained by this field and match the given characteristics.
[in] ulKind | A bitmask of flags indicating the kinds of fields to be included in the enumeration. Use 0 (zero) to include all field kinds.
[in] ulModifiers | A bitmask of flags indicating the modifiers of fields to be included in the enumeration. Use 0 (zero) to include all field modifiers.
[in] lpcszName | The name of the field to be included in the enumeration. Use NULL to include all names.

Remarks

The characteristics are determined by three parameters passed to the method that specify the name of the field, the field modifiers bitmask, and the field kind. A null parameter passed for the name is used to include all names. A bitmask of 0 is used to include all field modifiers. A FIELD_KIND of 0 is used to include all field kinds.

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The field modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteClassField::GetFileName

The GetFileName method returns the full name of the class if it is available (C:\classes\HelloWorld.class, for example).

HRESULT GetFileName(LPOLESTR *ppszFileName)

Parameter | Description
[out] ppszFileName | Returns the full path of the file that contains this class if it is available; for example, "c:\classes\HelloWorld.class".

IRemoteClassField::GetSourceFileName

The GetSourceFileName method returns the name of the source file attribute (“SourceFile”) from the class file if it is available (HelloWorld.java, for example).

HRESULT GetSourceFileName(LPOLESTR *ppszSourceFileName)

Parameter | Description
[out] ppszSourceFileName | Returns the name of the source file used to create this class; for example, "HelloWorld.java".

IRemoteClassField::GetSuperClass

The GetSuperClass method returns the class (an IRemoteClassField) from which this class is derived. For Java.Lang.Object, the top of the hierarchy, this method returns NULL.

HRESULT GetSuperclass(IRemoteClassField **ppSuperclass)

Parameter | Description
[out] ppSuperclass | Returns the class from which this class is derived.

IRemoteClassField::GetInterfaces

The GetInterfaces method returns an enumerator (IJavaEnumRemoteField) for the interfaces that this class implements.

HRESULT GetInterfaces(IJavaEnumRemoteField **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the interfaces that this class implements.

Remarks

If the class has no interfaces, an enumerator is returned that enumerates nothing.

IRemoteClassField::GetConstantPoolItem

The GetConstantPoolItem method returns the raw contents for the constant pool and is used for disassembly. Any indices contained within the constant pool item are converted from big endian order to platform byte order.

HRESULT GetConstantPoolItem(ULONG indexCP, BYTE **ppCPBytes, ULONG *plength)

Parameter | Description
[in] indexCP | Index in the constant pool of this class of the entry to be retrieved.
[out] ppCPBytes | Returns the constant pool data of the requested entry.
[out] plength | Returns the length of the returned constant pool entry, in bytes.

Remarks

The constant pool items are defined by an initial tag byte that indicates the format of the item stored followed the specific information for that constant entry. The constant pool tag bytes are defined as shown in the following table.

enum | Value | Description
CP_CONSTANT_UTF8 | 1 | A UCS Transformation Format (UTF-8) string used to represent constant string values encoded in a structure with a two-byte length preceding the string.
CP_CONSTANT_UNICODE | 2 | A Unicode string with a two-byte length preceding the string.
CP_CONSTANT_INTEGER | 3 | A 32-bit integer constant.
CP_CONSTANT_FLOAT | 4 | A 32-bit single-precision floating point constant.
CP_CONSTANT_LONG | 5 | A 64-bit long constant.
CP_CONSTANT_DOUBLE | 6 | A 64-bit double precision floating-point constant.
CP_CONSTANT_CLASS | 7 | A 16-bit index to a UTF-8 constant name.
CP_CONSTANT_STRING | 8 | A 16-bit index to a UTF-8 constant string.
CP_CONSTANT_FIELDREF | 9 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_METHODREF | 10 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_ INTERFACEMETHODREF | 11 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_NAMETYPE | 12 | One 16-bit index to a name (UTF-8 constant) followed by a 16-bit index to a field or method descriptor (a UTF-8 constant) representing the type of a class or instance variable. The field or method descriptor is a series of characters defined in the Java Virtual Machine specification published by Sun Microsystems.

IRemoteClassFieldEx : IRemoteClassField

The IRemoteClassFieldEx represents a class definition. This interface inherits from IRemoteClassField adding one new method.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class is unloaded.

IRemoteClassFieldEx::GetName

The GetName method returns the identifier (the class name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the identifier for this field; for example, "FooClass".

IRemoteClassFieldEx::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field, FIELD_KIND_CLASS.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

IRemoteClassFieldEx::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns NULL for a Class field.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on). When this method is called on a global container field, the method returns S_OK and the IRemoteField object returned representing the type is NULL.

IRemoteClassFieldEx::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the field.

IRemoteClassFieldEx::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteClassFieldEx::GetFields

The GetFields method returns an enumerator (IJavaEnumRemoteField) for the fields that are contained by this class and match given characteristics.

HRESULT GetFields(IEnumRemoteField **ppEnum, FIELDKIND ulKind,
     FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)

Parameter | Description
[out] ppEnum | Returns an enumerator for the fields that are contained by this field and match the given characteristics.
[in] ulKind | A bitmask of flags indicating the kinds of fields to be included in the enumeration. Use 0 (zero) to include all field kinds.
[in] ulModifiers | A bitmask of flags indicating the modifiers of fields to be included in the enumeration. Use 0 (zero) to include all field modifiers.
[in] lpcszName | The name of the field to be included in the enumeration. Use NULL to include all names.

Remarks

The characteristics are determined by three parameters passed to the method that specify the name of the field, the field modifiers bitmask, and the field kind. A null parameter passed for the name is used to include all names. A bitmask of 0 is used to include all field modifiers. A FIELD_KIND of 0 is used to include all field kinds.

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The field modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteClassFieldEx::GetFileName

The GetFileName method returns the full name of the class if it is available (C:\classes\HelloWorld.class, for example).

HRESULT GetFileName(LPOLESTR *ppszFileName)

Parameter | Description
[out] ppszFileName | Returns the full path of the file that contains this class if it is available; for example, "c:\classes\HelloWorld.class".

IRemoteClassFieldEx::GetSourceFileName

The GetSourceFileName method returns the name of the source file attribute (“SourceFile”) from the class file if it is available (HelloWorld.java, for example).

HRESULT GetSourceFileName(LPOLESTR *ppszSourceFileName)

Parameter | Description
[out] ppszSourceFileName | Returns the name of the source file used to create this class; for example, "HelloWorld.java".

IRemoteClassFieldEx::GetSourceFileDir

The GetSourceFileDir method returns the name of the source file directory attribute (“SourceDir”) from the class file if it is available.

HRESULT GetSourceFileDir(LPOLESTR *ppszSourceFileName)

Parameter | Description
[out] ppszSourceFileName | Returns the name of the source file directory attribute from the class file.

IRemoteClassFieldEx::GetSuperClass

The GetSuperClass method returns the class (an IRemoteClassField) from which this class is derived. For Java.Lang.Object, the top of the hierarchy, this method returns NULL.

HRESULT GetSuperclass(IRemoteClassField **ppSuperclass)

Parameter | Description
[out] ppSuperclass | Returns the class from which this class is derived.

IRemoteClassFieldEx::GetInterfaces

The GetInterfaces method returns an enumerator (IJavaEnumRemoteField) for the interfaces that this class implements.

HRESULT GetInterfaces(IJavaEnumRemoteField **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the interfaces that this class implements.

Remarks

If the class has no interfaces, an enumerator is returned that enumerates nothing.

IRemoteClassFieldEx::GetConstantPoolItem

The GetConstantPoolItem method returns the raw contents for the constant pool and is used for disassembly. Any indices contained within the constant pool item are converted from big endian order to platform byte order.

HRESULT GetConstantPoolItem(ULONG indexCP, BYTE **ppCPBytes,
     ULONG *plength)

Parameter | Description
[in] indexCP | The index in the constant pool of this class of the entry to be retrieved.
[out] ppCPBytes | Returns the constant pool data of the requested entry.
[out] plength | Returns the length of the returned constant pool entry, in bytes.

Remarks

The constant pool items are defined by an initial tag byte that indicates the format of the item stored followed the specific information for that constant entry. The constant pool tag bytes are defined as shown in the following table.

enum | Value | Description
CP_CONSTANT_UTF8 | 1 | A UCS Transformation Format (UTF-8) string used to represent constant string values encoded in a structure with a two-byte length preceding the string.
CP_CONSTANT_UNICODE | 2 | A Unicode string with a two-byte length preceding the string.
CP_CONSTANT_INTEGER | 3 | A 32-bit integer constant.
CP_CONSTANT_FLOAT | 4 | A 32-bit single-precision floating point constant.
CP_CONSTANT_LONG | 5 | A 64-bit long constant.
CP_CONSTANT_DOUBLE | 6 | A 64-bit double precision floating-point constant.
CP_CONSTANT_CLASS | 7 | A 16-bit index to a UTF-8 constant name.
CP_CONSTANT_STRING | 8 | A 16-bit index to a UTF-8 constant string.
CP_CONSTANT_FIELDREF | 9 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_METHODREF | 10 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_ INTERFACEMETHODREF | 11 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_NAMETYPE | 12 | One 16-bit index to a name (UTF-8 constant) followed by a 16-bit index to a field or method descriptor (a UTF-8 constant) representing the type of a class or instance variable. The field or method descriptor is a series of characters defined in the Java Virtual Machine specification published by Sun Microsystems.

IRemoteInnerClassField : IRemoteClassFieldEx

The IRemoteInnerClassField represents an inner class definition. This interface inherits from IRemoteClassFieldEx adding several new methods.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information until the class containing the field is unloaded.

IRemoteInnerClassField::GetName

The GetName method returns the identifier (the class name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the identifier for this field; for example, "FooClass".

IRemoteInnerClassField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field, FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

IRemoteInnerClassField::GetType

The GetType method returns an IRemoteField object that represents the type of this field.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns NULL for a Class field.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on). When this method is called on a global container field, the method returns S_OK and the IRemoteField object returned representing the type is NULL.

IRemoteInnerClassField::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains the field.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains the field.

IRemoteInnerClassField::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteInnerClassField::GetFields

The GetFields method returns an enumerator (IJavaEnumRemoteField) for the fields that are contained by this class and match given characteristics.

HRESULT GetFields(IEnumRemoteField **ppEnum, FIELDKIND ulKind,
     FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)

Parameter | Description
[out] ppEnum | Returns an enumerator for the fields that are contained by this field and match the given characteristics.
[in] ulKind | A bitmask of flags indicating the kinds of fields to be included in the enumeration. Use 0 (zero) to include all field kinds.
[in] ulModifiers | A bitmask of flags indicating the modifiers of fields to be included in the enumeration. Use 0 (zero) to include all field modifiers.
[in] lpcszName | The name of the field to be included in the enumeration. Use NULL to include all names.

Remarks

The characteristics are determined by three parameters passed to the method that specify the name of the field, the field modifiers bitmask, and the field kind. A null parameter passed for the name is used to include all names. A bitmask of 0 is used to include all field modifiers. A FIELD_KIND of 0 is used to include all field kinds.

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The field modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteInnerClassField::GetFileName

The GetFileName method returns the full name of the class if it is available (C:\classes\HelloWorld.class, for example).

HRESULT GetFileName(LPOLESTR *ppszFileName)

Parameter | Description
[out] ppszFileName | Returns the full path of the file that contains this class if it is available; for example, "c:\classes\HelloWorld.class".

IRemoteInnerClassField::GetSourceFileName

The GetSourceFileName method returns the name of the source file attribute (“SourceFile”) from the class file if it is available (HelloWorld.java, for example).

HRESULT GetSourceFileName(LPOLESTR *ppszSourceFileName)

Parameter | Description
[out] ppszSourceFileName | Returns the name of the source file used to create this class; for example, "HelloWorld.java".

IRemoteInnerClassField::GetSourceFileDir

The GetSourceFileDir method returns the name of the source file directory attribute (“SourceDir”) from the class file (if it is available).

HRESULT GetSourceFileDir(LPOLESTR *ppszSourceFileName)

Parameter | Description
[out] ppszSourceFileName | Returns the name of the source file directory attribute from the class file.

IRemoteInnerClassField::GetSuperClass

The GetSuperClass method returns the class (an IRemoteClassField) from which this class is derived. For Java.Lang.Object, the top of the hierarchy, this method returns NULL.

HRESULT GetSuperclass(IRemoteClassField **ppSuperclass)

Parameter | Description
[out] ppSuperclass | Returns the class from which this class is derived.

IRemoteInnerClassField::GetInterfaces

The GetInterfaces method returns an enumerator (IJavaEnumRemoteField) for the interfaces that this class implements.

HRESULT GetInterfaces(IJavaEnumRemoteField **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the interfaces that this class implements.

Remarks

If the class has no interfaces, an enumerator is returned that enumerates nothing.

IRemoteInnerClassField::GetConstantPoolItem

The GetConstantPoolItem method returns the raw contents for the constant pool and is used for disassembly. Any indices contained within the constant pool item are converted from big endian order to platform byte order.

HRESULT GetConstantPoolItem(ULONG indexCP, BYTE **ppCPBytes,
     ULONG *plength)

Parameter | Description
[in] indexCP | The index in the constant pool of this class of the entry to be retrieved.
[out] ppCPBytes | Returns the constant pool data of the requested entry.
[out] plength | Returns the length of the returned constant pool entry, in bytes.

Remarks

The constant pool items are defined by an initial tag byte that indicates the format of the item stored followed the specific information for that constant entry. The constant pool tag bytes are defined as shown in the following table.

enum | Value | Description
CP_CONSTANT_UTF8 | 1 | A UCS Transformation Format (UTF-8) string used to represent constant string values encoded in a structure with a two-byte length preceding the string.
CP_CONSTANT_UNICODE | 2 | A Unicode string with a two-byte length preceding the string
CP_CONSTANT_INTEGER | 3 | A 32-bit integer constant.
CP_CONSTANT_FLOAT | 4 | A 32-bit single-precision floating point constant.
CP_CONSTANT_LONG | 5 | A 64-bit long constant.
CP_CONSTANT_DOUBLE | 6 | A 64-bit double precision floating-point constant.
CP_CONSTANT_CLASS | 7 | A 16-bit index to a UTF-8 constant name.
CP_CONSTANT_STRING | 8 | A 16-bit index to a UTF-8 constant string.
CP_CONSTANT_FIELDREF | 9 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_METHODREF | 10 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_ INTERFACEMETHODREF | 11 | A 16-bit index to a class followed by a 16-bit index to a name_and_type.
CP_CONSTANT_NAMETYPE | 12 | One 16-bit index to a name (UTF-8 constant) followed by a 16-bit index to a field or method descriptor (a UTF-8 constant) representing the type of a class or instance variable. The field or method descriptor is a series of characters defined in the Java Virtual Machine specification published by Sun Microsystems.

IRemoteInnerClassField::GetInnerClassName

The GetInnerClassName method returns the actual class name, not the mangled class name from the Java compiler.

HRESULT GetInnerClassName (LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the actual class name.

IRemoteInnerClassField::GetInnerClassModifiers

The GetInnerClassModifiers method returns the real field modifiers for the inner class.

HRESULT GetInnerClassModifiers (FIELDMODIFIERS *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns the actual modifiers for an inner class.

IRemoteInnerClassField::GetOuterClass

The GetOuterClass method returns an IRemoteClassField representing the outer class.

HRESULT GetOuterClass(IRemoteClassField **ppOuterClass)

Parameter | Description
[out] ppOuterClass | Returns the outer class for this inner class.

IRemoteMethodField : IRemoteContainerField

The IRemoteMethodField represents a method within a class. This interface inherits from IRemoteContainerField. In addition to the methods supported by IRemoteContainerField,

This interface implements a number of methods that can be used by a debugger to set and clear breakpoints, get line number info, return Java bytecodes, and other information.

Because all the attributes of a field are constant during its lifetime, the debugger can cache this information.

IRemoteMethodField::GetName

The GetName method returns the identifier (the method name) for this field.

HRESULT GetName(LPOLESTR *ppszName)

Parameter | Description
[out] ppszName | Returns the identifier for this field; for example, "SortMethod".

IRemoteMethodField::GetKind

The GetKind method returns the kind (FIELD_KIND enum) of this field.

HRESULT GetKind(FIELDKIND *pKind)

Parameter | Description
[out] pKind | Returns the kind of this field, FIELD_KIND_METHOD.

Remarks

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

IRemoteMethodField::GetType

The GetType method returns an IRemoteField object that represents the return type of this method.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the return type of this method can be determined.

Remarks

The relationship between a field and its type depends on the FIELD_KIND of the field. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on).

IRemoteMethod::GetContainer

The GetContainer method returns an IRemoteContainerField object representing the class that contains this method.

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameter | Description
[out] ppContainer | Returns the field representing the class that contains this method.

IRemoteMethod::GetModifiers

The GetModifiers method returns a bitmask of flags containing the modifiers (FIELDMODIFIERS enum) for this field. If a bit is set, the type is modified in that way.

HRESULT GetModifiers(ULONG *pulModifiers)

Parameter | Description
[out] pulModifiers | Returns a bitmask of flags containing the modifiers for this type.

Remarks

Fields also have a set of modifiers contained in a flag attribute bitmask. These modifier bits are the same as those used in the access_flags field of the class file header. These bitmasks are defined in Java Virtual Machine specification published by JavaSoft.

These modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteMethodField::GetFields

The GetFields method returns an enumerator (IJavaEnumRemoteField) for the fields that are contained by this field and match given characteristics.

HRESULT GetFields(IEnumRemoteField **ppEnum, FIELDKIND ulKind,
     FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)

Parameter | Description
[out] ppEnum | Returns an enumerator for the fields that are contained by this field and match the given characteristics.
[in] ulKind | A bitmask of flags indicating the kinds of fields to be included in the enumeration. Use 0 (zero) to include all field kinds.
[in] ulModifiers | A bitmask of flags indicating the modifiers of fields to be included in the enumeration. Use 0 (zero) to include all field modifiers.
[in] lpcszName | The name of the field to be included in the enumeration. Use NULL to include all names.

Remarks

The characteristics are determined by three parameters passed to the method that specify the name of the field, the field modifiers bitmask, and the field kind. A null parameter passed for the name is used to include all names. A bitmask of 0 is used to include all field modifiers. A FIELD_KIND of 0 is used to include all field kinds.

Fields are classified and defined by the FIELDKIND enum as shown in the following table.

FIELDKIND enum | Value | Description
FIELD_KIND_DATA_OBJECT | 0x0001 | A class instance.
FIELD_KIND_DATA_PRIMITIVE | 0x0002 | A primitive Java data type.
FIELD_KIND_ARRAY | 0x0004 | An array.
FIELD_KIND_CLASS | 0x0008 | A Java class.
FIELD_KIND_METHOD | 0x0010 | A Java class method.
FIELD_KIND_LOCAL | 0x1000 | A local variable in a Java method.
FIELD_KIND_PARAM | 0x2000 | A parameter passed to a Java method.
FIELD_KIND_THIS | 0x4000 | A THIS pointer to an object.
FIELD_KIND_INNER_CLASS | 0x8000 | A Java inner class.

The field kind for an IRemoteField object can be a class (FIELD_KIND_CLASS), a method (FIELD_KIND_METHOD), or a field representing data. For fields representing data objects, the field kind returned will be a bitmask combined from the following two groups.

FIELD_KIND_DATA_OBJECT, FIELD_KIND_DATA_PRIMITIVE, or FIELD_KIND_ARRAY

FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS

For example, an array passed as a parameter to a method would have a field kind consisting of FIELD_KIND_ARRAY combined (ORed) with FIELD_KIND_PARAM.

For an inner class, the field kind consists of FIELD_KIND_CLASS combined with FIELD_KIND_INNER_CLASS. For a class field, the container field is FIELD_KIND_CLASS.

The field modifier bits are defined by the FIELDMODIFIERS enum as shown in the following table.

FIELDMODIFIERS enum | Value | Description
FIELD_ACC_PUBLIC | 0x0001 | Is public and may be accessed from outside its package (visible to everyone). This modifier can be applied to any class, interface, field, or method.
FIELD_ACC_PRIVATE | 0x0002 | Is private and usable only within the defining class. This modifier can be applied to a class, method, or class field.
FIELD_ACC_PROTECTED | 0x0004 | Is protected and may be accessed within this class and subclasses. This modifier can be applied to any class, method, or class field.
FIELD_ACC_STATIC | 0x0008 | A static field or method. This modifier can be applied to any class, method, or field.
FIELD_ACC_FINAL | 0x0010 | Is final and no further subclassing or assignment is allowed. This modifier can be applied to any class, method, or field.
FIELD_ACC_SYNCHRONIZED | 0x0020 | Use monitor lock when the method is invoked. This modifier can be applied to any class or method.
FIELD_ACC_VOLATILE | 0x0040 | The value of this field cannot be cached. This modifier can be applied to any class field.
FIELD_ACC_TRANSIENT | 0x0080 | This field cannot be read or written by a persistent object manager. This modifier can be applied to any class field.
FIELD_ACC_NATIVE | 0x0100 | This method is implemented using native code. This modifier can be applied to any class or method.
FIELD_ACC_INTERFACE | 0x0200 | Is an interface (used to distinguish between an interface and a class). This modifier is applied to an interface.
FIELD_ACC_ABSTRACT | 0x0400 | An abstract class or interface that may not be instantiated. This modifier can be applied to a class, an interface, or a method.
FIELD_ACC_SUPER | 0x0800 | Treat superclass methods specially in invokespecial (used for backward compatibility). This modifier can be applied to any class or interface.
FIELD_ACC_SYNTHETIC | 0x1000 | Set on fields that the compiler had to generate (used by inner classes).

IRemoteMethodField::SetBreakpoint

The SetBreakpoint method sets a code breakpoint at a given byte offset from the start of a method.

HRESULT SetBreakpoint(ULONG offPC)

Parameter | Description
[in] offPC | A byte offset within this method.

Remarks

The Microsoft VM will not validate the given location of the breakpoint; a breakpoint may be set at any offset within the method’s bytecodes. Breakpoints are reference counted and may be set multiple times at the same byte offset.

IRemoteMethodField::ClearBreakpoint

The ClearBreakpoint method clears a code breakpoint at a given byte offset from the start of a method. This method will only clear breakpoints set by SetBreakpoint.

HRESULT ClearBreakpoint(ULONG offPC)

Parameter | Description
[in] offPC | Byte offset within this method.

Remarks

If a breakpoint is set multiple times, it must be cleared the same number of times to eliminate it completely.

IRemoteMethodField::GetLineInfo

The GetLineInfo method returns an enumerator of LINEINFO structures (IJavaEnumLINEINFO objects) describing the mapping between source lines and byte offset within the Java bytecodes representing the method. This mapping is in order of increasing offsets. The last element in the list is a “dummy” node with a line number field set to the last line of the method + 1 and the offset field set to the last offset in the method +1.

HRESULT GetLineInfo(IEnumLINEINFO **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator of LINEINFO structures describing the mapping between source lines and byte offset within this method. This mapping is in order of increasing offsets. The last element in the list is a dummy node with the line number field set to (the last line of the method + 1) and the offset field set to (the last offset in the method + 1).

IRemoteMethodField::GetBytes

The GetBytes method returns an interface (ILockBytes) that can be used to access the Java bytecode of the method. This method can be used by a debugger to display a disassembly of the bytecode.

HRESULT GetBytes(ILockBytes **ppLockBytes)

Parameter | Description
[out] ppLockBytes | Returns an ILockBytes interface that you can use to access this method's bytecode.

IRemoteMethodField::GetScope

The GetScope method returns the range of byte offsets (within which the object is in scope) that can be used by a debugger to obtain the value of some field within this method.

HRESULT GetScope(IRemoteField *pField, ULONG *poffStart,
     ULONG *pcbScope)

Parameter | Description
[in] pField | The field whose scope within this method is to be determined.
[out] poffStart | The byte offset within this method where the scope of the given field begins.
[out] pcbScope | Length of the scope of the given field in this method, in bytes.

IRemoteMethodField::GetIndexedField

The GetIndexedField method returns a local variable or parameters field from a method by local variable index and byte offset.

HRESULT GetIndexedField(ULONG slot, ULONG offPC,  IRemoteField **ppField)

Parameter | Description
[in] slot | The slot in this method of the field to be retrieved.
[in] offPC | The byte offset within this method indicating the given slot's execution context.
[out] ppField | The field contained by the given slot at the given byte offset.

IEnumRemoteField : IUnknown

The IEnumRemoteField interface is used to enumerate all the fields contained within a class, method, or container.

IEnumRemoteField::Next

The Next method is used to retrieve an array of IRemoteField objects that represent the fields within a class, method, or container. The number of fields to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of IRemoteField objects requested to be retrieved.
[out] drgelt | The pointer to the array of IRemoteField objects that is retrieved.
[out] pceltFetched | The number of actual IRemoteField objects that was retrieved.

IEnumRemoteField::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)

Parameter | Description
[in] celt | The number of IRemoteField objects requested to be skipped.

IEnumRemoteField::Reset

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

HRESULT Reset(void)

IEnumRemoteField::Clone

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

HRESULT Clone(IJavaEnumRemoteField **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the fields in a class, method, or container representing the current position in the list of fields.

IEnumRemoteField::GetCount

The GetCount method returns the number of fields being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of fields pointed to by the enumerator object.

IJavaEnumRemoteField : IEnumRemoteField

The IJavaEnumRemoteField interface is used to enumerate all the fields contained within a class, method, or container. The IJavaEnumRemoteField object inherits from IEnumRemoteField, extending this interface with one additional method.

IJavaEnumRemoteField::Next

The Next method is used to retrieve an array of IRemoteField objects that represent the fields within a class, method, or container. The number of fields to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of IRemoteField objects requested to be retrieved.
[out] drgelt | The pointer to the array of IRemoteField objects that is retrieved.
[out] pceltFetched | The number of actual IRemoteField objects that was retrieved.

IJavaEnumRemoteField::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)

Parameter | Description
[in] celt | The number of IRemoteField objects requested to be skipped.

IJavaEnumRemoteField::Reset

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

HRESULT Reset(void)

IJavaEnumRemoteField::Clone

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

HRESULT Clone(IJavaEnumRemoteField **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the fields in a class, method, or container representing the current position in the list of fields.

IJavaEnumRemoteField::GetCount

The GetCount method returns the number of fields being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of fields pointed to by the enumerator object.

IJavaEnumRemoteField::GetNext

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

HRESULT GetNext(IRemoteField **ppirf)

Parameter | Description
[out] ppirf | The pointer to the IRemoteField object that is retrieved.

IEnumLINEINFO : IUnknown

Line number information represents the mapping between Java source code line numbers and byte offsets in the method. This information is represented as an array of LINEINFO structures maintained for each method. The IEnumLINEINFO interface provides access to this information.

IEnumLINEINFO::Next

The Next method is used to retrieve an array of LINEINFO structures that represent the mapping between Java source code line numbers and byte offsets in the method. The number of LINEINFO structures to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of LINEINFO structures requested to be retrieved.
[out] drgelt | The pointer to the array of LINEINFO structures that are retrieved.
[out] pceltFetched | The number of actual LINEINFO structures that was retrieved.

Remarks

The LINEINFO structure is defined as follows:

typedef struct lineinfo {
   USHORT iLine;      // line number
   USHORT offPC;      // byte offset in method
} LINEINFO;

IEnumLINEINFO::Skip

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

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of LINEINFO structures requested to be skipped.

IEnumLINEINFO::Reset

The Reset method sets or resets the positions of the enumerator to the beginning of the list of LINEINFO structures.

HRESULT Reset(void)

IEnumLINEINFO::Clone

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

HRESULT Clone(IJavaEnumLINEINFO **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object representing the current position in the list of LINEINFO structures.

IEnumLINEINFO::GetCount

The GetCount method returns the number of LINEINFO structures being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of LINEINFO structures pointed to by the enumerator object.

IJavaEnumLINEINFO : IEnumLINEINFO

Line number information represents the mapping between Java source code line numbers and byte offsets in the method. This information is represented as an array of LINEINFO structures maintained for each method. The IJavaEnumLINEINFO interface provides access to this information. This interface inherits from the IEnumLINEINFO interface add one new method.

IJavaEnumLINEINFO::Next

The Next method is used to retrieve an array of LINEINFO structures that represent the mapping between Java source code line numbers and byte offsets in the method. The number of LINEINFO structures to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of LINEINFO structures requested to be retrieved.
[out] drgelt | The pointer to the array of LINEINFO structures that are retrieved.
[out] pceltFetched | The number of actual LINEINFO structures that was retrieved.

Remarks

The LINEINFO structure is defined as follows:

typedef struct lineinfo {
   USHORT iLine;      // line number
   USHORT offPC;      // byte offset in method
} LINEINFO;

IJavaEnumLINEINFO::Skip

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

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of LINEINFO structures to be skipped.

IJavaEnumLINEINFO::Reset

The Reset method sets or resets the positions of the enumerator to the beginning of the list of LINEINFO structures.

HRESULT Reset(void)

IJavaEnumLINEINFO::Clone

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

HRESULT Clone(IJavaEnumLINEINFO **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object representing the current position in the list of LINEINFO structures.

IJavaEnumLINEINFO::GetCount

The GetCount method returns the number of LINEINFO structures being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of LINEINFO structures pointed to by the enumerator object.

IJavaEnumLINEINFO::GetNext

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

HRESULT GetNext(LPLINEINFO *pli)

Parameter | Description
[out] pli | The pointer to the LINEINFO structure that is retrieved.

Remarks

The LINEINFO structure is defined as follows:

typedef struct lineinfo {
   USHORT iLine;      // line number
   USHORT offPC;      // byte offset in method
} LINEINFO;


Dynamic Information Interfaces

Dynamic information on a Java process is available through the IRemoteObject hierarchy of interfaces. These interfaces provide bound access to objects of different types. An object does not necessarily refer to an instance of a class, but represents an instance of any type. The information obtained from an IRemoteObject is only valid during the lifetime of the actual object that it represents. Consequently, dynamic information cannot be cached by the debugger.

Access to dynamic information in a Java process is based on using the IRemoteThreadGroup and IRemoteThread passed on each ThreadGroupCreateEvent and ThreadCreateEvent notification to the debugger. The IRemoteProcess:GetGlobalContainerObject method can also be used to access the root of this object hierarchy and descend down it to retrieve IRemoteClassField objects.

The dynamic information interfaces consist primarily of IRemoteObject, IRemoteObjectEx, IEnumRemoteObject, the IEnumRemoteValue interfaces, and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, or classes) that inherit from IRemoteObject or IEnumRemoteValue.

IRemoteObject : IUnknown

The IremoteObject interface represents bound access to objects of different types in a Java process. An object does not necessarily refer to an instance of a class; it refers to an instance of any type.

The information obtained from an IRemoteObject is valid only during the lifetime of the actual object that it represents.

IRemoteObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on.).

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)
Remarks

For classes, the value of the object changes when the object references a different instance of that class, not when any of the instance's data members change. For arrays, the object is considered changed when a new array is assigned to this object, not when any of its elements change.

IRemoteObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteObjectEx : IRemoteObject

The IremoteObjectEx interface represents bound access to objects of different types in a Java process. An object does not necessarily refer to an instance of a class; it refers to an instance of any type. This interface inherits from IRemoteObject and adds three new methods.

The information obtained from IRemoteObjectEx is valid only during the lifetime of the actual object that it represents.

IRemoteObjectEx::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The type will be either a class type or a Java native object type (boolean, short, integer, long, and so on).

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns IRemoteField from which the type of this object can be determined.

IRemoteObjectEx::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)
Remarks

For classes, the value of the object changes when the object references a different instance of that class, not when any of the instance's data members change. For arrays, the object is considered changed when a new array is assigned to this object, not when any of its elements change.

IRemoteObjectEx::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteObjectEx::IsSameObject

The IsSameObject method indicates whether two objects are the same object.

HRESULT IsSameObject (IRemoteObject *other)

Parameter | Description
[in] other | The other object to compare with this object.

Remarks

A return value of S_OK indicates that the two objects are the same object.

IRemoteObjectEx::GetContainer

The GetContainer method returns IRemoteObject that represents the container for the current object. This methods allows a debugger to navigate back up the hierarchy of objects.

HRESULT GetContainer (IRemoteObject **ppContaainer)

Parameter | Description
[out] ppContainer | The object representing the container for the current object.

IRemoteObjectEx::GetIdentity

The GetIdentity method returns a new IRemoteObjectEx that is detached from its containers. This method is used for data breakpoints and allows a debugger to hang on to an object across execution.

HRESULT GetIdentity (IRemoteObjectEx *pIdentity)

Parameter | Description
[out] pIdentity | A new object representing the current object that is detached from its containers.

IRemoteBooleanObject : IRemoteObject

The IRemoteBooleanObject represents bound access to a boolean object in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from IRemoteBooleanObject is valid only during the lifetime of the actual object that it represents.

IRemoteBooleanObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for an IRemoteBooleanObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns IRemoteField from which the type of this object can be determined.

IRemoteBooleanObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteBooleanObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteBooleanObject::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_BOOLEAN *pvalue)

Parameter | Description
[out] pvalue | Returns the boolean value of this object.

IRemoteBooleanObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_BOOLEAN value)

Parameter | Description
[in] value | The boolean value that this object should be set to.

IRemoteByteObject : IRemoteObject

The IRemoteByteObject provides run-time access to the value of a byte variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from IRemoteByteObject is valid only during the lifetime of the actual object that it represents.

IRemoteByteObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for IRemoteByteObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns IRemoteField from which the type of this object can be determined.

IRemoteByteObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteByteObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteByteObject::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_BYTE *pvalue)

Parameter | Description
[out] pvalue | Returns the byte value of this object.

IRemoteByteObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_BYTE value)

Parameter | Description
[in] value | The byte value that this object should be set to.

IRemoteCharObject : IRemoteObject

The IRemoteCharObject provides run-time access to the value of a character variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from IRemoteCharObject is valid only during the lifetime of the actual object that it represents.

IRemoteCharObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for IRemoteCharObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns IRemoteField from which the type of this object can be determined.

IRemoteCharObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteCharObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteCharObject::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_CHAR *pvalue)

Parameter | Description
[out] pvalue | Returns the character value of this object.

IRemoteCharObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_CHAR value)

Parameter | Description
[in] value | The character value that this object should be set to.

IRemoteContainerObject : IRemoteObject

The IRemoteContainerObject provides run-time access to the container objects (FILED_KIND_CLASS or FIELD_KIND_METHOD) in a Java process. This interface inherits from IRemoteObject and adds one new method.

The information obtained from IRemoteContainerObject is valid only during the lifetime of the actual object that it represents.

IRemoteContainerObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. IRemoteContainerObject can be any of the FIELD_KINDs.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteContainerObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteContainerObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteContainerObject::GetFieldObject

The GetFieldObject method returns an IRemoteObject that represents the object contained within that IRemoteContainer object. The IRemoteObject object that is returned is bound to its container. IRemoteField can be used to extract the value of that field from many different IRemoteContainerObject instances in the same Java process. This method allows a debugger to navigate down the hierarchy of objects.

HRESULT GetFieldObject (IRemoteField *pField, IRemoteObject **ppFieldObject)

Parameter | Description
[in] pField | The field in the IRemoteContainer object that is requested.
[out] ppFieldObject | The field object representing this field in the container.

Remarks

The GetType method called on the returned IRemoteObject will return the original IRemoteField that was passed to the GetFieldObject method.

IRemoteClassObject : IRemoteContainerObject

The IRemoteClassObject provides run-time access to the container objects in a Java process. This interface inherits from IRemoteContainerObject and adds one new method.

The information obtained from IRemoteClassObject is valid only during the lifetime of the actual object that it represents.

IRemoteClassObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object, FIELD_KIND_DATA_OBJECT for IRemoteClassObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns IRemoteField from which the type of this object can be determined.

IRemoteClassObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteClassObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteClassObject::GetFieldObject

The GetFieldObject method returns IRemoteObject that represents the object contained in the field of this object. The IRemoteObject object that is returned is not bound to the instance of the object and can be used to extract the value of that field from many different IRemoteClassObject instances in the same Java process. This method allows a debugger to navigate down the hierarchy of objects.

HRESULT GetFieldObject (IRemoteField *pField, IRemoteObject **ppFieldObject)

Parameter | Description
[in] pField | The field in the IRemoteClass object that is requested.
[out] ppFieldObject | The field object representing this field in the container.

Remarks

The GetType method called on the returned IRemoteObject will return the original IRemoteField that was passed to the GetFieldObject method.

IRemoteClassObject::GetDerivedMostType

The GetDerivedMostType method returns an IRemoteClassField that represents the object's derived-most type. An example of a derived-most type would be a MyException class derived from the java.io.IOException class. This method would return the MyException class for the IRemoteClassField.

HRESULT GetDerivedMostType (IRemoteClassField **ppDerivedMostField)

Parameter | Description
[out] ppDerivedMostField | The object’s derived most type.

IRemoteDoubleObject : IRemoteObject

The IRemoteDoubleObject provides run-time access to the value of a double variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from an IRemoteDoubleObject is valid only during the lifetime of the actual object that it represents.

IRemoteDoubleObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for an IRemoteDoubleObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteDoubleObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteDoubleObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteDouble::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_DOUBLE *pvalue)

Parameter | Description
[out] pvalue | Returns the value of this object.

IRemoteDoubleObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_DOUBLE value)

Parameter | Description
[in] value | The value that this object should be set to.

IRemoteFloatObject : IRemoteObject

The IRemoteFloatObject provides run-time access to the value of a float variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from an IRemoteFloatObject is valid only during the lifetime of the actual object that it represents.

IRemoteFloatObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for an IRemoteFloatObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteFloatObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteFloatObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteFloat::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_FLOAT *pvalue)

Parameter | Description
[out] pvalue | Returns the value of this object.

IRemoteFloatObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_FLOAT value)

Parameter | Description
[in] value | The value that this object should be set to.

IRemoteIntObject : IRemoteObject

The IRemoteIntObject provides run-time access to the value of an integer variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from an IRemoteIntObject is valid only during the lifetime of the actual object that it represents.

IRemoteIntObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for an IRemoteIntObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteIntObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteIntObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteInt::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_INT *pvalue)

Parameter | Description
[out] pvalue | Returns the value of this object.

IRemoteIntObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_INT value)

Parameter | Description
[in] value | The value that this object should be set to.

IRemoteLong : IRemoteObject

The IRemoteLongObject provides run-time access to the value of a long variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from an IRemoteLongObject is valid only during the lifetime of the actual object that it represents.

IRemoteLongObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for an IRemoteLongObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteLongObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteLongObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteLong::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_LONG *pvalue)

Parameter | Description
[out] pvalue | Returns the value of this object.

IRemoteLongObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_LONG value)

Parameter | Description
[in] value | The value that this object should be set to.

IRemoteShortObject : IRemoteObject

The IRemoteShortObject provides run-time access to the value of a double variable in a Java process. This interface inherits from IRemoteObject and adds two new methods.

The information obtained from an IRemoteShortObject is valid only during the lifetime of the actual object that it represents.

IRemoteShortObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_DATA_PRIMITIVE bit will be set for an IRemoteShortObject.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns an IRemoteField from which the type of this object can be determined.

IRemoteShortObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)

IRemoteShortObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteShortObject::GetValue

The GetValue method returns the value of a primitive Java type.

HRESULT GetValue (JAVA_SHORT *pvalue)

Parameter | Description
[out] pvalue | Returns the value of this object.

IRemoteShortObject::SetValue

The SetValue method sets the value of a primitive Java type.

HRESULT SetValue (JAVA_SHORT value)

Parameter | Description
[in] value | The value that this object should be set to.

IRemoteArrayObject : IRemoteObject

The IRemoteArrayObject represents bound access to array objects of different types in a Java process. This interface inherits from IRemoteObject and adds three new methods.

The information obtained from an IRemoteArrayObject is valid only during the lifetime of the actual object that it represents.

IRemoteArrayObject::GetType

The GetType method returns the type of the object (an IRemoteField object). A debugger would normally then call the GetKind method of the IRemoteField interface to determine the FIELD_KIND of the object. The FIELD_KIND_ ARRAY bit will be set for an IRemoteArrayObject. The element type of the array can be determined by calling IRemoteField::GetType on the IRemoteField returned by the IRemoteArrayObject::GetType method.

HRESULT GetType(IRemoteField **ppType)

Parameter | Description
[out] ppType | Returns and IRemoteField from which the type of this object can be determined.

IRemoteArrayObject::SetBreakpoint

The SetBreakpoint method sets a data breakpoint on the object. The breakpoint fires when the value of the object changes.

HRESULT SetBreakpoint(void)
Remarks

For classes, the value of the object changes when the object references a different instance of that class, not when any of the instance's data members change. For arrays, the object is considered changed when a new array is assigned to this object, not when any of its elements change.

IRemoteArrayObject::ClearBreakpoint

The ClearBreakpoint method clears a data breakpoint on the object previously set with the SetBreakpoint method.

HRESULT ClearBreakpoint(void)

IRemoteArrayObject::GetElements

The GetElements method returns an enumerator for the elements of this array, starting at index 0.

HRESULT GetElementObjects(IJavaEnumRemoteObject **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the elements of this array, starting at index 0.

IRemoteArrayObject::GetSize

The GetElements method returns the number of elements in the array.

HRESULT GetSize(ULONG *pcElements)

Parameter | Description
[out] pcElements | Returns the number of elements in the array.

IRemoteArrayObject::GetElementValues

The GetElements method returns an enumerator for the values of the elements of this array, starting at index 0.

HRESULT GetElementValues(IJavaEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator for the values of the elements of this array, starting at index 0.

IEnumRemoteObject : IUnknown

The IEnumRemoteObject interface is used to enumerate field objects in a class or container (an IRemoteClassObject, IRemoteClassObjectEx, or IRemoteContainerObject) and elements in an array (an IRemoteArrayObject).

IEnumRemoteObject::Next

The Next method is used to retrieve an array of IRemoteObject objects that represent the objects within a class, a container, or an array. The number of objects to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of objects that is retrieved.
[out] pceltFetched | The number of actual objects that was retrieved.

IEnumRemoteObject::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)

Parameter | Description
[in] celt | The number of objects requested to be skipped.

IEnumRemoteObject::Reset

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

HRESULT Reset(void)

IEnumRemoteObject::Clone

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

HRESULT Clone(IJavaEnumRemoteObject **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the objects in a class, a container, or an array representing the current position in the list of objects.

IEnumRemoteObject::GetCount

The GetCount method returns the number of objects being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of objects pointed to by the enumerator object.

IJavaEnumRemoteObject : IEnumRemoteObject

The IJavaEnumRemoteObject interface is used to enumerate field objects in a class or container (an IRemoteClassObject, IRemoteClassObjectEx, or IRemoteContainerObject) and elements in an array (an IRemoteArrayObject).

IJavaEnumRemoteObject::Next

The Next method is used to retrieve an array of IRemoteObject objects that represent the objects within a class, a container, or an array. The number of objects to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of objects that is retrieved.
[out] pceltFetched | The number of actual objects that was retrieved.

IJavaEnumRemoteObject::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)

Parameter | Description
[in] celt | The number of objects to be skipped.

IJavaEnumRemoteObject::Reset

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

HRESULT Reset(void)

IJavaEnumRemoteObject::Clone

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

HRESULT Clone(IJavaEnumRemoteObject **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the objects in a class, a container, or an array representing the current position in the list of objects.

IJavaEnumRemoteObject::GetCount

The GetCount method returns the number of objects being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of objects pointed to by the enumerator object.

IJavaEnumRemoteObject::GetNext

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

HRESULT GetNext(IRemoteObject **ppiro)

Parameter | Description
[out] ppiro | The pointer to the IRemoteObject object that is retrieved.

IEnumRemoteValue : IUnknown

The IEnumRemoteValue interface and the interfaces that inherit from it are used to enumerate and retrieve the values of elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example). These interfaces provides contain type-safe methods for enumerating values of built-in types. These interfaces can only be used to retrieve the values of these Java primitive types.

IEnumRemoteValue::Skip

The Skip method moves the position of the array or data element enumeration forward. The number of array or data elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index or data list) to the beginning of the array or list.

HRESULT Reset(void)

IEnumRemoteValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteValue::GetCount

The GetCount method returns the number of elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements in the array pointed to by the enumerator object.

IEnumRemoteBooleanValue : IEnumRemoteValue

The IEnumRemoteBooleanValue interface is used to enumerate and retrieve the boolean values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type boolean. This interface can only be used to retrieve the values of boolean data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteBooleanValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteBooleanValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteBooleanValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteBooleanValue::GetCount

The GetCount method returns the number of elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements in the array pointed to by the enumerator object.

IEnumRemoteBooleanValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteByteValue : IEnumRemoteValue

The IEnumRemoteByteValue interface is used to enumerate and retrieve the byte values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type byte. This interface can only be used to retrieve the values of byte data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteByteValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteByteValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteByteValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteByteValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IEnumRemoteByteValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteCharValue : IEnumRemoteValue

The IEnumRemoteCharValue interface is used to enumerate and retrieve the char values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type char. This interface can only be used to retrieve the values of char data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteCharValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteCharValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteCharValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteCharValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements that are available through this enumerator object.

IEnumRemoteCharValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteDoubleValue : IEnumRemoteValue

The IEnumRemoteDoubleValue interface is used to enumerate and retrieve the double values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type double. This interface can only be used to retrieve the values of double data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteDoubleValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteDoubleValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteDoubleValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteDoubleValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IEnumRemoteDoubleValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteFloatValue : IEnumRemoteValue

The IEnumRemoteFloatValue interface is used to enumerate and retrieve the float values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type float. This interface can only be used to retrieve the values of float data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteFloatValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteFloatValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteFloatValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteFloatValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IEnumRemoteFloatValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteIntValue : IEnumRemoteValue

The IEnumRemoteIntValue interface is used to enumerate and retrieve the integer values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type int. This interface can only be used to retrieve the values of int data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteIntValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteIntValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteIntValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteIntValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IEnumRemoteIntValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteLongValue : IEnumRemoteValue

The IEnumRemoteLongValue interface is used to enumerate and retrieve the long values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type long. This interface can only be used to retrieve the values of long data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteLongValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteLongValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteLongValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteLongValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IEnumRemoteLongValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IEnumRemoteShortValue : IEnumRemoteValue

The IEnumRemoteShortValue interface is used to enumerate and retrieve the short values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type short. This interface can only be used to retrieve the values of short data types.

This interface inherits from the IEnumRemoteValue interface adding one method.

IEnumRemoteShortValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IEnumRemoteShortValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IEnumRemoteShortValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IEnumRemoteShortValue::GetCount

The GetCount method returns the number of elements in the array or data list being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IEnumRemoteShortValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of data values requested to be retrieved.
[out] drgelt | The pointer to the array of values that was retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteBooleanValue : IEnumRemoteBooleanValue

The IJavaEnumRemoteBooleanValue interface is used to enumerate and retrieve the boolean values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type boolean. This interface can only be used to retrieve the values of boolean data types.

This interface inherits from the IEnumRemoteBooleanValue interface adding one method.

IJavaEnumRemoteBooleanValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteBooleanValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteBooleanValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteBooleanValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteBooleanValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumBooleanValue::GetNext

The GetNext method is used to retrieve the boolean value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_BOOLEAN *pjb)

Parameter | Description
[out] pjb | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when it is changed.

IJavaEnumRemoteByteValue : IEnumRemoteByteValue

The IJavaEnumRemoteByteValue interface is used to enumerate and retrieve the byte values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type byte. This interface can only be used to retrieve the values of byte data types.

This interface inherits from the IEnumRemoteByteValue interface adding one method.

IJavaEnumRemoteByteValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteByteValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteByteValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteByteValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteByteValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cached these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteByteValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_BYTE *pjbyte)

Parameter | Description
[out] pjbyte | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.

IJavaEnumRemoteCharValue : IEnumRemoteCharValue

The IJavaEnumRemoteCharValue interface is used to enumerate and retrieve the char values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type char. This interface can only be used to retrieve the values of char data types.

This interface inherits from the IEnumRemoteCharValue interface adding one method.

IJavaEnumRemoteCharValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteCharValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteCharValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteCharValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteCharValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteCharValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_CHAR *pjch)

Parameter | Description
[out] pjch | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.

IJavaEnumRemoteDoubleValue : IEnumRemoteDoubleValue

The IJavaEnumRemoteDoubleValue interface is used to enumerate and retrieve the double values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type double. This interface can only be used to retrieve the values of double data types.

This interface inherits from the IEnumRemoteDoubleValue interface adding one method.

IJavaEnumRemoteDoubleValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteDoubleValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteDoubleValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteDoubleValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteDoubleValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteDoubleValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_DOUBLE *pjdbl)

Parameter | Description
[out] pjdbl | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.

IJavaEnumRemoteFloatValue : IEnumRemoteFloatValue

The IJavaEnumRemoteFloatValue interface is used to enumerate and retrieve the float values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type float. This interface can only be used to retrieve the values of float data types.

This interface inherits from the IEnumRemoteFloatValue interface adding one method.

IJavaEnumRemoteFloatValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteFloatValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteFloatValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteFloatValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteFloatValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteFloatValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_FLOAT *pjflt)

Parameter | Description
[out] pjflt | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.

IJavaEnumRemoteIntValue : IEnumRemoteIntValue

The IJavaEnumRemoteIntValue interface is used to enumerate and retrieve the integer values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type int. This interface can only be used to retrieve the values of int data types.

This interface inherits from the IEnumRemoteIntValue interface adding one method.

IJavaEnumRemoteIntValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteIntValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteIntValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteIntValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteIntValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteIntValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_INT *pjn)

Parameter | Description
[out] pjn | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.

IJavaEnumRemoteLongValue : IEnumRemoteLongValue

The IJavaEnumRemoteLongValue interface is used to enumerate and retrieve the long values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type long. This interface can only be used to retrieve the values of long data types.

This interface inherits from the IEnumRemoteLongValue interface adding one method.

IJavaEnumRemoteLongValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteLongValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteLongValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteLongValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteLongValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteLongValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_LONG *pjl)

Parameter | Description
[out] pjl | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.

IJavaEnumRemoteShortValue : IEnumRemoteShortValue

The IJavaEnumRemoteShortValue interface is used to enumerate and retrieve the short values for elements of an array (IRemoteArrayObject) and other data variables (class data fields and method parameters, for example) of type short. This interface can only be used to retrieve the values of short data types.

This interface inherits from the IEnumRemoteShortValue interface adding one method.

IJavaEnumRemoteShortValue::Skip

The Skip method moves the position of the array enumeration (index) forward. The number of data or array elements to be skipped is based on a parameter passed to the method.

HRESULT Skip(ULONG celt)

Parameter | Description
[in] celt | The number of array elements requested to be skipped.

IJavaEnumRemoteShortValue::Reset

The Reset method sets or resets the positions of the enumerator (the array index) to the beginning of the array.

HRESULT Reset(void)

IJavaEnumRemoteShortValue::Clone

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

HRESULT Clone(IEnumRemoteValue **ppEnum)

Parameter | Description
[out] ppEnum | Returns an enumerator object pointing to the element in the array representing the current position in the array.

IJavaEnumRemoteShortValue::GetCount

The GetCount method returns the number of data elements in the array being pointed to by the enumerator object.

HRESULT GetCount (ULONG * pcelt)

Parameter | Description
[out] pcelt | The number of elements available through this enumerator object.

IJavaEnumRemoteShortValue::Next

The Next method is used to retrieve the value of several array or data elements pointed to by the enumerator object. The number of values to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

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

Parameter | Description
[in] celt | The number of objects requested to be retrieved.
[out] drgelt | The pointer to the array of values that is retrieved.
[out] pceltFetched | The number of actual values that was retrieved.

Remarks

The data values retrieved by this method are dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache these values unless data breakpoints are set on these data elements to indicate when these data elements are changed.

IJavaEnumRemoteShortValue::GetNext

The GetNext method is used to retrieve the value of the next array element or data item being pointed to by the enumerator object and increments the enumeration pointer by one.

HRESULT GetNext(JAVA_SHORT *pjsh)

Parameter | Description
[out] pjsh | A pointer to the current value of this data item.

Remarks

The data value retrieved by this method is dynamic and may be changed after further execution of the Java process. Consequently, a debugger cannot cache this value unless a data breakpoint is set on this data element to indicate when this data element is changed.


Introduction

This section describes the invocation interfaces, which include the following:
IJavaExecute
IJavaExecute2
IEnumJAVAPROPERTIES
Structures

See Structures for details about the structures these interfaces use.

The globally unique identifiers (GUIDs) for the invocation interfaces are defined in the file Javaexec.h.


IJavaExecute

// IUnknown methods
HRESULT QueryInterface(REFIID riid, LPVOID *ppv);
ULONG   AddRef();
ULONG   Release();

// IJavaExecute methods
HRESULT GetDefaultClassPath(LPOLESTR *ppszClassPath);
HRESULT Execute(LPJAVAEXECUTEINFO pjei, LPERRORINFO *pperrorinfo);

IJavaExecute::GetDefaultClassPath

HRESULT GetDefaultClassPath(LPOLESTR *ppszClassPath)

Sets ppszClassPath to a string describing the default class path (computed from the registry and the environment).

Parameter | Description
ppszClassPath | Address of the buffer to receive the class path. The elements in the class path are separated by semicolons, and elements are searched in the order they appear in the string.

Remarks:

The caller must free the returned string using the CoTaskMemFree function.

IJavaExecute::Execute

HRESULT Execute(LPJAVAEXECUTEINFO pJavaExecuteInfo, LPERRORINFO *ppErrorInfo);

Loads a Java class and executes its static main method.

The main method must have the following signature:

public static void main( String[] )

Return Value:

If the main method runs successfully and does not throw an uncaught Java exception, the Execute method returns S_OK, and ppErrorInfo is set to NULL.

If the main method runs successfully and throws an uncaught Java exception, the Execute method returns S_OK, and ppErrorInfo is set to an IErrorInfo object that describes the exception.

If the class is not found or does not expose a main method, or if there are insufficient resources to run the method, the Execute method returns a failing HRESULT.

Parameter | Description
pJavaExecuteInfo | This structure provides the name of the class, the arguments, and the execution environment. See JAVAEXECUTEINFO.
ppErrorInfo | Points to a buffer that receives an IErrorInfo interface object if the main method throws a Java exception. This parameter can be NULL if this information is not needed.


IJavaExecute2

// IUnknown methods
HRESULT QueryInterface(REFIID riid, LPVOID *ppv);
ULONG   AddRef();
ULONG   Release();

// IJavaExecute methods
HRESULT GetDefaultClassPath(LPOLESTR *ppszClassPath);
HRESULT Execute(LPJAVAEXECUTEINFO pjei, LPERRORINFO *pperrorinfo);

// IJavaExecute2 methods
HRESULT SetSystemProperties(LPENUMJAVAPROPERTY penum);
HRESULT SetClassSource(DWORD dwType, LPVOID pData, DWORD dwLen);

See also IJavaExecute.

IJavaExecute2::SetSystemProperties

HRESULT SetSystemProperties(LPENUMJAVAPROPERTY pEnumJavaProperty)

Sets property values for java.lang.System.

Parameter | Description
pEnumJavaProperty | Enumeration object that produces a set of key/value pairs. The SetSystemProperties method will enumerate through the entire collection and map each key to the associated value.

IJavaExecute2::SetClassSource

HRESULT SetClassSource(DWORD dwType, LPVOID pData, DWORD dwLen);

Inserts a special source of classes into the class path. These elements are searched before any other elements in the class path.

Parameter | Description
dwType Type of class source. The following types are recognized.
CLASS_SOURCE_TYPE_MODULERESOURCES
Allows classes to be stored within a Microsoft® Win32® resource.
CLASS_SOURCE_TYPE_ISTORAGE
Not currently implemented.

These values are defined in Javaexec.h

pData Address of an information structure whose format is type dependent.

For CLASS_SOURCE_TYPE_MODULERESOURCES, this is an address of a JAVACLASSRESOURCEINFO structure.

dwLen | Size in bytes of the structure pointed to by pData.


IEnumJAVAPROPERTIES

// IUnknown methods
HRESULT QueryInterface(REFIID riid, LPVOID *ppv);
ULONG   AddRef();
ULONG   Release();

// IEnumJavaPROPERTIES methods
ULONG   Next(ULONG celt, LPJAVAPROPERTY rgelt, ULONG *pceltFetched)
HRESULT Skip(ULONG celt)
HRESULT Reset()
HRESULT Clone(LPENUMJAVAPROPERTY *ppenum);

This enumerator lists key/value pairs for IJavaExecute2::SetSystemProperties.


Structures

JAVAEXECUTEINFO

typedef struct {
    DWORD     cbSize;
    DWORD     dwFlags;
    LPCOLESTR  pszClassName;
    LPCOLESTR *rgszArgs;
    ULONG     cArgs
    LPCOLESTR pszClassPath
} JAVAEXECUTEINFO, *LPJAVAEXECUTEINFO;

This structure is passed into IJavaExecute::Execute.

Parameter | Description
cbSize | Must be set to the size of JAVAEXECUTEINFO in bytes.
dwFlags Can be:
JEIF_VERIFYCLASSES Turn on verification of all classes. By default, the verification setting from the registry will be used.
pszClassName Name of the class to load. The class must have a public method that matches the signature:
public static void main(java.lang.String[]);
rgszArgs | Array of Unicode strings. This string is converted to a Java array of strings, which is then passed as the argument to the main method. The cArgs member indicates the number of strings in this array.
cArgs | Number of strings in rgszArgs.
pszClassPath Specifies additional class path elements (separated by semicolons). These class path elements will be searched before the elements in the default class path.

This member can be NULL if no additional elements are required.

Remarks:

The class path is a per-process variable. Any extensions made to the class path by means of the Execute method will persist after the Execute method has returned. Therefore, the Execute method is not suitable for use in a shared library.

See Also: IJavaExecute::Execute

JAVAPROPERTY

typedef struct {
    LPOLESTR pszKey;
    LPOLESTR pszValue;
}   JAVAPROPERTY, * LPJAVAPROPERTY;

This structure is used as part of IEnumJAVAPROPERTIES. The pszKey and pszValue members are both allocated using the CoTaskMemAlloc function, and are released by the caller of IEnumJAVAPROPERTIES::Next.

See Also: IEnumJAVAPROPERTIES

JAVACLASSRESOURCEINFO

struct {
    HMODULE   hModule;
    DWORD     dwResourceID;
};

This structure is passed to IJavaExecute::SetClassSource.

Parameter | Description
hModule | Handle to the module that contains the resource.
dwResourceID Identifies the resource that contains the class data. The resource must be of type RCDATA.

See JAVACLASSRESOURCE for the format of the resource data.

JAVACLASSRESOURCE

struct {
    DWORD dwSignature;
    DWORD dwNumClasses;
    DWORD dwFormatVersion;
    DWORD dwFlags;
    [Class Information Section]
    [Class Names Section]
    [Class Data Section]
};

Parameter | Description
dwSignature | Must be the value 0x43524E44.
dwNumClasses | Number of classes contained within this resource.
dwFormatVersion | Must be 1.
dwFlags | Reserved for future use.

Class Information Section:

The Class Information Section consists of an array of structures that detail the position of each class within the resource. Each class will have one of these structures. The format of this structure is:

struct {
    DWORD dwNameOffset;
    DWORD dwSize;
    DWORD dwDataOffset;
};
dwNameOffset | Offset from the beginning of the resource to the class name.
dwSize | Size of the class data.
dwDataOffset | Offset from the beginning of the resource to the class data.

Class Names Section:

The Class Names Section contains the names of the classes contained in the resource. The names are packed together, back-to-back, so that each name immediately follows the previous name. You must use a slash mark (/) to separate package names, and you must terminate each name with the null character.

Class Data Section:

The Class Data Section contains class file data for each class stored in the resource. The format for each class file is the same as the standard Java binary class file format.


Introduction

The following sections describe the Just-In-Time (JIT) compiler.
Background
JIT Structure
The JIT Compiler/VM Interface


Background

The standard model of a virtual machine (VM) for Java continually interprets a sequence of bytecodes that describe the intent of a Java applet or application. Each time the VM encounters a bytecode, whether it has interpreted it many times before or not, there is a (relatively) lengthy translation process. Even though various approaches exist for speeding up this approach somewhat, this interpretation process accounts for significantly slower execution performance compared to equivalent compiled native code.

To improve this performance, JIT compilers interact with the VM and compile appropriate bytecode sequences into an equivalent piece of native machine code. This process occurs at run time (that is, as the particular piece of code is going to be executed) rather than at compile time, as is traditionally the case with compiled languages such as C and C++. Rather than interpret the same bytecodes repeatedly, the hardware (the CPU) can run ("interpret") the native code. This can allow quite dramatic performance gains in the execution speed. There is, however, a tradeoff.

The time that the JIT compiler takes to compile the bytecodes is added to the overall execution time. For example, when a method executes only once and does not contain any loops, the overall performance might be reduced when JIT compilation occurs.

Note that JIT compilation has potential advantages over traditional code compilation techniques in some aspects: for example, it can target the specific machine on which the program is actually running (for example, 486 versus Pentium), rather than for a general CPU (or "the most likely" one), which is the best that traditional approaches (such as targeting a generic x86 platform) can achieve.


JIT Structure

The following diagram gives an overview of the JIT compiler's internal structure. The structure is similar to that used in typical static compiler environments. Bytecodes (together with requested symbol and other information) are converted ("imported") into an internal representation. The internal representation is then used to generate code, which is optimized appropriately. There is also a linker component that resolves references for the in-memory generated code, which is then ready to run.


The JIT Compiler/VM Interface

The following diagram illustrates the relationship between the JIT compiler and the Microsoft VM for Java.

The JIT compiler and the VM provide interfaces that both use to enable effective JIT code compilation. The "compilation unit" for the JIT compiler is a single method. The VM alone decides which method to compile. Tools vendors might want to provide facilities in their tools (for example, through language constructs or user interface) to augment .class files so that they indicate which methods to JIT (the precise format of such .class file attributes is TBD).

These interfaces are designed to allow clean separation and independence between the VM and the JIT compiler. This will enable other vendors to replace one JIT compiler with another, as appropriate.

A JIT compiler (vendor) can make the following assumptions.

  • Code and data blocks allocated through the respective VM helper functions will stay in place. Therefore, most references to methods and data members can be resolved at compilation time.
  • The first element in every object contains the reference to the respective class's vtable (method-pointer table).
  • For arrays (which are also Java objects) the offset for the element count as well as the offset for the first array element are always at the same fixed offset relative to the beginning of the object (array).
  • Every loaded interface is assigned a unique handle, which allows quick access at run time.
  • The vtable offsets of interface methods are always the same across all implementations of the interface. Therefore, all vtable offsets for methods can be resolved at compile time.

At the same time, the code and data that a JIT compiler generates for the Microsoft VM for Java must meet the following criteria.

  • All methods must have a local stack frame.
  • For the x86 platform, the calling convention is basically "__pascal": parameters must be pushed from left to right ("this" is pushed before any user arguments), the callee pops arguments, EBX/ESI/EDI are the callee-saved registers, and the FP stack is always empty on entry to methods, return values in EAX (32-bit scalars), EDX:EAX (64-bit integers), or on the FP stack (floats and doubles).
  • The JIT compiler must provide an API that enumerates all live references in a method while it calls a method (stack crawling support for GC).
  • Optionally, the JIT compiler may provide an API that enumerates all live references in a method at any time (this allows GC to occur at any time).
  • Currently only "base" pointers can be live at points where GC might occur (for example, the code might not have a pointer to the interior of an object/array that is live across a method call).
  • Code sharing across multiple namespaces is supported (optional).

The JIT compiler decides whether to allow interruption by the garbage collector at any time or just while a method calls another method. The latter is certainly easier to implement and needs less information at run time, but in certain scenarios it could disable the garbage collection process for an extended period of time (for example, a method executes a loop that does not contain a method call). In those cases, the JIT compiler must insert code that (conditionally) invokes the garbage collector directly unless it can be determined that the code will execute method calls frequently enough. To give the JIT maximal flexibility, it can make this decision for every method individually.

Beyond just generating code for a method, the JIT must provide additional information to enable proper execution and debugging of Java applications. Depending on the type of information, that is done in two ways:

  • Information defined by the VM: The JIT compiler provides this information at compile time to the VM, and the VM records and interprets it (for example, exception handler tables and line number information).
  • Private JIT information: The JIT compiler can store any private information along with each method so that it can provide the requested information to the VM at run time; the VM saves the information (to the VM it is just a single block of opaque data) and passes it back to the JIT compiler at run time (for example, enumeration of live object references in a stack frame, decision if a method is "GC-safe" at the current offset, and so on).


Introduction

This section provides an overview of the extended Microsoft Component Object Model (COM) attributes. These attributes are used to provide marshaling information between Java objects and COM objects. If a development environment generates these attributes, the Microsoft Win32 VM for Java (Microsoft VM) will use them to marshal parameters between COM and Java.
Java Object Categories
Identity of Java-Callable Wrappers and Java-Callable Data Wrappers
The Attribute Specification
Attribute Reference


Java Object Categories

In this model, all Java objects fall into one of the following categories.

  • Pure Java objects. These objects are allocated on the garbage-collected heap, and garbage collection controls their lifetime. Optionally, pure Java objects can have an associated proxy known as the COM-callable wrapper (CCW), which is a thread-safe, VM-created COM object that exports vtable or IDispatch interfaces. These proxies are implemented by the run time and marshal to methods on the Java object. As long as there is one outstanding AddRef method on the CCW, the CCW maintains a "root pointer" to the actual Java object to prevent it from being reclaimed.
  • Java-callable wrappers (JCWs). JCWs are stateless "wrapper" objects that represent a single COM object. JCWs can either be instances of special classes generated from typelibs, or be automatically made instances of the com.ms.com.CUnknown class. Unlike normal classes, which implement a fixed set of interfaces declared by the object's class, JCWs can be cast to any interface at will, provided that the underlying COM object accepts the QueryInterface of the interface's underlying IID (stored in attributes in the interface's .class file.) JCWs always inherit from java.lang.Object. They currently cannot derive from any other class.
  • Java-callable data wrappers (JCDWs). These are proxies for external data structures (structs, unions, and arrays.) In this case, the external data structure is passed in from native code through a COM interface. To avoid copying data, the proxy will maintain an address of the actual data, and the proxy's fields will be mapped by means of attributes to offsets within the data structure. A set of application programming interfaces (APIs) will allow byte-level traversal of the memory (as a fallback for very difficult structures such as DVTARGETDEVICE). Garbage collection controls a proxy's lifetime. Since no universal protocol exists for tracking an external data structure's lifetime, the burden is on the developer not to use the proxy after the underlying data structure has been released.


Identity of Java-Callable Wrappers and Java-Callable Data Wrappers

Java-callable wrappers (JCWs) for Component Object Model (COM) objects and proxies may contain Java-implemented methods, but no fields (other than those mapped to the underlying COM object) or any other dynamic state, because there is no way to specify a constructor to be called at marshaling time.

JCWs for COM objects will behave as expected with regard to the "==" operator. That is, "==" will yield a true value if and only if the underlying COM objects have the same IUnknown interface pointer.

The "==" operator will not be maintained for Java-callable data wrappers (data proxies). The cost of maintaining identity for data proxies (many of which will be temporary stack-allocated arguments) is too high and data proxies are already non-Java-like, in that their useful lifetimes are determined externally rather than by garbage collection.


The Attribute Specification

Working with MS VM
In this topic

* The type Attribute

* The ExposedAs Attribute

* The ProxiesTo Attribute

* The MapsTo Attribute

* Method and Type Descriptions

Microsoft VM | Previous | VM | Next
Overview of COM Attributes for Java Class Files | Previous | VM | Next

The Attribute Specification

This section describes the attributes at a semantic level without getting into representational issues.

Note that the attributes specify detail at the method level whenever possible. That is, while you customarily think of interfaces having IIDs, the attribute specification specifies an IID for each method, so that one Java interface could conceivably proxy to methods on multiple IIDs. For performance reasons, however, the first version of the Microsoft VM will not support this full generality. All methods on an interface will be required to have the same IID. The attribute language itself, however, is consciously designed not to obstruct future flexibility.

This section describes the attributes using an informal representation in which normal Java syntax is augmented by an "attribute syntax," where brackets contain attribute information. This should not be construed as recommending the syntax to use in a commercial development environment.

The type Attribute

This section's model divides Java classes into "pure," "Java-callable-wrappers," and "Java-callable data wrappers."

The allowable attributes are:

          class [type jcw <options>] foo {...}  // denotes a Java-callable wrapper
          class [type jcdw <options>] foo {...}  // denotes a Java-callable data wrapper

A given class has at most one type attribute. When no type attribute is present for a given class, the type of the class is determined as pure.

The type attribute can appear only in a class that derives directly from java.lang.Object. Interfaces do not have type attributes.

Java-Callable Wrappers

Java-callable wrappers (JCWs) are stateless proxies for a single COM object. JCWs can have an optional CLSID subattribute, which the following example shows.

   [type jcw {CLSID=....}]

Each instance of a JCW has an implicit marshaling mode that is determined using the parameter type attribute through which the JCW is created. The marshaling mode is either "NoMarshal" or "AutoMarshal".

If the marshaling mode is AutoMarshal, the JCW's home thread will be the thread that was current at the time the JCW was bound to the COM object. The JCW can be freely passed to other threads. However, calls to the JCW from outside threads will involve overhead due to marshaling back to the home thread. On a Microsoft® Win32® implementation, the home thread for an AutoMarshal JCW must process window messages on a regular basis. Otherwise, this thread will block other applications that attempt system-wide broadcasts.

If a class identifier (CLSID) is given, JCW classes can be used as the argument to the Java new operator. What happens then depends on the ThreadingModel (determined by the Threading Model registry entry for the CLSID).

If the ThreadingModel is "Free", the COM object is instantiated using the Win32 CoCreateInstance function on the current thread. The JCW can be passed around freely between threads and calls to it are never marshaled.

If the ThreadingModel is "Apartment", the object's home thread is either a special apartment thread or the current thread, depending on certain thread attributes that are outside the scope of this document. The JCW can be passed around freely between threads, but calls to it from outside the apartment thread will cause marshaling overhead.

If the ThreadingModel is "Single", the Microsoft VM switches to the hosting process's main Apartment thread to create the object. This thread is presumed to have a message loop.

Java-Callable Data Wrappers

Java-callable data wrappers (JCDWs) are stateless proxies for external data structures.

The ExposedAs Attribute

The ExposedAs attribute prescribes the external interface of COM-callable wrappers (CCWs) created for a given Java object. More specifically, for a given Java method or field, it describes whether it is exposed as a vtable or Dispatch interface; what IID it is exposed on, what vtable offset or dispid it is assigned to, what name it is exposed as (for Dispatch only) and how the parameters are marshaled.

The following example denotes these.

//pure
class Foo {
    [ExposedAs { VtblLoc  | DispatchLoc } <MethodDesc>]
    void Method1(int whatever)
    {
        DoesSomething;
    }
}

where:

   VtblLoc ::= (IID = iid, VtblOffset = offset)
   DispatchLoc ::= (IID = iid, DispId = dispid, DispType = type,
                    [DispName = name])
   MethodDesc ::= (see later)

Note that a given member can have multiple ExposedAs attributes within the same class (akin to exporting the same function under multiple names from a dynamic-link library (DLL).) In addition, local classes can inherit ExposedAs attributes from superclasses and interface definitions. If a method overrides a method in a superclass, the local method is exposed through all the interfaces listed in the ExposedAs attributes of the overridden method, as well as its own (the overridden method is never exposed by this mechanism; this would violate the notion of overriding).

If two ExposedAs attributes within a class's inheritance tree specify equal vtbllocs or dispatchlocs, it is considered an error.

ExposedAs attributes may appear on interfaces that are named in the "implements" clause of JCW or JCDW classes. However, these attributes have no effect on those classes.

The ProxiesTo Attribute

The ProxiesTo attribute describes, for a given method or field of a Java-callable wrapper (JCW), exactly which Component Object Model (COM) member function it maps to in the underlying COM object.

//JCW
class Foo {
    void Method1(int whatever)
    {
        [ProxiesTo { VtblLoc  | DispatchLoc} <MethodDesc>]
    }
}

Since JCWs cannot subclass each other, there are no overriding or inheritance rules to define for classes. However, Java interfaces can also specify ProxiesTo attributes (this is convenient for standard interfaces). In addition, interfaces that extend other interfaces can also override the ProxiesTo attributes of their parent interfaces (this is what happens when a COM interface definition inherits off another: it has its own IID).

In the case of multiple ProxiesTo attributes, the ambiguity is resolved by the form of the method call used. That is, in the following example:

interface IOleThing {
    [ProxiesTo (IID=IID_A,...]
    void foo();
}

interface IOleThingEx extends IOleThing {
    [ProxiesTo (IID=IID_B,...]
    void foo();
}

class CoOleThing implements IOleThingEx {
    [ProxiesTo (IID_IID_C,...]
    public void foo();
}

If the call to foo is made using invokeinterface on IOleThing, IID_A is used. If the call to foo is made using invokeinterface on IOleThingEx, IID_B is used. If the call is made using invokevirtual, CoOleThing is used.

The MapsTo Attribute

The MapsTo attribute describes how the fields of a Java-callable data wrapper (JCDW) map to offsets in the underlying data structure. These are valid only on the fields of a JCDW class. JCDW classes cannot subclass each other, so there are no inheritance/overriding rules.

//JCDW
class Data {
    [MapsTo ( [AutoOffset], Offset=offset, TypeDesc = typedesc)]
    int x;
}

The TypeDesc structure is described in the next section. If the "AutoOffset" is set, the Offset must be zero and the Virtual Machine will compute the actual offset for the hosting platform. This allows the structure definition to move freely between platforms.

Method and Type Descriptions

The TypeDesc structure defines the type of a single method parameter or return value. TypeDesc structures come in two flavors: one for vtable methods and one for dispatch methods. TypeDesc structures do not attempt to describe the type of the corresponding Java. These attributes are always associated with a method attribute that specifies method signatures.

TypeDesc structures have in/out subattributes to aid in efficient marshaling. Also, if TypeDesc describes a Java-callable wrapper (JCW), you must tag it with a subattribute that indicates the expected marshaling model of the external COM object. JCWs have a "Marshaling Mode," which is one of "NoMarshal" or "AutoMarshal." On a NoMarshal JCW, all calls made from Java to COM are made on the calling thread. On an AutoMarshal JCW, the Microsoft VM marshals all calls back to the thread on which the JCW was created.

Vtable Types

VtblTypes can be one of the following:
void | For return values only: indicates method has no return value
signed(1|2|4|8) | Signed 1, 2, 4, and 8-byte characters
unsigned(1|2|4|8) | Unsigned 1, 2, 4, and 8-byte characters
real(4|8) | Float and double
ptr | A 32-bit linear address
struct(size) | A by-value structure or array
interface(IID) | An IUnknown interface derivative
jstring | Strings
jarray | Arrays

Dispatch Types

Dispatch types are denoted by the VARTYPE enumerations (the subset that is allowable in a VARIANT). In addition, the DispatchType encodes the expected IID for VT_UNKNOWN and VT_DISPATCH.

Method Descriptions

A MethodDesc structure appears in various method-level attributes. This structure is the equivalent of the "Java method signature" for a COM/dispatch type. Either it is an array of VtblTypeDesc structures along with a VtblTypeDesc structure for the return type; or it is an array of DispatchTypeDesc structures along with a DispatchTypeDesc structure.


Attribute Reference

This section describes, at the bit level, the details of the attributes that must be present in any .class file that is to be used to invoke a Component Object Model (COM) object from Java or expose a Java object as a COM object.

The following attributes must be present.
Level | Name | Description
Class | COM_ClassType | Denotes the implementation language
Class | COM_GuidPool | Stores IIDs and class identifiers (CLSIDs)
Class | COM_MethodPool | Stores distilled typelib information
Method | COM_ExposedAs_Group | Exposes a Java method to COM
Method | COM_ProxiesTo | Exposes a COM method to Java
Field | COM_MapsTo | Exposes external data to Java

All unused bits in Flag fields must be zero.

Data Type Sizes and Alignment

Except where noted, BYTEs, WORDs, and DWORDs are unsigned and stored in the .class file in Big-Endian format.
BYTE | 8 bits
WORD | 16 bits
DWORD | 32 bits

There is no implicit padding between the fields of the structures, or any padding after the last field of any structure.

COM_ClassType

typedef struct {
    WORD        Flags;          // Must be zero. Reserved for future use.
    WORD        ClassType;      // CCTCT_JCW or CCTCT_JCDW
    WORD        CLSIDIndex;     // Optional index to CLSID (-1 for none)
} CCT_Attr;

This attribute, of attribute level Class, denotes the implementation language.

Parameter | Description
Flags | This field must be zero.
ClassType The only legal values are CCTCT_JCW and CCTCT_JCDW.

The actual type of a class is determined as follows:

  • If the class has a ClassType of type "CCTCT_JCW", the class type is "JCW".
  • If the class has a ClassType of type "CCTCT_JCDW", the class type is "JCDW".
  • All other situations are illegal.
CLSIDIndex If ClassType is not CCTCT_JCW, the contents of the field must be 0xffff.

If ClassType is CCTCT_JCW, and the CLSIDIndex is not 0xffff, it must indicate a valid index into the GuidPool. The globally unique identifier (GUID) corresponding to this index will be used as the CLSID of the Component Object Model (COM) object to load when you create an instance of this class by using the new operator.

Restrictions:

If the class type is CCTCT_JCW, the access flags for the class must be a subset of:
ACC_ABSTRACT
ACC_FINAL
ACC_PUBLIC

If the class type is CCTCT_JCDW, the access flags for the class must be a subset of:
ACC_FINAL (required)
ACC_PUBLIC

The class's superclass must be java.lang.Object.

If the class type is CCTCT_JCDW, the ACC_FINAL access flag must be present, and all fields defined by the class must have a COM_MapsTo.

COM_GuidPool

typedef struct {
    WORD        nGuids;         // # of guids in table
    // GUID     aGuid[nGuids];
} CGP_Attr;

Stores IIDs and class identifiers (CLSIDs).

Parameter | Description
nGuids | Indicates the number of GUIDs defined in this table.
aGuid Stores the actual GUID representations. A GUID is a 16-byte integer that is subdivided into fields as follows:
struct _GUID {
    DWORD Data1;
    WORD  Data2;
    WORD  Data3;
    BYTE  Data4[8];
}

Each field is stored in LITTLE-ENDIAN format in the .class file. This is an exception from the normal rule that all integers are stored in Big-Endian.

Remarks:

This attribute stores IIDs and CLSIDs that are referenced by index from the MethodPool. Valid indexes range from 0 inclusive to nGuids exclusive. The index 0xffff is reserved to indicate the "null" index. Hence, the GuidPool can contain a maximum of 65,535 globally unique identifiers (GUIDs).

Restrictions:

The class access flags must be a subset of:
ACC_ABSTRACT
ACC_FINAL
ACC_INTERFACE
ACC_PUBLIC

COM_MethodPool

typedef struct {
    WORD        nFuncs;         // # of functions in table
    // CFuncDesc aCFunc[nFuncs]
} CMP_Attr;

Stores distilled typelib information.

Parameter | Description
nFuncs | Indicates the number of CFuncDesc structures defined in this table.
aCFunc | Stores the actual CFuncDesc structures. The CFuncDesc structures are variable-sized structures.

Remarks:

This attribute stores the "method signatures" of the COM methods that are invoked by and implemented by the Java methods in the .class file. These signatures (CFuncDesc structures) are referenced by index by other attributes in the class. Valid indexes range from 0 inclusive to nFuncs exclusive. The index 0xffff is reserved to indicate the "null" index.

Restrictions:

The class access flags must be a subset of:
ACC_ABSTRACT
ACC_FINAL
ACC_INTERFACE
ACC_PUBLIC

Though the CFuncDesc structure allows you to specify an IID for individual CFuncDesc, the Virtual Machine requires that all CFuncDesc structures in a .class file reference the same IID in the CGuidPool.

This restriction does not apply to IIDs embedded in the CTypeDesc structures within the parameter arrays and return types of the CFuncDesc structures.

CTypeDesc

typedef struct {
    BYTE        Type;       //TD_* value
    BYTE        Flags;      //TDF_* flags
    union {
        WORD    IIDIndex;   // (for TD_INTF only)
        WORD    SizeIndex;  // (for TD_STRUCT only)
    };
} CTypeDesc;

This structure describes the type of a parameter or return value of a COM method.

Parameter Description
Type Must a member of the following TD_* enumeration. Supported types are grouped as follows:
Void | TD_VOID | No value. Only valid as a return type.
Integral | TD_I1 | Signed 8-bit
TD_I2 | Signed 16-bit
TD_I4 | Signed 32-bit
TD_I8 | Signed 64-bit
TD_U1 | Unsigned 8-bit
TD_U2 | Unsigned 16-bit
TD_U4 | Unsigned 32-bit
TD_U8 | Unsigned 64-bit
Floating point | TD_R4 | 32-bit float
TD_R8 | 64-bit float
Pointer | TD_PTR | Value is a pointer to some data structure.
Struct | TD_STRUCT | Value is a structure that is being passed by value.
Interface | TD_INTF | Value is an IUnknown derivative.
String | TD_JSTR | Value is a BSTR (OLE Automation)
Array | TD_JARR | Value points to the first element of a fixed-sized array.
Flags Flags are grouped into in/out flags and thread-model flags.

In/out:

If you use CTypeDesc to describe a parameter, the flags must specify one of TD_IN, TD_OUT, or TD_INOUT. For all types other than TD_PTR, TD_JSTR, and TD_JARR, the value of this subflag must be TD_IN.

If you use CTypeDesc to describe a return value or a MapsTo type, this subflag must be set to zero.

Thread Marshaling Mode:

This subflag is meaningful only for the TD_INTF type. For all others, it must be set to zero. This subflag indicates the desired thread marshaling mode of the interface pointer. If the Virtual Machine creates a JCW to represent this COM interface, it will do the appropriate marshaling. If this TypeDesc is being used to marshal to a Java class that is not a Java-callable wrapper (JCW), this subflag must be have the value 0.

The Virtual Machine supports two marshaling modes:
TDF_AUTOMARSHAL | COM methods invoked through JCW methods will be marshaled by the Virtual Machine to the thread on which the JCW was created. This allows non-threadsafe COM objects to be invoked from multiple Java threads without explicit marshaling.
TDF_NOMARSHAL | COM methods invoked through JCW methods will occur on the calling thread. This mode is most suitable for thread-safe COM objects. If the object is not thread-safe and this mode is used, the caller must restrict calls to the JCW to the thread on which the JCW was received.

The marshaling mode is a property of an instance of a JCW class, not of the JCW class itself.

In certain cases, the Virtual Machine may produce a Java object that assumes a different marshaling mode than this subflag indicates. This can happen if the interface pointer was previously marshaled to Java through another method whose parameter was flagged with the less-restrictive marshaling mode. It can also happen if the Virtual Machine itself created the incoming interface pointer (these interface pointers are all thread-safe).

union {
    WORD IIDIndex;
    WORD SizeIndex;
    }

For types other than TD_STRUCT, TD_JARR, and TD_INTF, this union must be set to zero.

If the type is TD_STRUC, this field must be set to an index into the constant pool: the constant pool item must be type CP_Integer and must indicate the size of the struct in bytes.

If the type is TD_JARR, this field must contain the expected number of elements in the array. TD_JARR cannot be used to pass variable-sized arrays.

If the type is TD_INTF, this field must be set to a valid index into the GuidPool. 0xffff (the "null" index) is not valid.

CVtblMethod

typedef struct {
    WORD        IIDIndex;
    WORD        VtblIndex;
    WORD        nArguments;
    WORD        wRetValParameter;   // -1 means none
    CTypeDesc   RetType;
    // Followed by array of CTypeDesc's for parameters
    CTypeDesc   aParamType[1];
} CVtblMethod;

Describes a vtable-based method in a COM interface. References to this structure can appear in both ExposedAs_Group attributes and ProxiesTo attributes.

Parameter | Description
IIDIndex | Valid index into the GuidPool that describes the IID of the COM interface that implements this method. 0xffff is not valid here.
VtblIndex | Denotes which vtable element the method occupies. The values 0, 1, and 2 are not legal here, because these correspond to the IUnknown interface methods that cannot be overridden. In addition, if the method pool contains CDispMethod structures using the same IID, values 3, 4, 5, and 6 must be avoided (because they correspond to IDispatch interface methods that the Microsoft VM supplies).
nArguments Number of parameters in the aParamType member. This count does not include the automatic this parameter passed to all COM methods.

If the wRetValParameter member is 0xffff, this count must match the number of parameters in the corresponding Java signature exactly. Otherwise, the count must be exactly one greater than the corresponding Java signature.

wRetValParameter If this member contains a value other than 0xffff, it must contain a value between 0 (inclusive) and nArguments (exclusive). This indicates that the parameter whose index equals wRetValParameter is actually a pointer through which the method returns its "true" return value. The aParamType member for this parameter must indicate the type of the buffer (the "pointer to" is implicit), and the RetType must be TD_VOID. In addition, the return type of the Java method sig must be compatible with the retval parameter.

If this COM method is invoked from Java, the Virtual Machine will supply a return value buffer of the appropriate type to the COM method. Upon a successful return from the COM method, (see CFuncDesc.Flags for what constitutes a successful return).

If you use Java to implement this COM method, the Virtual Machine will remove the retval pointer parameter from the list of arguments presented to the Java method. When the Java method returns, the Virtual Machine will convert the Java method's return value to COM representation, then write it to the retval buffer passed in from COM. The Virtual Machine will then create a COM return value that indicates success (see CFuncDesc.Flags for what constitutes a successful return).

RetType | Describes the return type. This type must be TD_VOID if wRetValParameter contains a value other than 0xffff, or if CFuncDesc.Flags has the CMDF_HRESULT_RETVAL bit set.
aParamType | Describes the parameter of each COM method.

Remarks:

For vtable methods, the Virtual Machine supports the following pairings between Java and COM types.
Java | COM | As return type | Restrictions
Any integral | Any integral | Yes
boolean | TD_I4 or TD_U4 | Yes
float | TD_R4 | Yes
double | TD_R8 | Yes
JCDW | TD_PTR | Yes | [1]
JCDW | TD_STRUCT | No
java.lang.String | TD_JSTR | Yes
object | TD_INTF | Yes | [2]
array of integrals | TD_JARR | No
array of floats | TD_JARR | No
array of booleans | TD_JARR | No
array of java.lang.String | TD_JARR | No
array of objects | TD_JARR | No | [2]
[1] You cannot use JCDWs that have embedded Java object types as return types.
[2] You must declare the Java object type as a Java interface, JCW class, or java.lang.Object.

These values intentionally match the VT_* enum values that are allowed in a VARIANT.
VTD_BOOL
VTD_BSTR
VTD_CY
VTD_DATE
VTD_DISPATCH
VTD_EMPTY
VTD_ERROR
VTD_I2
VTD_I4
VTD_NULL
VTD_R4
VTD_R8
VTD_UI1
VTD_UNKNOWN
VTD_VARIANT

Modifiers to VTD_ types. These do not have the same values as their VT_* equivalents because those values do not fit in a byte.
VTD_ARRAY
VTD_BYREF

CVarTypeDesc

typedef struct {
    BYTE        type;         //VTD_* value
    WORD        optname;      //(0 or constant-pool index to utf8)
    BYTE        Flags;        // TDF_* values
} CVarTypeDesc;

Describes the type of a single parameter or return value to an IDispatch interface method.

Parameter | Description
type | Contains a "compressed VARTYPE" value, defined by the VTD_* values.
optname | If nonzero, this field must be a constant-pool index to a CP_Utf8 that gives the parameter's name. This field is optional.
Flags One of these values:
CMDF_DISPATCH This flag indicates that the function is a Dispatch method.
CMDF_HRESULT_RETVAL This flag cannot be used with CMDF_DISPATCH. This flag indicates that the return type of the method is an HRESULT and that it is to be mapped to an exception on the Java side.

If this flag is used, the declared type of the RetVal must be TD_VOID.

When this flag is on, the Virtual Machine will treat all return values from COM objects as HRESULTs and will throw a Java exception (details TBD) if the HRESULT is not S_OK.

Conversely, the Virtual Machine will map all uncaught exceptions from Java code into a failing HRESULT, and will supply a return value of S_OK otherwise.

CDispMethod

typedef struct {
    WORD           IIDIndex;
    DWORD          Dispid;
    WORD           disptype;
    WORD           dispname;
    WORD           nArguments;
    CVarTypeDesc   RetType;
    // Followed by array of CVarTypeDesc's for parameters
    CVarTypeDesc   aParamType[1];
} CDispMethod;

Describes an OLE Automation method or property.

Parameter | Description
IIDIndex | Must be a valid index into the GUID pool and denotes the IID (typically IID_IDispatch, but can be any interface that derives from the IDispatch interface) through which this method is exposed.
disptype Describes the dispmember type. One of:
DISPATCH_METHOD
DISPATCH_PROPERTYGET
DISPATCH_PROPERTYPUT
DISPATCH_PROPERTYPUTREF
dispname | If this field is nonzero, it must be a valid index into the constant pool and the index must reference a CP_Utf8 that provides the name of the method. This field is required only if CDispMethod is referenced by an ExposedAs_Group attribute.
nArguments | Number of arguments.
RetType | Describes the type of the return value.
aParamType | Describes the type of the return value.

Remarks:

For Dispatch methods, the Virtual Machine supports the following pairings between Java and COM types. Because IDispatch::Invoke relies on VariantChangeType to convert a wide variety of types to another, the actual possibilities are larger than are represented here.
Java | Variant | As return type
Any integral | Any integral | Yes
Any float | Any float | Yes
One element array of:
short | VT_BYREF|VT_I2 | No
int | VT_BYREF|VT_I4 | No
float | VT_BYREF|VT_R4 | No
double | VT_BYREF|VT_R8 | No
byte | VT_BYREF|VT_UI1 | No
Object/interface | VT_BYREF|VT_UNKNOWN | No
Object/interface | VT_BYREF|VT_DISPATCH | No
java.lang.String | VT_BYREF|VT_BSTR | No
Object or interface | VT_UNKNOWN | Yes
Object or interface | VT_DISPATCH | Yes
java.lang.String | VT_BSTR | Yes

CFuncDesc

typedef struct {
    WORD        cbSize;         // size of entire CFuncDesc in bytes
    WORD        Flags;          // CMDF_* values
    union {
        CVtblMethod mvm;
        CDispMethod mdm;
    };
} CFuncDesc;

Describes a single method in the method pool.

Parameter | Description
cbSize | Size of CFuncDesc (including the cbSize member), in bytes.
Flags One of these values:
CMDF_DISPATCH Indicates that the function is a Dispatch method.
CMDF_HRESULT_RETVAL This flag cannot be used with CMDF_DISPATCH. This flag indicates that the return type of the method is an HRESULT and that it is to be mapped to an exception on the Java side.

If this flag is used, the declared type of the RetVal must be TD_VOID.

When this flag is on, the Virtual Machine will treat all return values from COM objects as HRESULTs and will throw a Java exception (details TBD) if the HRESULT is not S_OK.

Conversely, the Virtual Machine will map all uncaught exceptions from Java code into a failing HRESULT, and will supply a return value of S_OK otherwise.

COM_ExposedAs_Group

typedef struct _COM_ExposedAs_Group {
    WORD       Flags;           //none defined
    WORD       nExposedAs;
    // followed by array of CExposedAs's.
} CEAG_Attr;

This attribute, of attribute level Method, is a collection of ExposedAs structures, each of which causes the Java method to be exposed as a COM method.

Parameter | Description
Flags | Must be zero.
nExposedAs | Number of ExposedAs attributes that follow.
CEA ExposedAs[nExposedAs] | Array of exposed as.

Restrictions:

The access flags for the method must be a subset of:
ACC_ABSTRACT
ACC_FINAL
ACC_NATIVE
ACC_PRIVATE
ACC_PROTECTED
ACC_PUBLIC
ACC_SYNCHRONIZED

The class cannot have a ClassType attribute.

_COM_ExposedAs

typedef struct _COM_ExposedAs {
    WORD        Flags;
    WORD        MethodPoolIndex;
} CEA;

Each ExposedAs structure causes the Java method to be exposed as a COM method.

Parameter | Description
Flags | Must be zero.
MethodPoolIndex | Must be a valid index into the MethodPool.

COM_ProxiesTo

typedef struct _COM_ProxiesTo {
    WORD        CP_Flags;
    WORD        MethodPoolIndex;
} CPT_Attr;

Denotes that the Java method is implemented using COM.

Parameter | Description
CP_Flags | Must be zero.
MethodPoolIndex | Must be a valid index into the MethodPool.

Restrictions:

The access flags for the method must be a subset of:
ACC_ABSTRACT (on interfaces only)
ACC_FINAL
ACC_NATIVE (required)
ACC_PRIVATE
ACC_PROTECTED
ACC_PUBLIC

COM_MapsTo

typedef struct _COM_MapsTo {
    WORD        Flags;      // MTF_* values
    WORD        wPad;
    DWORD       dwOffset;
    CTypeDesc   typedesc;
} CMT_Attr;

Denotes that data for the field is stored in externally allocated memory.

Parameter | Description
Flags Can be this value:
MTF_AUTOOFFSET: If this flag is set, dwOffset must be zero and the Virtual Machine will compute the offset for the hosting platform. This allows the structure definition to move freely between platforms.

Every MapsTo in a .class file must use the same setting for MTF_AUTOOFFSET.

The auto-packing algorithm for the x86 platform is the ZP4 (DWORD-aligned) packing order.

wPad | Must be zero.
dwOffset | Offset in bytes within the external data structure. If MTF_AUTOOFFSET is on, this field has no meaning and must be set to zero.
typedesc | Describes the native type of the field.

Restrictions:

The access flags for the field must be a subset of:
ACC_FINAL
ACC_PRIVATE
ACC_PROTECTED
ACC_PUBLIC


Release Notes Win32 Virtual Machine

In this topic

Release Notes | Release Notes
Win32 Virtual Machine | Introduction

Microsoft Win32 Virtual Machine for Java

The Microsoft VM for Java (build 2613) ships with the retail version of the Internet Explorer 4.01. This release of the SDK for Java provides this VM in a stand-alone form, to be installed on the retail version of the Internet Explorer 3.02 (or later). It supports the following:

  • Enhanced JIT performance and reduced working set requirements

  • Enhanced interpreter loop performance

  • JDK 1.1 Support

    The Microsoft Virtual Machine for Java supports a number of JDK 1.1 defined enhancements, including Serialization, Reflection and Inner classes.

  • Java and COM

    The SafeArray class now has public methods to access array data.

    COM custom marshalling provides better control of how data is passed in and out of the virtual machine.

  • ActiveX and Java Beans Support

    Any Bean is exposed as an ActiveX control and any ActiveX control is exposed as a Bean.

    Auto-IDispatch now uses introspection to expose the necessary public classes and variables.

    ITypeInfo is provided on a class automatically and a type library can be persisted for a class.

    Event sourcing and sinking is supported.

  • Package Management Features

    The Java Language Package Manager is used by the VM to efficiently organize Java packages. For more information on this feature, please read the SDK documentation on Package Management.

    The current method of installing and using Java packages consists of storing all the classes in a zip file and then appending this file to the CLASSPATH registry key. When the VM needs a class, it searches each CLASSPATH entry. The CLASSPATH can become filled with references to packages that are old or unused, or different versions of the same package. It is also difficult to know which packages are needed and which are not. To address these and other concerns, the Java Language Package Manager is used to organize Java packages. The Java Package Manager offers:

    • Version Control. Package version numbers are tracked, allowing Java programs and installers to intelligently update the system.
    • Namespaces. Entire applets and applications can be installed in namespaces to avoid conflicting with identically named packages and classes from other vendors.
    • Improved Security. Instead of having to fully trust all installed classes, the package manager stores the allowed permissions of each package, as verified by Authenticode.
    • Signing. Through Authenticode signing, the package manager can ensure that only the vendor that installed a package can update it.
    • ActiveX Bean Support. ActiveX Beans in Java packages can be automatically registered by the package manager.
    • Ease of Use. Web pages can install packages without having to alter the CLASSPATH or require a reboot.

    When a Java package is installed in the Package Manager, the original archive file is removed and the classes are stored internally. Thus, developers need to use the clspack command (described in the tools section) to generate the ZIP files used by Java compilers. All of the standard Java packages shipped with this version of the VM are installed in the Package Manager, including the AFC classes.


Security Issues

Although Microsoft® J/Direct™ is a very powerful feature for standalone Java applications and trusted intranet Web applications, it is clearly too powerful to be used by normal Java applets on the Web. This section describes how J/Direct works with the security system of the Microsoft Win32 VM for Java to prevent untrusted code from abusing the power provided by J/Direct.

Trusted Versus Untrusted Classes

J/Direct divides all loaded Java classes into one of two categories:

  1. Fully trusted (indicating maximum permissions).
  2. Untrusted.

Only fully trusted classes are allowed to use J/Direct. A Java class is considered fully trusted if one of the following statements is true.

  1. The class is digitally signed indicating full trust. An example of such a class would be a signed applet. To find out more about signing cabinet files, see the Creating and Using Cabinet Files article and the Signcode article in the Tools section of the Microsoft SDK for Java.
  2. The class is installed on the target computer's CLASSPATH or installed by the package manager. A downloadable digitally signed library designed to be shared among multiple applets could meet this criterion.
  3. The class is running as a non-browser application using the jview or the wjview application.

An unsigned applet on the Web, on the other hand, constitutes untrusted Java code.

Security Checkpoints for J/Direct Method Calls

The Microsoft VM applies security checks to J/Direct methods at three different times:

  1. At link time.
  2. Upon first invocation.
  3. Upon every invocation.

An attempted J/Direct call takes place only if each of the three security checks passes or is explicitly disabled.

Security Checks at Link time

Linking is what occurs when one Java class invokes or accesses (using the Reflection API) a member of another class. At link time, the Microsoft VM checks to see whether the class being referenced is accessible and whether the arguments being passed are of the correct type and number. The class is considered accessible if it is in the same package or if it is declared public.

With the standard Java language, you are limited to a choice of two options for class accessibility: you can either declare a class public (so that anyone can link to it) or non-public (so that only classes in the same package can link to it). However, with Microsoft® Internet Explorer 4.0, there is now a third option. You can declare the class as "public for fully trusted callers only." You can declare any class with this type of accessibility, even if the class does not use J/Direct. To declare the class, place the following directive at the beginning of the class.

  /** @security(checkClassLinking=on) */

It is important to notice that this security check only prevents untrusted callers from directly calling the "protected" class. It does not prevent indirect calls. A third (fully trusted) class can forward a call from an untrusted caller to the "protected" class. However, there is a safeguard. The intermediate class must either be installed on the target computer's CLASSPATH, or it must be digitally signed for maximum trust and installed using the browser.

Security Checks upon First Invocation

The first invocation of a method is the first time the method is invoked from any caller. At this time, for each method marked with the native keyword, the Microsoft VM determines whether the method is a member of a fully trusted class. If it is not, a SecurityException is thrown that includes the message, "Only fully trusted classes can have native methods as members." Because this security check does not depend on the calling context, it only needs to be performed once. If it passes, the check does not take place on future invocations. There is no way to disable this security check.

Security Checks upon Every Invocation

This is the most stringent check available. On every call, the entire call stack is examined. If even one caller that is not fully-trusted is discovered on the call stack, a SecurityException is thrown. By default, all J/Direct methods perform this check. RNI methods do not perform this check because of backwards compatibility requirements. RNI was designed to allow easy porting from the original JDK 1.0 native interface, which did not offer this security check.

Although this security check offers maximum safety, Microsoft offers a way to disable it. The mechanism for disabling is provided because this stringent security check has two important side effects.

Possible Performance Degradation | This security check requires a scan of the entire call stack each time a J/Direct method is called. The performance degradation is most noticeable on trusted applets, which generally run with a security manager present. Applications, on the other hand, usually do not see a significant performance drop. This is due to the fact that J/Direct omits the call stack scan for applications that run without a security manager.
Inflexibility | This security mechanism forces the use of maximum permissions, even in cases where only one specific permission is required. For example, consider a trusted library that uses J/Direct to expose a single permission to untrusted applets in a safe way. It would be appropriate for this library to turn off the call time security check and perform its own security check for the specific permission.

The @security directive disables the per-invocation security check. Here is the syntax for this directive.

  /** @security(checkDllCalls=off) */

The @security directive applies to the entire class. Individual methods within a class cannot be tagged. The following example shows the placement of the @security directive.

  /** @security(checkDllCalls=off) */
  class FastJDirectMethods{
    /** @dll.import(...) */
    static native void func();
  }

Be aware of the fact that disabling this security check transfers responsibility for security from the Microsoft VM to you. Remember that even with this security check disabled, you will still have to digitally sign the class for maximum trust. If you decide to use this directive, be sure to take the following precautions:

  • All J/Direct methods should be declared private.
  • Any publicly accessible methods should never blindly pass caller arguments to J/Direct. You must take responsibility for ensuring that only valid arguments are passed to native code.
  • Your class should expose no more capability than is required, and it should guard all access to these capabilities with the appropriate security checks.

Important Note Regarding Trusted Applets: Calls from within an applet's init, start, stop, or destroy methods may trigger a SecurityExceptionEx even if the applet is trusted. To avoid this situation, you should assert permissions by executing the following code.

  import com.ms.security.*;
    ...
  PolicyEngine.assertPermission(PermissionID.SYSTEM);

Security Checkpoints for J/Direct Structures

J/Direct also imposes security restrictions on classes that are marked using the @dll.struct compiler directive. Because structures only become unsafe when they are instantiated, these security checks are more efficient than the checks used for J/Direct methods. The following two security checks are performed on @dll.struct classes.

Load time | Classes marked with @dll.struct will load only if the context indicates full trust.
Link time | Code that is not fully trusted cannot link to classes declared using @dll.struct. The Microsoft VM will throw a NoClassDefFoundError if such an attempt is made.

Security and the com.ms.win32 Classes

For maximum security, the J/Direct methods defined in the com.ms.win32 package do perform the call stack check on each invocation. If you are using these classes for a Java application (running under jview or wjview), the performance overhead will be negligible. If you are using com.ms.win32 classes from a trusted class and require maximum performance, you should copy the required J/Direct declarations into your own classes and disable the per-invocation security check. See the Security Checks upon Every Invocation section for more information on disabling the per-invocation security check.


Known Issues for the Microsoft Virtual Machine

In this topic

Release Notes | Release Notes
Known Issues | Introduction

Known Issues for the Microsoft VM for Java

  • This release of the Microsoft VM strictly enforces the following requirement: for a class to access methods of a class in another package, the second class must be declared public. Previous releases did not enforce this requirement. Hence some applets that worked before may display errors with the new virtual machine. It is advisable to make the packages conform to this Java requirement.

  • For ActiveX-Beans integration, certain functionality (such as persistence and OC96 windowless support) is not yet present. The ActiveX control hosting does not support all ambient properties. Code download will be provided in future releases.

  • VM uninstall option is provided in this release. Be aware of the following issues:

    If you want use the VM uninstall option, go to Control Panel, Add/Remove Software and uninstall the VM. If you uninstall the VM yet still plan to use Internet Explorer 4.0, this may cause potential problems with the downloading ability of the browser.

    Internet Explorer 4.0 uninstall includes an option to remove the Microsoft VM for Java. If you uninstall Internet Explorer 4.0 yet plan to use the VM and the SDK, the VM may not function properly. You must reinstall the stand-alone VM, by using the "Download" or the "Install and Download" option offered by SDKsetup.exe (the SDK download wizard). You can obtain the stand alone VM (msjavx86.exe) from the download directory you define or use the default directory C:\SDK-Java.20\Components. You can then double click on the msjavx86.exe to reinstall the VM at any time.

  • Using package-managed classes with existing tools:

    A tool called clspack creates all the ZIP files that are usually included in %WINDIR%\Java\Classes, and are now stored in the package manager. It is provided in the SDK\bin directory. You can use it by setting the path to the SDK\bin (set path=c:\sdk-java.20\bin;%path%) or copying it into %windir% directory.

    In addition, the value of the CLASSPATH registry setting is prepended with a reference to this generated classes.zip file (if one is not currently there). The compiler provided with the SDK (jvc.exe) checks this location by default for classes, so there is no need to set the CLASSPATH environment variable.

    For other compilers that do not check this location by default, set the CLASSPATH environment variable with:

    set CLASSPATH=%WINDIR%\Java\Classes\Classes.zip

    before running the compiler. It's a good idea to place this command in a batch file for easy use.

  • Raw Native Interface Enhancements:

    The Raw Native Interface (RNI) has been extended as a result of feedback and performance enhancements. The enhancements made to RNI are in four primary areas:

  • Additional APIs to enable reflection from native code
  • Changes to support future garbage collection performance enhancements
  • RNIGetCompatibleVersion requirement for RNI DLLs
  • RNI invocation APIs

For a more detailed description of the new and updated APIs, see the SDK documentation.

  • Any class calling the ActiveXControl class needs to be trusted. If an applet intends to host an ActiveX Control using the ActiveXControl class, it needs to be signed with the "fully trusted" permission. Any class calling the ActiveXControl class needs to be on the CLASSPATH or have the right permissions ascribed to it through package management. If the jactivex tool is used to host an ActiveX Control, the classes output by the tool end up using the ActiveXControl class. So any code using the classes output by jactivex needs to be trusted.
  • Some of the XML Data Source Object (DSO) functionality requires Internet Explorer version 4.0 or higher.
  • The following components of the XML specification have not yet been implemented:
    • Conditional sections in the DTD (INCLUDE & IGNORE keywords).
    • Some aspects of character encoding.
    For more information and an updated version of the Microsoft® XML parser please refer to the XML website.


About com.ms.vm

This package provides a class that implements a weak reference to an object. A weak reference tracks an object without preventing it from being garbage collected.

Classes

Class WeakReference
This class implements a weak reference to an object.

Hierarchy

Object
  |
  +--WeakReference


Class WeakReference

public class WeakReference
{
  // Constructors
  public WeakReference(Object referent);

  // Methods
  public void finalize();
  public Object getReferent();
  public void setReferent(Object object);
}

This class implements a weak reference to an object. A weak reference tracks an object without preventing it from being garbage-collected.

Constructors

WeakReference

public WeakReference(Object referent);

Constructs a weak reference to a specified object.

Parameter | Description
referent | The object to track.

Methods

finalize

public void finalize();

Finalizes the weak reference instance. The referent is no longer tracked.

Return Value:

No return value.

getReferent

public Object getReferent();

Retrieves the current object being tracked.

Return Value:

Returns the object being tracked; returns null if the object was collected.

setReferent

public void setReferent(Object object);

Sets the current object being tracked.

Return Value:

No return value.

Parameter | Description
object | The object being tracked, or null if the object was collected.


NOTICE SPECIFIC TO SOFTWARE AVAILABLE ON THIS WEBSITE Any software that is made available to download from this server ("Software") is the copyrighted work of Microsoft and/or its suppliers. Use of the Software is governed by the terms of the end user license agreement, if any, which accompanies or is included with the Software ("License Agreement"). An end user will be unable to install any Software that is accompanied by or includes a License Agreement, unless he or she first agrees to the License Agreement terms.

The Software is made available for downloading solely for use by end users according to the License Agreement. Any reproduction or redistribution of the Software not in accordance with the License Agreement is expressly prohibited by law, and may result in severe civil and criminal penalties. Violators will be prosecuted to the maximum extent possible.

WITHOUT LIMITING THE FOREGOING, COPYING OR REPRODUCTION OF THE SOFTWARE TO ANY OTHER SERVER OR LOCATION FOR FURTHER REPRODUCTION OR REDISTRIBUTION IS EXPRESSLY PROHIBITED.

THE SOFTWARE IS WARRANTED, IF AT ALL, ONLY ACCORDING TO THE TERMS OF THE LICENSE AGREEMENT. EXCEPT AS WARRANTED IN THE LICENSE AGREEMENT, MICROSOFT CORPORATION HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT.

RESTRICTED RIGHTS LEGEND. Any Software which is downloaded from this Server for or on behalf of the United States of America, its agencies and/or instrumentalities ("U.S. Government"), is provided with Restricted Rights. Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is Microsoft Corporation, One Microsoft Way, Redmond, WA 98052-6399.

NOTICE SPECIFIC TO DOCUMENTS AVAILABLE ON THIS WEBSITE

Permission to use Documents (such as white papers, press releases, datasheets and FAQs) from this server ("Server") is granted, provided that (1) the below copyright notice appears in all copies and that both the copyright notice and this permission notice appear, (2) use of such Documents from this Server is for informational and non-commercial or personal use only and will not be copied or posted on any network computer or broadcast in any media, and (3) no modifications of any Documents are made. Use for any other purpose is expressly prohibited by law, and may result in severe civil and criminal penalties. Violators will be prosecuted to the maximum extent possible.

Documents specified above do not include the design or layout of the microsoft.com website or any other Microsoft owned, operated, licensed or controlled site. Elements of Microsoft websites are protected by trade dress and other laws and may not be copied or imitated in whole or in part. No logo, graphic, sound or image from any Microsoft website may be copied or retransmitted unless expressly permitted by Microsoft.

MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE INFORMATION CONTAINED IN THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THIS SERVER FOR ANY PURPOSE. ALL SUCH DOCUMENTS AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES

AND CONDITIONS WITH REGARD TO THIS INFORMATION, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION AVAILABLE FROM THIS SERVER.

THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THIS SERVER COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED HEREIN AT ANY TIME.

NOTICES REGARDING SOFTWARE, DOCUMENTS AND SERVICES AVAILABLE ON THIS WEBSITE.

IN NO EVENT SHALL MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF SOFTWARE, DOCUMENTS, PROVISION OF OR FAILURE TO PROVIDE SERVICES, OR INFORMATION AVAILABLE FROM THIS SERVER.

LINKS TO THIRD PARTY SITES

THE LINKS IN THIS AREA WILL LET YOU LEAVE MICROSOFT'S SITE. THE LINKED SITES ARE NOT UNDER THE CONTROL OF MICROSOFT AND MICROSOFT IS NOT RESPONSIBLE FOR THE CONTENTS OF ANY LINKED SITE OR ANY LINK CONTAINED IN A LINKED SITE, OR ANY CHANGES OR UPDATES TO SUCH SITES. MICROSOFT IS PROVIDING THESE LINKS TO YOU ONLY AS A CONVENIENCE, AND THE INCLUSION OF ANY LINK DOES NOT IMPLY ENDORSEMENT BY MICROSOFT OF THE SITE.

COPYRIGHT NOTICE. Copyright © 1998 Microsoft and/or its suppliers, One Microsoft Way, Redmond, Washington 98052-6399 U.S.A. All rights reserved.

TRADEMARKS. Microsoft, Windows, Windows NT, MSN, The Microsoft Network and/or other Microsoft products referenced herein are either trademarks or registered trademarks of Microsoft. Other product and company names mentioned herein may be the trademarks of their respective owners.

The names of companies, products, people, characters and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product or event, unless otherwise noted.

Any rights not expressly granted herein are reserved.