KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdi > hcr > VirtualMachine


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jdi.hcr;
12
13
14 /**
15  * Hot code replacement extension to <code>com.sun.jdi.VirtualMachine</code>.
16  */
17 public interface VirtualMachine {
18     /** All the given type were reloaded */
19     public static final int RELOAD_SUCCESS = 0;
20     /** The VM is inconsistent after the reload operation */
21     public static final int RELOAD_FAILURE = 1;
22     /** The reload operation was ignored */
23     public static final int RELOAD_IGNORED = 2;
24
25     /**
26      * Determines if this implementation supports the early return
27      * of the top stack frame of a thread.
28      *
29      * @return <code>true</code> if the feature is supported,
30      * <code>false</code> otherwise.
31      */
32     public boolean canDoReturn();
33     
34     /**
35      * Determines if this implementation supports the retrieval
36      * of a class file version.
37      *
38      * @return <code>true</code> if the feature is supported,
39      * <code>false</code> otherwise.
40      */
41     public boolean canGetClassFileVersion();
42     
43     /**
44      * Determines if this implementation supports the reenter stepping.
45      *
46      * @return <code>true</code> if the feature is supported,
47      * <code>false</code> otherwise.
48      */
49     public boolean canReenterOnExit();
50     
51     /**
52      * Determines if this implementation supports the replacement
53      * of classes on the fly.
54      *
55      * @return <code>true</code> if the feature is supported,
56      * <code>false</code> otherwise.
57      */
58     public boolean canReloadClasses();
59     
60     /**
61      * Notifies the VM that the class file base that it is running from has changed.
62      * Classes are given by their names.
63      * <p>
64      * The class file base is the collection of class files available on the various VM's class paths
65      * consulted by the class loaders that are integral to the system. In JDK 1.2, these would
66      * include all files on the boot class path (used by the bootstrap class loader), the extension
67      * directory (used by the extension class loader), and the regular class path (used by the
68      * application class loader). The notion is important because only those classes that the VM
69      * knows to be in the class file base will be eligible for hot code replacement. Classes that
70      * are actually loaded by non-standard class loaders cannot be replaced on the fly (because the
71      * VM has no way of asking non-standard class loaders to reload them). Classes loaded from the
72      * class file base by cooperating class loaders are said to be HCR-eligible.
73      * <p>
74      * The VM is expected to:
75      * <ol>
76      * <li>Suspend all running threads.
77      * <li>For a given JNI signature, try to find the definition of the corresponding class.
78      * <ul>
79      * <li>If the class definition can be found then it replaces the previous definition
80      * for that class.
81      * <li>If a definition for the class is not found, then it is unloaded.
82      * <ul>
83      * <li>This operation returns only when the classes have been reloaded and/or deleted.
84      * <li>If the suspend policy of the class unload event is not to suspend the VM, then the
85      * VM resumes all the threads that it has suspended.
86      * <li>Finally for each class that has been reloaded, the VM is expected to
87      * <ul>
88      * <li>send a class unload event,
89      * <li>note the VM is already suspended if the suspend policy of class unload event
90      * said so,
91      * <li>when the frontend resumes the VM, send a class prepare event,
92      * <li>suspend the VM according to the suspend policy of the class prepare event
93      * request.
94      * </ul>
95      * <li>For each class that has been unloaded, the VM is expected to
96      * <ul>
97      * <li>send a class unload event,
98      * <li>suspend the VM if it was requested by the class unload event request.
99      * </ul>
100      * </ol>
101      * <p>
102      * Subsequent references to classes will work with the new class definition. Note the existing
103      * <code>com.sun.jdi.ReferenceType</code>, <code>com.sun.jdi.Method</code> and
104      * <code>com.sun.jdi.Field</code> still refer to the old class definition. So they
105      * should be discarded when the class unload event come in.
106      * <p>
107      * The VM does not discard stack frames automatically:
108      * <ul>
109      * <li>methods on the stack are not affected, and could therefore be referencing
110      * obsolete code
111      * <li>replacing a class does not affect anything on the stack
112      * <li>subsequent class and method lookups find the replacements
113      * </ul>
114      * <p>
115      * Installed breakpoints are not automatically carried over to the reloaded class:
116      * <ul>
117      * <li>breakpoints are resolved to particular locations in particular classes and methods
118      * <li>the VM must clear breakpoints to methods in classes that have been reloaded or
119      * unloaded (the debugger will reinstall them when it gets the class prepare event.)
120      * </ul>
121      * <p>
122      * A change notice encompasses changes to the content of a class file in the base, the addition
123      * of a class files to the base, and the removal of a class file from the base.
124      * <p>
125      * Change notices apply to all classes that are HCR-eligible (i.e., loaded by one of the
126      * cooperative system class loaders); other classes are never affected.
127      * <p>
128      * Returns whether the operation could be completed as specified above, whether it was
129      * ignored (for example if the VM doesn't support this kind of replacement), or whether the
130      * operation failed and the VM should be restarted.
131      *
132      */
133     public int classesHaveChanged(String JavaDoc[] arg1);
134 }
135
Popular Tags