001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdi.hcr;
011:
012: /**
013: * Hot code replacement extension to <code>com.sun.jdi.VirtualMachine</code>.
014: */
015: public interface VirtualMachine {
016: /** All the given type were reloaded */
017: public static final int RELOAD_SUCCESS = 0;
018: /** The VM is inconsistent after the reload operation */
019: public static final int RELOAD_FAILURE = 1;
020: /** The reload operation was ignored */
021: public static final int RELOAD_IGNORED = 2;
022:
023: /**
024: * Determines if this implementation supports the early return
025: * of the top stack frame of a thread.
026: *
027: * @return <code>true</code> if the feature is supported,
028: * <code>false</code> otherwise.
029: */
030: public boolean canDoReturn();
031:
032: /**
033: * Determines if this implementation supports the retrieval
034: * of a class file version.
035: *
036: * @return <code>true</code> if the feature is supported,
037: * <code>false</code> otherwise.
038: */
039: public boolean canGetClassFileVersion();
040:
041: /**
042: * Determines if this implementation supports the reenter stepping.
043: *
044: * @return <code>true</code> if the feature is supported,
045: * <code>false</code> otherwise.
046: */
047: public boolean canReenterOnExit();
048:
049: /**
050: * Determines if this implementation supports the replacement
051: * of classes on the fly.
052: *
053: * @return <code>true</code> if the feature is supported,
054: * <code>false</code> otherwise.
055: */
056: public boolean canReloadClasses();
057:
058: /**
059: * Notifies the VM that the class file base that it is running from has changed.
060: * Classes are given by their names.
061: * <p>
062: * The class file base is the collection of class files available on the various VM's class paths
063: * consulted by the class loaders that are integral to the system. In JDK 1.2, these would
064: * include all files on the boot class path (used by the bootstrap class loader), the extension
065: * directory (used by the extension class loader), and the regular class path (used by the
066: * application class loader). The notion is important because only those classes that the VM
067: * knows to be in the class file base will be eligible for hot code replacement. Classes that
068: * are actually loaded by non-standard class loaders cannot be replaced on the fly (because the
069: * VM has no way of asking non-standard class loaders to reload them). Classes loaded from the
070: * class file base by cooperating class loaders are said to be HCR-eligible.
071: * <p>
072: * The VM is expected to:
073: * <ol>
074: * <li>Suspend all running threads.
075: * <li>For a given JNI signature, try to find the definition of the corresponding class.
076: * <ul>
077: * <li>If the class definition can be found then it replaces the previous definition
078: * for that class.
079: * <li>If a definition for the class is not found, then it is unloaded.
080: * <ul>
081: * <li>This operation returns only when the classes have been reloaded and/or deleted.
082: * <li>If the suspend policy of the class unload event is not to suspend the VM, then the
083: * VM resumes all the threads that it has suspended.
084: * <li>Finally for each class that has been reloaded, the VM is expected to
085: * <ul>
086: * <li>send a class unload event,
087: * <li>note the VM is already suspended if the suspend policy of class unload event
088: * said so,
089: * <li>when the frontend resumes the VM, send a class prepare event,
090: * <li>suspend the VM according to the suspend policy of the class prepare event
091: * request.
092: * </ul>
093: * <li>For each class that has been unloaded, the VM is expected to
094: * <ul>
095: * <li>send a class unload event,
096: * <li>suspend the VM if it was requested by the class unload event request.
097: * </ul>
098: * </ol>
099: * <p>
100: * Subsequent references to classes will work with the new class definition. Note the existing
101: * <code>com.sun.jdi.ReferenceType</code>, <code>com.sun.jdi.Method</code> and
102: * <code>com.sun.jdi.Field</code> still refer to the old class definition. So they
103: * should be discarded when the class unload event come in.
104: * <p>
105: * The VM does not discard stack frames automatically:
106: * <ul>
107: * <li>methods on the stack are not affected, and could therefore be referencing
108: * obsolete code
109: * <li>replacing a class does not affect anything on the stack
110: * <li>subsequent class and method lookups find the replacements
111: * </ul>
112: * <p>
113: * Installed breakpoints are not automatically carried over to the reloaded class:
114: * <ul>
115: * <li>breakpoints are resolved to particular locations in particular classes and methods
116: * <li>the VM must clear breakpoints to methods in classes that have been reloaded or
117: * unloaded (the debugger will reinstall them when it gets the class prepare event.)
118: * </ul>
119: * <p>
120: * A change notice encompasses changes to the content of a class file in the base, the addition
121: * of a class files to the base, and the removal of a class file from the base.
122: * <p>
123: * Change notices apply to all classes that are HCR-eligible (i.e., loaded by one of the
124: * cooperative system class loaders); other classes are never affected.
125: * <p>
126: * Returns whether the operation could be completed as specified above, whether it was
127: * ignored (for example if the VM doesn't support this kind of replacement), or whether the
128: * operation failed and the VM should be restarted.
129: *
130: */
131: public int classesHaveChanged(String[] arg1);
132: }
|