1 /*
  2  * Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
  3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  4  *
  5  * This code is free software; you can redistribute it and/or modify it
  6  * under the terms of the GNU General Public License version 2 only, as
  7  * published by the Free Software Foundation.  Oracle designates this
  8  * particular file as subject to the "Classpath" exception as provided
  9  * by Oracle in the LICENSE file that accompanied this code.
 10  *
 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package com.sun.jdi;
 27 
 28 import java.util.List;
 29 import java.util.Map;
 30 
 31 import com.sun.jdi.connect.AttachingConnector;
 32 import com.sun.jdi.connect.Connector;
 33 import com.sun.jdi.connect.LaunchingConnector;
 34 import com.sun.jdi.connect.spi.Connection;
 35 import com.sun.jdi.event.EventQueue;
 36 import com.sun.jdi.event.MethodExitEvent;
 37 import com.sun.jdi.event.VMDisconnectEvent;
 38 import com.sun.jdi.event.VMStartEvent;
 39 import com.sun.jdi.request.BreakpointRequest;
 40 import com.sun.jdi.request.ClassPrepareRequest;
 41 import com.sun.jdi.request.EventRequestManager;
 42 import com.sun.jdi.request.MonitorContendedEnterRequest;
 43 import com.sun.jdi.request.MonitorContendedEnteredRequest;
 44 import com.sun.jdi.request.MonitorWaitRequest;
 45 import com.sun.jdi.request.MonitorWaitedRequest;
 46 import com.sun.jdi.request.VMDeathRequest;
 47 
 48 /**
 49  * A virtual machine targeted for debugging.
 50  * More precisely, a {@link Mirror mirror} representing the
 51  * composite state of the target VM.
 52  * All other mirrors are associated with an instance of this
 53  * interface.  Access to all other mirrors is achieved
 54  * directly or indirectly through an instance of this
 55  * interface.
 56  * Access to global VM properties and control of VM execution
 57  * are supported directly by this interface.
 58  * <P>
 59  * Instances of this interface are created by instances of
 60  * {@link Connector}. For example,
 61  * an {@link AttachingConnector AttachingConnector}
 62  * attaches to a target VM and returns its virtual machine mirror.
 63  * A Connector will typically create a VirtualMachine by invoking
 64  * the VirtualMachineManager's {@link
 65  * VirtualMachineManager#createVirtualMachine(Connection)}
 66  * createVirtualMachine(Connection) method.
 67  * <p>
 68  * Note that a target VM launched by a launching connector is not
 69  * guaranteed to be stable until after the {@link VMStartEvent} has been
 70  * received.
 71  * <p>
 72  * Any method on <code>VirtualMachine</code> which
 73  * takes <code>VirtualMachine</code> as an parameter may throw
 74  * {@link VMDisconnectedException} if the target VM is
 75  * disconnected and the {@link VMDisconnectEvent} has been or is
 76  * available to be read from the {@link EventQueue}.
 77  * <p>
 78  * Any method on <code>VirtualMachine</code> which
 79  * takes <code>VirtualMachine</code> as an parameter may throw
 80  * {@link VMOutOfMemoryException} if the target VM has run out of memory.
 81  *
 82  * @author Robert Field
 83  * @author Gordon Hirsch
 84  * @author James McIlree
 85  * @since  1.3
 86  */
 87 public interface VirtualMachine extends Mirror {
 88 
 89     /**
 90      * Returns all modules. For each module in the target
 91      * VM a {@link ModuleReference} will be placed in the returned list.
 92      * <P>
 93      *
 94      * Not all target virtual machines support this operation.
 95      * Use {@link VirtualMachine#canGetModuleInfo()}
 96      * to determine if the operation is supported.
 97      *
 98      * @implSpec
 99      * The default implementation throws {@code UnsupportedOperationException}.
100      *
101      * @return a list of {@link ModuleReference} objects, each mirroring
102      * a module in the target VM.
103      *
104      * @throws java.lang.UnsupportedOperationException if
105      * the target virtual machine does not support this
106      * operation.
107      *
108      * @since 9
109      */
110     default List<ModuleReference> allModules() {
111         throw new java.lang.UnsupportedOperationException(
112             "The method allModules() must be implemented");
113     }
114 
115     /**
116      * Returns the loaded reference types that
117      * match a given name. The name must be fully qualified
118      * (for example, java.lang.String). The returned list
119      * will contain a {@link ReferenceType} for each class
120      * or interface found with the given name. The search
121      * is confined to loaded classes only; no attempt is made
122      * to load a class of the given name.
123      * <P>
124      * The returned list will include reference types
125      * loaded at least to the point of preparation and
126      * types (like array) for which preparation is
127      * not defined.
128      *
129      * @param className the class/interface name to search for
130      * @return a list of {@link ReferenceType} objects, each
131      * mirroring a type in the target VM with the given name.
132      */
133     List<ReferenceType> classesByName(String className);
134 
135     /**
136      * Returns all {@linkplain ReferenceType loaded types} in the target VM.
137      * <p>
138      * The returned list includes all reference types, including
139      * {@link Class#isHidden hidden classes or interfaces}, loaded
140      * at least to the point of preparation and types (like array)
141      * for which preparation is not defined.
142      *
143      * @return a list of {@link ReferenceType} objects, each mirroring
144      * a loaded type in the target VM.
145      * @see <a href="{@docRoot}/../specs/jvmti/jvmti.html#GetLoadedClasses">
146      * JVM TI GetLoadedClasses</a> regarding how class and interface creation can be triggered
147      */
148     List<ReferenceType> allClasses();
149 
150     /**
151      * All classes given are redefined according to the
152      * definitions supplied.  A method in a redefined class
153      * is called 'equivalent' (to the old version of the
154      * method) if
155      * <UL>
156      * <LI>their bytecodes are the same except for indicies into
157      *   the constant pool, and
158      * <LI>the referenced constants are equal.
159      * </UL>
160      * Otherwise, the new method is called 'non-equivalent'.
161      * If a redefined method has active stack frames, those active
162      * frames continue to run the bytecodes of the previous version of the
163      * method.  If the new version of such a method is non-equivalent,
164      * then a method from one of these active frames is called 'obsolete' and
165      * {@link Method#isObsolete Method.isObsolete()}
166      * will return true when called on one of these methods.
167      * If resetting such a frame is desired, use
168      * {@link ThreadReference#popFrames ThreadReference.popFrames(StackFrame)}
169      * to pop the old obsolete method execution from the stack.
170      * New invocations of redefined methods will always invoke the new versions.
171      * <p>
172      * This function does not cause any initialization except
173      * that which would occur under the customary JVM semantics.
174      * In other words, redefining a class does not cause
175      * its initializers to be run. The values of preexisting
176      * static variables will remain as they were prior to the
177      * call. However, completely uninitialized (new) static
178      * variables will be assigned their default value.
179      * <p>
180      * If a redefined class has instances then all those
181      * instances will have the fields defined by the redefined
182      * class at the completion of the call. Preexisting fields
183      * will retain their previous values. Any new fields will
184      * have their default values; no instance initializers or
185      * constructors are run.
186      * <p>
187      * Threads need not be suspended.
188      * <p>
189      * No events are generated by this function.
190      * <p>
191      * All breakpoints in the redefined classes are deleted.
192      * <p>
193      * Not all target virtual machines support this operation.
194      * Use {@link #canRedefineClasses() canRedefineClasses()}
195      * to determine if the operation is supported.
196      * Use {@link #canAddMethod() canAddMethod()}
197      * to determine if the redefinition can add methods.
198      * Use {@link #canUnrestrictedlyRedefineClasses() canUnrestrictedlyRedefineClasses()}
199      * to determine if the redefinition can change the schema,
200      * delete methods, change the class hierarchy, etc.
201      *
202      * @param classToBytes A map from {@link ReferenceType}
203      * to array of byte.
204      * The bytes represent the new class definition and
205      * are in Java Virtual Machine class file format.
206      *
207      * @throws java.lang.UnsupportedOperationException if
208      * the target virtual machine does not support this
209      * operation.
210      * <UL>
211      * <LI>If {@link #canRedefineClasses() canRedefineClasses()}
212      * is false any call of this method will throw this exception.
213      * <LI>If {@link #canAddMethod() canAddMethod()} is false
214      * attempting to add a method will throw this exception.
215      * <LI>If {@link #canUnrestrictedlyRedefineClasses()
216      *            canUnrestrictedlyRedefineClasses()}
217      * is false attempting any of the unsupported class file changes described
218      * in <a href="{@docRoot}/../specs/jvmti.html#RedefineClasses">
219      * JVM TI RedefineClasses</a> will throw this exception.
220      * </UL>
221      *
222      * @throws java.lang.NoClassDefFoundError if the bytes
223      * don't correspond to the reference type (the names
224      * don't match).
225      *
226      * @throws java.lang.VerifyError if a "verifier" detects
227      * that a class, though well formed, contains an internal
228      * inconsistency or security problem.
229      *
230      * @throws java.lang.ClassFormatError if the bytes
231      * do not represent a valid class.
232      *
233      * @throws java.lang.ClassCircularityError if a
234      * circularity has been detected while initializing a class.
235      *
236      * @throws java.lang.UnsupportedClassVersionError if the
237      * major and minor version numbers in bytes
238      * are not supported by the VM.
239      *
240      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
241      *
242      * @see Method#isObsolete
243      * @see ThreadReference#popFrames
244      * @see #canRedefineClasses
245      * @see #canAddMethod
246      * @see #canUnrestrictedlyRedefineClasses
247      *
248      * @since 1.4
249      */
250     void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes);
251 
252     /**
253      * Returns a list of the currently running threads. For each
254      * running thread in the target VM, a {@link ThreadReference}
255      * that mirrors it is placed in the list.
256      * The returned list contains threads created through
257      * java.lang.Thread, all native threads attached to
258      * the target VM through JNI, and system threads created
259      * by the target VM. Thread objects that have
260      * not yet been started
261      * (see {@link java.lang.Thread#start Thread.start()})
262      * and thread objects that have
263      * completed their execution are not included in the returned list.
264      *
265      * @return a list of {@link ThreadReference} objects, one for each
266      * running thread in the mirrored VM.
267      */
268     List<ThreadReference> allThreads();
269 
270     /**
271      * Suspends the execution of the application running in this
272      * virtual machine. All threads currently running will be suspended.
273      * <p>
274      * Unlike {@link java.lang.Thread#suspend Thread.suspend()},
275      * suspends of both the virtual machine and individual threads are
276      * counted. Before a thread will run again, it must be resumed
277      * (through {@link #resume} or {@link ThreadReference#resume})
278      * the same number of times it has been suspended.
279      *
280      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
281      */
282     void suspend();
283 
284     /**
285      * Continues the execution of the application running in this
286      * virtual machine. All threads are resumed as documented in
287      * {@link ThreadReference#resume}.
288      *
289      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
290      *
291      * @see #suspend
292      */
293     void resume();
294 
295     /**
296      * Returns each thread group which does not have a parent. For each
297      * top level thread group a {@link ThreadGroupReference} is placed in the
298      * returned list.
299      * <p>
300      * This command may be used as the first step in building a tree
301      * (or trees) of the existing thread groups.
302      *
303      * @return a list of {@link ThreadGroupReference} objects, one for each
304      * top level thread group.
305      */
306     List<ThreadGroupReference> topLevelThreadGroups();
307 
308     /**
309      * Returns the event queue for this virtual machine.
310      * A virtual machine has only one {@link EventQueue} object, this
311      * method will return the same instance each time it
312      * is invoked.
313      *
314      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
315      *
316      * @return the {@link EventQueue} for this virtual machine.
317      */
318     EventQueue eventQueue();
319 
320     /**
321      * Returns the event request manager for this virtual machine.
322      * The {@link EventRequestManager} controls user settable events
323      * such as breakpoints.
324      * A virtual machine has only one {@link EventRequestManager} object,
325      * this method will return the same instance each time it
326      * is invoked.
327      *
328      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
329      *
330      * @return the {@link EventRequestManager} for this virtual machine.
331      */
332     EventRequestManager eventRequestManager();
333 
334     /**
335      * Creates a {@link BooleanValue} for the given value. This value
336      * can be used for setting and comparing against a value retrieved
337      * from a variable or field in this virtual machine.
338      *
339      * @param value a boolean for which to create the value
340      * @return the {@link BooleanValue} for the given boolean.
341      */
342     BooleanValue mirrorOf(boolean value);
343 
344     /**
345      * Creates a {@link ByteValue} for the given value. This value
346      * can be used for setting and comparing against a value retrieved
347      * from a variable or field in this virtual machine.
348      *
349      * @param value a byte for which to create the value
350      * @return the {@link ByteValue} for the given byte.
351      */
352     ByteValue mirrorOf(byte value);
353 
354     /**
355      * Creates a {@link CharValue} for the given value. This value
356      * can be used for setting and comparing against a value retrieved
357      * from a variable or field in this virtual machine.
358      *
359      * @param value a char for which to create the value
360      * @return the {@link CharValue} for the given char.
361      */
362     CharValue mirrorOf(char value);
363 
364     /**
365      * Creates a {@link ShortValue} for the given value. This value
366      * can be used for setting and comparing against a value retrieved
367      * from a variable or field in this virtual machine.
368      *
369      * @param value a short for which to create the value
370      * @return the {@link ShortValue} for the given short.
371      */
372     ShortValue mirrorOf(short value);
373 
374     /**
375      * Creates an {@link IntegerValue} for the given value. This value
376      * can be used for setting and comparing against a value retrieved
377      * from a variable or field in this virtual machine.
378      *
379      * @param value an int for which to create the value
380      * @return the {@link IntegerValue} for the given int.
381      */
382     IntegerValue mirrorOf(int value);
383 
384     /**
385      * Creates a {@link LongValue} for the given value. This value
386      * can be used for setting and comparing against a value retrieved
387      * from a variable or field in this virtual machine.
388      *
389      * @param value a long for which to create the value
390      * @return the {@link LongValue} for the given long.
391      */
392     LongValue mirrorOf(long value);
393 
394     /**
395      * Creates a {@link FloatValue} for the given value. This value
396      * can be used for setting and comparing against a value retrieved
397      * from a variable or field in this virtual machine.
398      *
399      * @param value a float for which to create the value
400      * @return the {@link FloatValue} for the given float.
401      */
402     FloatValue mirrorOf(float value);
403 
404     /**
405      * Creates a {@link DoubleValue} for the given value. This value
406      * can be used for setting and comparing against a value retrieved
407      * from a variable or field in this virtual machine.
408      *
409      * @param value a double for which to create the value
410      * @return the {@link DoubleValue} for the given double.
411      */
412     DoubleValue mirrorOf(double value);
413 
414     /**
415      * Creates a string in this virtual machine.
416      * The created string can be used for setting and comparing against
417      * a string value retrieved from a variable or field in this
418      * virtual machine.
419      *
420      * @param value the string to be created
421      * @return a {@link StringReference} that mirrors the newly created
422      * string in the target VM.
423      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
424      * -see {@link VirtualMachine#canBeModified()}.
425      */
426     StringReference mirrorOf(String value);
427 
428 
429     /**
430      * Creates a {@link VoidValue}.  This value
431      * can be passed to {@link ThreadReference#forceEarlyReturn}
432      * when a void method is to be exited.
433      *
434      * @return the {@link VoidValue}.
435      */
436     VoidValue mirrorOfVoid();
437 
438     /**
439      * Returns the {@link java.lang.Process} object for this
440      * virtual machine if launched by a {@link LaunchingConnector}
441      *
442      * @return the {@link java.lang.Process} object for this virtual
443      * machine, or null if it was not launched by a {@link LaunchingConnector}.
444      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
445      * -see {@link VirtualMachine#canBeModified()}.
446      */
447     Process process();
448 
449     /**
450      * Invalidates this virtual machine mirror.
451      * The communication channel to the target VM is closed, and
452      * the target VM prepares to accept another subsequent connection
453      * from this debugger or another debugger, including the
454      * following tasks:
455      * <ul>
456      * <li>All event requests are cancelled.
457      * <li>All threads suspended by {@link #suspend} or by
458      * {@link ThreadReference#suspend} are resumed as many
459      * times as necessary for them to run.
460      * <li>Garbage collection is re-enabled in all cases where it was
461      * disabled through {@link ObjectReference#disableCollection}.
462      * </ul>
463      * Any current method invocations executing in the target VM
464      * are continued after the disconnection. Upon completion of any such
465      * method invocation, the invoking thread continues from the
466      * location where it was originally stopped.
467      * <p>
468      * Resources originating in
469      * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
470      * will become invalid.
471      */
472     void dispose();
473 
474     /**
475      * Causes the mirrored VM to terminate with the given error code.
476      * All resources associated with this VirtualMachine are freed.
477      * If the mirrored VM is remote, the communication channel
478      * to it will be closed. Resources originating in
479      * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
480      * will become invalid.
481      * <p>
482      * Threads running in the mirrored VM are abruptly terminated.
483      * A thread death exception is not thrown and
484      * finally blocks are not run.
485      *
486      * @param exitCode the exit code for the target VM.  On some platforms,
487      * the exit code might be truncated, for example, to the lower order 8 bits.
488      *
489      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
490      */
491     void exit(int exitCode);
492 
493     /**
494      * Determines if the target VM supports watchpoints
495      * for field modification.
496      *
497      * @return <code>true</code> if the feature is supported,
498      * <code>false</code> otherwise.
499      */
500     boolean canWatchFieldModification();
501 
502     /**
503      * Determines if the target VM supports watchpoints
504      * for field access.
505      *
506      * @return <code>true</code> if the feature is supported,
507      * <code>false</code> otherwise.
508      */
509     boolean canWatchFieldAccess();
510 
511     /**
512      * Determines if the target VM supports the retrieval
513      * of a method's bytecodes.
514      *
515      * @return <code>true</code> if the feature is supported,
516      * <code>false</code> otherwise.
517      */
518     boolean canGetBytecodes();
519 
520     /**
521      * Determines if the target VM supports the query
522      * of the synthetic attribute of a method or field.
523      *
524      * @return <code>true</code> if the feature is supported,
525      * <code>false</code> otherwise.
526      */
527     boolean canGetSyntheticAttribute();
528 
529     /**
530      * Determines if the target VM supports the retrieval
531      * of the monitors owned by a thread.
532      *
533      * @return <code>true</code> if the feature is supported,
534      * <code>false</code> otherwise.
535      */
536     boolean canGetOwnedMonitorInfo();
537 
538     /**
539      * Determines if the target VM supports the retrieval
540      * of the monitor for which a thread is currently waiting.
541      *
542      * @return <code>true</code> if the feature is supported,
543      * <code>false</code> otherwise.
544      */
545     boolean canGetCurrentContendedMonitor();
546 
547     /**
548      * Determines if the target VM supports the retrieval
549      * of the monitor information for an object.
550      *
551      * @return <code>true</code> if the feature is supported,
552      * <code>false</code> otherwise.
553      */
554     boolean canGetMonitorInfo();
555 
556     /**
557      * Determines if the target VM supports filtering
558      * events by specific instance object.  For example,
559      * see {@link BreakpointRequest#addInstanceFilter}.
560      *
561      * @return <code>true</code> if the feature is supported,
562      * <code>false</code> otherwise.
563      */
564     boolean canUseInstanceFilters();
565 
566     /**
567      * Determines if the target VM supports any level
568      * of class redefinition.
569      * @see #redefineClasses
570      *
571      * @return <code>true</code> if the feature is supported,
572      * <code>false</code> otherwise.
573      *
574      * @since 1.4
575      */
576     boolean canRedefineClasses();
577 
578     /**
579      * Determines if the target VM supports the addition
580      * of methods when performing class redefinition.
581      * @see #redefineClasses
582      * @deprecated A JVM TI based JDWP back-end will never set this capability to true.
583      *
584      * @return <code>true</code> if the feature is supported,
585      * <code>false</code> otherwise.
586      *
587      * @since 1.4
588      */
589     @Deprecated(since="15")
590     boolean canAddMethod();
591 
592     /**
593      * Determines if the target VM supports
594      * changes when performing class redefinition that are
595      * otherwise restricted by {@link #redefineClasses}.
596      * @see #redefineClasses
597      * @deprecated A JVM TI based JDWP back-end will never set this capability to true.
598      *
599      * @return <code>true</code> if the feature is supported,
600      * <code>false</code> otherwise.
601      *
602      * @since 1.4
603      */
604     @Deprecated(since="15")
605     boolean canUnrestrictedlyRedefineClasses();
606 
607     /**
608      * Determines if the target VM supports popping
609      * frames of a threads stack.
610      * @see ThreadReference#popFrames
611      *
612      * @return <code>true</code> if the feature is supported,
613      * <code>false</code> otherwise.
614      *
615      * @since 1.4
616      */
617     boolean canPopFrames();
618 
619     /**
620      * Determines if the target VM supports getting
621      * the source debug extension.
622      * @see ReferenceType#sourceDebugExtension
623      *
624      * @return <code>true</code> if the feature is supported,
625      * <code>false</code> otherwise.
626      *
627      * @since 1.4
628      */
629     boolean canGetSourceDebugExtension();
630 
631     /**
632      * Determines if the target VM supports the creation of
633      * {@link VMDeathRequest}s.
634      * @see EventRequestManager#createVMDeathRequest
635      *
636      * @return <code>true</code> if the feature is supported,
637      * <code>false</code> otherwise.
638      *
639      * @since 1.4
640      */
641     boolean canRequestVMDeathEvent();
642 
643     /**
644      * Determines if the target VM supports the inclusion of return values
645      * in
646      * {@link MethodExitEvent}s.
647      * @see EventRequestManager#createMethodExitRequest
648      *
649      * @return <code>true</code> if the feature is supported,
650      * <code>false</code> otherwise.
651      *
652      * @since 1.6
653      */
654     boolean canGetMethodReturnValues();
655 
656     /**
657      * Determines if the target VM supports the accessing of class instances,
658      * instance counts, and referring objects.
659      *
660      * @see #instanceCounts
661      * @see ReferenceType#instances(long)
662      * @see ObjectReference#referringObjects(long)
663      *
664      * @return <code>true</code> if the feature is supported,
665      * <code>false</code> otherwise.
666      *
667      * @since 1.6
668      */
669     boolean canGetInstanceInfo();
670 
671     /**
672      * Determines if the target VM supports the filtering of
673      * class prepare events by source name.
674      *
675      * see {@link ClassPrepareRequest#addSourceNameFilter}.
676      * @return <code>true</code> if the feature is supported,
677      * <code>false</code> otherwise.
678      *
679      * @since 1.6
680      */
681     boolean canUseSourceNameFilters();
682 
683     /**
684      * Determines if the target VM supports the forcing of a method to
685      * return early.
686      *
687      * @see ThreadReference#forceEarlyReturn(Value)
688      *
689      * @return <code>true</code> if the feature is supported,
690      * <code>false</code> otherwise.
691      *
692      * @since 1.6
693      */
694     boolean canForceEarlyReturn();
695 
696     /**
697      * Determines if the target VM is a read-only VM.  If a method which
698      * would modify the state of the VM is called on a read-only VM,
699      * then {@link VMCannotBeModifiedException} is thrown.
700      *
701      * @return <code>true</code> if the feature is supported,
702      * <code>false</code> otherwise.
703      *
704      * @since 1.5
705      */
706 
707     boolean canBeModified();
708 
709     /**
710      * Determines if the target VM supports the creation of
711      * {@link MonitorContendedEnterRequest}s.
712      * {@link MonitorContendedEnteredRequest}s.
713      * {@link MonitorWaitRequest}s.
714      * {@link MonitorWaitedRequest}s.
715      * @see EventRequestManager#createMonitorContendedEnterRequest
716      * @see EventRequestManager#createMonitorContendedEnteredRequest
717      * @see EventRequestManager#createMonitorWaitRequest
718      * @see EventRequestManager#createMonitorWaitedRequest
719      *
720      * @return <code>true</code> if the feature is supported,
721      * <code>false</code> otherwise.
722      *
723      * @since 1.6
724      */
725 
726     boolean canRequestMonitorEvents();
727 
728     /**
729      * Determines if the target VM supports getting which
730      * frame has acquired a monitor.
731      * @see ThreadReference#ownedMonitorsAndFrames
732      *
733      * @return <code>true</code> if the feature is supported,
734      * <code>false</code> otherwise.
735      *
736      * @since 1.6
737      */
738 
739      boolean canGetMonitorFrameInfo();
740 
741 
742     /**
743      * Determines if the target VM supports reading class file
744      * major and minor versions.
745      *
746      * @see ReferenceType#majorVersion()
747      * @see ReferenceType#minorVersion()
748      *
749      * @return <code>true</code> if the feature is supported,
750      * <code>false</code> otherwise.
751      *
752      * @since 1.6
753      */
754     boolean canGetClassFileVersion();
755 
756     /**
757      * Determines if the target VM supports getting constant pool
758      * information of a class.
759      *
760      * @see ReferenceType#constantPoolCount()
761      * @see ReferenceType#constantPool()
762      *
763      * @return <code>true</code> if the feature is supported,
764      * <code>false</code> otherwise.
765      *
766      * @since 1.6
767      */
768     boolean canGetConstantPool();
769 
770     /**
771      * Determines if the target VM supports getting information about modules.
772      *
773      * @return {@code true} if the feature is supported, {@code false} otherwise
774      *
775      * @implSpec
776      * The default implementation returns {@code false}.
777      *
778      * @see VirtualMachine#allModules()
779      * @see ReferenceType#module()
780      * @see ModuleReference
781      *
782      * @since 9
783      */
784     default boolean canGetModuleInfo() {
785         return false;
786     }
787 
788     /**
789      * Set this VM's default stratum (see {@link Location} for a
790      * discussion of strata).  Overrides the per-class default set
791      * in the class file.
792      * <P>
793      * Affects location queries (such as,
794      * {@link Location#sourceName()})
795      * and the line boundaries used in
796      * single stepping.
797      *
798      * @param stratum the stratum to set as VM default,
799      * or null to use per-class defaults.
800      *
801      * @throws java.lang.UnsupportedOperationException if the
802      * target virtual machine does not support this operation.
803      *
804      * @since 1.4
805      */
806     void setDefaultStratum(String stratum);
807 
808     /**
809      * Return this VM's default stratum.
810      *
811      * @see #setDefaultStratum(String)
812      * @see ReferenceType#defaultStratum()
813      * @return <code>null</code> (meaning that the per-class
814      * default - {@link ReferenceType#defaultStratum()} -
815      * should be used) unless the default stratum has been
816      * set with
817      * {@link #setDefaultStratum(String)}.
818      *
819      * @since 1.4
820      */
821     String getDefaultStratum();
822 
823     /**
824      * Returns the number of instances of each ReferenceType in the 'refTypes'
825      * list.
826      * Only instances that are reachable for the purposes of garbage collection
827      * are counted.
828      * <p>
829      * Not all target virtual machines support this operation.
830      * Use {@link VirtualMachine#canGetInstanceInfo()}
831      * to determine if the operation is supported.
832      *
833      * @see ReferenceType#instances(long)
834      * @see ObjectReference#referringObjects(long)
835      * @param refTypes the list of {@link ReferenceType} objects for which counts
836      *        are to be obtained.
837      *
838      * @return an array of <code>long</code> containing one element for each
839      *         element in the 'refTypes' list.  Element i of the array contains
840      *         the number of instances in the target VM of the ReferenceType at
841      *         position i in the 'refTypes' list.
842      *         If the 'refTypes' list is empty, a zero-length array is returned.
843      *         If a ReferenceType in refTypes has been garbage collected, zero
844      *         is returned for its instance count.
845      * @throws java.lang.UnsupportedOperationException if
846      * the target virtual machine does not support this
847      * operation - see
848      * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
849      * @throws NullPointerException if the 'refTypes' list is null.
850      * @since 1.6
851      */
852     long[] instanceCounts(List<? extends ReferenceType> refTypes);
853 
854     /**
855      * Returns text information on the target VM and the
856      * debugger support that mirrors it. No specific format
857      * for this information is guaranteed.
858      * Typically, this string contains version information for the
859      * target VM and debugger interfaces.
860      * More precise information
861      * on VM and JDI versions is available through
862      * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion},
863      * and {@link VirtualMachineManager#minorInterfaceVersion}
864      *
865      * @return the description.
866      */
867     String description();
868 
869     /**
870      * Returns the version of the Java Runtime Environment in the target
871      * VM as reported by the property <code>java.version</code>.
872      * For obtaining the JDI interface version, use
873      * {@link VirtualMachineManager#majorInterfaceVersion}
874      * and {@link VirtualMachineManager#minorInterfaceVersion}
875      *
876      * @return the target VM version.
877      */
878     String version();
879 
880     /**
881      * Returns the name of the target VM as reported by the
882      * property <code>java.vm.name</code>.
883      *
884      * @return the target VM name.
885      */
886     String name();
887 
888     /** All tracing is disabled. */
889     int TRACE_NONE        = 0x00000000;
890     /** Tracing enabled for JDWP packets sent to target VM. */
891     int TRACE_SENDS       = 0x00000001;
892     /** Tracing enabled for JDWP packets received from target VM. */
893     int TRACE_RECEIVES    = 0x00000002;
894     /** Tracing enabled for internal event handling. */
895     int TRACE_EVENTS      = 0x00000004;
896     /** Tracing enabled for internal managment of reference types. */
897     int TRACE_REFTYPES    = 0x00000008;
898     /** Tracing enabled for internal management of object references. */
899     int TRACE_OBJREFS      = 0x00000010;
900     /** All tracing is enabled. */
901     int TRACE_ALL         = 0x00ffffff;
902 
903     /**
904      * Traces the activities performed by the com.sun.jdi implementation.
905      * All trace information is output to System.err. The given trace
906      * flags are used to limit the output to only the information
907      * desired. The given flags are in effect and the corresponding
908      * trace will continue until the next call to
909      * this method.
910      * <p>
911      * Output is implementation dependent and trace mode may be ignored.
912      *
913      * @param traceFlags identifies which kinds of tracing to enable.
914      */
915     void setDebugTraceMode(int traceFlags);
916 }