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