jdimodelsrc.org.eclipse.jdi.hcr.VirtualMachine Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2023 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdi.hcr;
/**
* Hot code replacement extension to com.sun.jdi.VirtualMachine.
*/
public interface VirtualMachine {
/** All the given type were reloaded */
public static final int RELOAD_SUCCESS = 0;
/** The VM is inconsistent after the reload operation */
public static final int RELOAD_FAILURE = 1;
/** The reload operation was ignored */
public static final int RELOAD_IGNORED = 2;
/**
* Determines if this implementation supports the early return of the top
* stack frame of a thread.
*
* @return true if the feature is supported, false
* otherwise.
*/
public boolean canDoReturn();
/**
* Determines if this implementation supports the retrieval of a class file
* version.
*
* @return true if the feature is supported, false
* otherwise.
*/
public boolean canGetClassFileVersion();
/**
* Determines if this implementation supports the reenter stepping.
*
* @return true if the feature is supported, false
* otherwise.
*/
public boolean canReenterOnExit();
/**
* Determines if this implementation supports the replacement of classes on
* the fly.
*
* @return true if the feature is supported, false
* otherwise.
*/
public boolean canReloadClasses();
/**
* 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:
*
* - Suspend all running threads.
*
- 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.
*
* @param arg1
* the names of the classes that have changed
* @return 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
*/
public int classesHaveChanged(String[] arg1);
}