| package org.eclipse.jdi.hcr; |
| |
| /* |
| * (c) Copyright IBM Corp. 2000, 2001. |
| * All Rights Reserved. |
| */ |
| |
| /** |
| * Hot code replacement extension to <code>com.sun.jdi.VirtualMachine</code>. |
| */ |
| 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 <code>true</code> if the feature is supported, |
| * <code>false</code> otherwise. |
| */ |
| public boolean canDoReturn(); |
| |
| /** |
| * Determines if this implementation supports the retrieval |
| * of a class file version. |
| * |
| * @return <code>true</code> if the feature is supported, |
| * <code>false</code> otherwise. |
| */ |
| public boolean canGetClassFileVersion(); |
| |
| /** |
| * Determines if this implementation supports the reenter stepping. |
| * |
| * @return <code>true</code> if the feature is supported, |
| * <code>false</code> otherwise. |
| */ |
| public boolean canReenterOnExit(); |
| |
| /** |
| * Determines if this implementation supports the replacement |
| * of classes on the fly. |
| * |
| * @return <code>true</code> if the feature is supported, |
| * <code>false</code> 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. |
| * <p> |
| * 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. |
| * <p> |
| * The VM is expected to: |
| * <ol> |
| * <li>Suspend all running threads. |
| * <li>For a given JNI signature, try to find the definition of the corresponding class. |
| * <ul> |
| * <li>If the class definition can be found then it replaces the previous definition |
| * for that class. |
| * <li>If a definition for the class is not found, then it is unloaded. |
| * <ul> |
| * <li>This operation returns only when the classes have been reloaded and/or deleted. |
| * <li>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. |
| * <li>Finally for each class that has been reloaded, the VM is expected to |
| * <ul> |
| * <li>send a class unload event, |
| * <li>note the VM is already suspended if the suspend policy of class unload event |
| * said so, |
| * <li>when the frontend resumes the VM, send a class prepare event, |
| * <li>suspend the VM according to the suspend policy of the class prepare event |
| * request. |
| * </ul> |
| * <li>For each class that has been unloaded, the VM is expected to |
| * <ul> |
| * <li>send a class unload event, |
| * <li>suspend the VM if it was requested by the class unload event request. |
| * </ul> |
| * </ol> |
| * <p> |
| * Subsequent references to classes will work with the new class definition. Note the existing |
| * <code>com.sun.jdi.ReferenceType</code>, <code>com.sun.jdi.Method</code> and |
| * <code>com.sun.jdi.Field</code> still refer to the old class definition. So they |
| * should be discarded when the class unload event come in. |
| * <p> |
| * The VM does not discard stack frames automatically: |
| * <ul> |
| * <li>methods on the stack are not affected, and could therefore be referencing |
| * obsolete code |
| * <li>replacing a class does not affect anything on the stack |
| * <li>subsequent class and method lookups find the replacements |
| * </ul> |
| * <p> |
| * Installed breakpoints are not automatically carried over to the reloaded class: |
| * <ul> |
| * <li>breakpoints are resolved to particular locations in particular classes and methods |
| * <li>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.) |
| * </ul> |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * |
| */ |
| public int classesHaveChanged(String[] arg1); |
| } |