Package org.eclipse.jdi.hcr

Interface VirtualMachine

public interface VirtualMachine

Hot code replacement extension to com.sun.jdi.VirtualMachine.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	RELOAD_FAILURE	The VM is inconsistent after the reload operation
static final int	RELOAD_IGNORED	The reload operation was ignored
static final int	RELOAD_SUCCESS	All the given type were reloaded

Method Summary

Modifier and Type	Method	Description
boolean	canDoReturn()	Determines if this implementation supports the early return of the top stack frame of a thread.
boolean	canGetClassFileVersion()	Determines if this implementation supports the retrieval of a class file version.
boolean	canReenterOnExit()	Determines if this implementation supports the reenter stepping.
boolean	canReloadClasses()	Determines if this implementation supports the replacement of classes on the fly.
int	classesHaveChanged(String[] arg1)	Notifies the VM that the class file base that it is running from has changed.

Field Details

RELOAD_SUCCESS

static final int RELOAD_SUCCESS

All the given type were reloaded

See Also:

• Constant Field Values

RELOAD_FAILURE

static final int RELOAD_FAILURE

The VM is inconsistent after the reload operation

See Also:

• Constant Field Values

RELOAD_IGNORED

static final int RELOAD_IGNORED

The reload operation was ignored

See Also:

• Constant Field Values

Method Details

canDoReturn

boolean canDoReturn()

Determines if this implementation supports the early return of the top stack frame of a thread.

Returns:

true if the feature is supported, false otherwise.

canGetClassFileVersion

boolean canGetClassFileVersion()

Determines if this implementation supports the retrieval of a class file version.

Returns:

true if the feature is supported, false otherwise.

canReenterOnExit

boolean canReenterOnExit()

Determines if this implementation supports the reenter stepping.

Returns:

true if the feature is supported, false otherwise.

canReloadClasses

boolean canReloadClasses()

Determines if this implementation supports the replacement of classes on the fly.

Returns:

true if the feature is supported, false otherwise.

classesHaveChanged

int classesHaveChanged(String[] arg1)

Notifies the VM that the class file base that it is running from has changed. Classes are given by their names.

The class file base is the collection of class files available on the various VM's class paths consulted by the class loaders that are integral to the system. In JDK 1.2, these would include all files on the boot class path (used by the bootstrap class loader), the extension directory (used by the extension class loader), and the regular class path (used by the application class loader). The notion is important because only those classes that the VM knows to be in the class file base will be eligible for hot code replacement. Classes that are actually loaded by non-standard class loaders cannot be replaced on the fly (because the VM has no way of asking non-standard class loaders to reload them). Classes loaded from the class file base by cooperating class loaders are said to be HCR-eligible.

The VM is expected to:

1. Suspend all running threads.
2. For a given JNI signature, try to find the definition of the corresponding class.
   • If the class definition can be found then it replaces the previous definition for that class.
   • If a definition for the class is not found, then it is unloaded.
     • This operation returns only when the classes have been reloaded and/or deleted.
     • If the suspend policy of the class unload event is not to suspend the VM, then the VM resumes all the threads that it has suspended.
     • Finally for each class that has been reloaded, the VM is expected to
       • send a class unload event,
       • note the VM is already suspended if the suspend policy of class unload event said so,
       • when the frontend resumes the VM, send a class prepare event,
       • suspend the VM according to the suspend policy of the class prepare event request.
     • For each class that has been unloaded, the VM is expected to
       • send a class unload event,
       • suspend the VM if it was requested by the class unload event request.

Subsequent references to classes will work with the new class definition. Note the existing com.sun.jdi.ReferenceType, com.sun.jdi.Method and com.sun.jdi.Field still refer to the old class definition. So they should be discarded when the class unload event come in.

The VM does not discard stack frames automatically:

• methods on the stack are not affected, and could therefore be referencing obsolete code
• replacing a class does not affect anything on the stack
• subsequent class and method lookups find the replacements

Installed breakpoints are not automatically carried over to the reloaded class:

• breakpoints are resolved to particular locations in particular classes and methods
• the VM must clear breakpoints to methods in classes that have been reloaded or unloaded (the debugger will reinstall them when it gets the class prepare event.)

A change notice encompasses changes to the content of a class file in the base, the addition of a class files to the base, and the removal of a class file from the base.

Change notices apply to all classes that are HCR-eligible (i.e., loaded by one of the cooperative system class loaders); other classes are never affected.

Returns whether the operation could be completed as specified above, whether it was ignored (for example if the VM doesn't support this kind of replacement), or whether the operation failed and the VM should be restarted.

Parameters:

arg1 - the names of the classes that have changed

Returns:

whether the operation could be completed as specified above, whether it was ignored (for example if the VM doesn't support this kind of replacement), or whether the operation failed and the VM should be restarted