1 /*
  2  * Copyright (c) 1998, 2021, 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 live
254      * <a href="{@docRoot}/java.base/java/lang/Thread.html#platform-threads">platform
255      * threads</a> in the target VM. The returned list contains a {@link ThreadReference}
256      * mirror for each live platform thread that is attached to the VM. The list does
257      * not contain elements for virtual threads.
258      * <p>
259      * The returned list contains the platform threads created with the {@link Thread}
260      * API, and all native threads attached to the target VM through JNI.
261      * Thread objects that have not yet been started
262      * (see {@link java.lang.Thread#start Thread.start()})
263      * and thread objects that have
264      * completed their execution are not included in the returned list.
265      *
266      * @return a list of {@link ThreadReference} objects, one for each
267      * live platform thread in the mirrored VM.
268      */
269     List<ThreadReference> allThreads();
270 
271     /**
272      * Suspends the execution of the application running in this
273      * virtual machine. All threads currently running will be suspended.
274      * <p>
275      * Unlike {@link java.lang.Thread#suspend Thread.suspend()},
276      * suspends of both the virtual machine and individual threads are
277      * counted. Before a thread will run again, it must be resumed
278      * (through {@link #resume} or {@link ThreadReference#resume})
279      * the same number of times it has been suspended.
280      *
281      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
282      */
283     void suspend();
284 
285     /**
286      * Continues the execution of the application running in this
287      * virtual machine. All threads are resumed as documented in
288      * {@link ThreadReference#resume}.
289      *
290      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
291      *
292      * @see #suspend
293      */
294     void resume();
295 
296     /**
297      * Returns each thread group which does not have a parent. For each
298      * top level thread group a {@link ThreadGroupReference} is placed in the
299      * returned list.
300      * <p>
301      * This command may be used as the first step in building a tree
302      * (or trees) of the existing thread groups.
303      *
304      * @return a list of {@link ThreadGroupReference} objects, one for each
305      * top level thread group.
306      */
307     List<ThreadGroupReference> topLevelThreadGroups();
308 
309     /**
310      * Returns the event queue for this virtual machine.
311      * A virtual machine has only one {@link EventQueue} object, this
312      * method will return the same instance each time it
313      * is invoked.
314      *
315      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
316      *
317      * @return the {@link EventQueue} for this virtual machine.
318      */
319     EventQueue eventQueue();
320 
321     /**
322      * Returns the event request manager for this virtual machine.
323      * The {@link EventRequestManager} controls user settable events
324      * such as breakpoints.
325      * A virtual machine has only one {@link EventRequestManager} object,
326      * this method will return the same instance each time it
327      * is invoked.
328      *
329      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
330      *
331      * @return the {@link EventRequestManager} for this virtual machine.
332      */
333     EventRequestManager eventRequestManager();
334 
335     /**
336      * Creates a {@link BooleanValue} for the given value. This value
337      * can be used for setting and comparing against a value retrieved
338      * from a variable or field in this virtual machine.
339      *
340      * @param value a boolean for which to create the value
341      * @return the {@link BooleanValue} for the given boolean.
342      */
343     BooleanValue mirrorOf(boolean value);
344 
345     /**
346      * Creates a {@link ByteValue} for the given value. This value
347      * can be used for setting and comparing against a value retrieved
348      * from a variable or field in this virtual machine.
349      *
350      * @param value a byte for which to create the value
351      * @return the {@link ByteValue} for the given byte.
352      */
353     ByteValue mirrorOf(byte value);
354 
355     /**
356      * Creates a {@link CharValue} for the given value. This value
357      * can be used for setting and comparing against a value retrieved
358      * from a variable or field in this virtual machine.
359      *
360      * @param value a char for which to create the value
361      * @return the {@link CharValue} for the given char.
362      */
363     CharValue mirrorOf(char value);
364 
365     /**
366      * Creates a {@link ShortValue} for the given value. This value
367      * can be used for setting and comparing against a value retrieved
368      * from a variable or field in this virtual machine.
369      *
370      * @param value a short for which to create the value
371      * @return the {@link ShortValue} for the given short.
372      */
373     ShortValue mirrorOf(short value);
374 
375     /**
376      * Creates an {@link IntegerValue} for the given value. This value
377      * can be used for setting and comparing against a value retrieved
378      * from a variable or field in this virtual machine.
379      *
380      * @param value an int for which to create the value
381      * @return the {@link IntegerValue} for the given int.
382      */
383     IntegerValue mirrorOf(int value);
384 
385     /**
386      * Creates a {@link LongValue} for the given value. This value
387      * can be used for setting and comparing against a value retrieved
388      * from a variable or field in this virtual machine.
389      *
390      * @param value a long for which to create the value
391      * @return the {@link LongValue} for the given long.
392      */
393     LongValue mirrorOf(long value);
394 
395     /**
396      * Creates a {@link FloatValue} for the given value. This value
397      * can be used for setting and comparing against a value retrieved
398      * from a variable or field in this virtual machine.
399      *
400      * @param value a float for which to create the value
401      * @return the {@link FloatValue} for the given float.
402      */
403     FloatValue mirrorOf(float value);
404 
405     /**
406      * Creates a {@link DoubleValue} for the given value. This value
407      * can be used for setting and comparing against a value retrieved
408      * from a variable or field in this virtual machine.
409      *
410      * @param value a double for which to create the value
411      * @return the {@link DoubleValue} for the given double.
412      */
413     DoubleValue mirrorOf(double value);
414 
415     /**
416      * Creates a string in this virtual machine.
417      * The created string can be used for setting and comparing against
418      * a string value retrieved from a variable or field in this
419      * virtual machine.
420      *
421      * @param value the string to be created
422      * @return a {@link StringReference} that mirrors the newly created
423      * string in the target VM.
424      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
425      * -see {@link VirtualMachine#canBeModified()}.
426      */
427     StringReference mirrorOf(String value);
428 
429 
430     /**
431      * Creates a {@link VoidValue}.  This value
432      * can be passed to {@link ThreadReference#forceEarlyReturn}
433      * when a void method is to be exited.
434      *
435      * @return the {@link VoidValue}.
436      */
437     VoidValue mirrorOfVoid();
438 
439     /**
440      * Returns the {@link java.lang.Process} object for this
441      * virtual machine if launched by a {@link LaunchingConnector}
442      *
443      * @return the {@link java.lang.Process} object for this virtual
444      * machine, or null if it was not launched by a {@link LaunchingConnector}.
445      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
446      * -see {@link VirtualMachine#canBeModified()}.
447      */
448     Process process();
449 
450     /**
451      * Invalidates this virtual machine mirror.
452      * The communication channel to the target VM is closed, and
453      * the target VM prepares to accept another subsequent connection
454      * from this debugger or another debugger, including the
455      * following tasks:
456      * <ul>
457      * <li>All event requests are cancelled.
458      * <li>All threads suspended by {@link #suspend} or by
459      * {@link ThreadReference#suspend} are resumed as many
460      * times as necessary for them to run.
461      * <li>Garbage collection is re-enabled in all cases where it was
462      * disabled through {@link ObjectReference#disableCollection}.
463      * </ul>
464      * Any current method invocations executing in the target VM
465      * are continued after the disconnection. Upon completion of any such
466      * method invocation, the invoking thread continues from the
467      * location where it was originally stopped.
468      * <p>
469      * Resources originating in
470      * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
471      * will become invalid.
472      */
473     void dispose();
474 
475     /**
476      * Causes the mirrored VM to terminate with the given error code.
477      * All resources associated with this VirtualMachine are freed.
478      * If the mirrored VM is remote, the communication channel
479      * to it will be closed. Resources originating in
480      * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
481      * will become invalid.
482      * <p>
483      * Threads running in the mirrored VM are abruptly terminated.
484      * A thread death exception is not thrown and
485      * finally blocks are not run.
486      *
487      * @param exitCode the exit code for the target VM.  On some platforms,
488      * the exit code might be truncated, for example, to the lower order 8 bits.
489      *
490      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
491      */
492     void exit(int exitCode);
493 
494     /**
495      * Determines if the target VM supports watchpoints
496      * for field modification.
497      *
498      * @return <code>true</code> if the feature is supported,
499      * <code>false</code> otherwise.
500      */
501     boolean canWatchFieldModification();
502 
503     /**
504      * Determines if the target VM supports watchpoints
505      * for field access.
506      *
507      * @return <code>true</code> if the feature is supported,
508      * <code>false</code> otherwise.
509      */
510     boolean canWatchFieldAccess();
511 
512     /**
513      * Determines if the target VM supports the retrieval
514      * of a method's bytecodes.
515      *
516      * @return <code>true</code> if the feature is supported,
517      * <code>false</code> otherwise.
518      */
519     boolean canGetBytecodes();
520 
521     /**
522      * Determines if the target VM supports the query
523      * of the synthetic attribute of a method or field.
524      *
525      * @return <code>true</code> if the feature is supported,
526      * <code>false</code> otherwise.
527      */
528     boolean canGetSyntheticAttribute();
529 
530     /**
531      * Determines if the target VM supports the retrieval
532      * of the monitors owned by a thread.
533      *
534      * @return <code>true</code> if the feature is supported,
535      * <code>false</code> otherwise.
536      */
537     boolean canGetOwnedMonitorInfo();
538 
539     /**
540      * Determines if the target VM supports the retrieval
541      * of the monitor for which a thread is currently waiting.
542      *
543      * @return <code>true</code> if the feature is supported,
544      * <code>false</code> otherwise.
545      */
546     boolean canGetCurrentContendedMonitor();
547 
548     /**
549      * Determines if the target VM supports the retrieval
550      * of the monitor information for an object.
551      *
552      * @return <code>true</code> if the feature is supported,
553      * <code>false</code> otherwise.
554      */
555     boolean canGetMonitorInfo();
556 
557     /**
558      * Determines if the target VM supports filtering
559      * events by specific instance object.  For example,
560      * see {@link BreakpointRequest#addInstanceFilter}.
561      *
562      * @return <code>true</code> if the feature is supported,
563      * <code>false</code> otherwise.
564      */
565     boolean canUseInstanceFilters();
566 
567     /**
568      * Determines if the target VM supports any level
569      * of class redefinition.
570      * @see #redefineClasses
571      *
572      * @return <code>true</code> if the feature is supported,
573      * <code>false</code> otherwise.
574      *
575      * @since 1.4
576      */
577     boolean canRedefineClasses();
578 
579     /**
580      * Determines if the target VM supports the addition
581      * of methods when performing class redefinition.
582      * @see #redefineClasses
583      * @deprecated A JVM TI based JDWP back-end will never set this capability to true.
584      *
585      * @return <code>true</code> if the feature is supported,
586      * <code>false</code> otherwise.
587      *
588      * @since 1.4
589      */
590     @Deprecated(since="15")
591     boolean canAddMethod();
592 
593     /**
594      * Determines if the target VM supports
595      * changes when performing class redefinition that are
596      * otherwise restricted by {@link #redefineClasses}.
597      * @see #redefineClasses
598      * @deprecated A JVM TI based JDWP back-end will never set this capability to true.
599      *
600      * @return <code>true</code> if the feature is supported,
601      * <code>false</code> otherwise.
602      *
603      * @since 1.4
604      */
605     @Deprecated(since="15")
606     boolean canUnrestrictedlyRedefineClasses();
607 
608     /**
609      * Determines if the target VM supports popping
610      * frames of a threads stack.
611      * @see ThreadReference#popFrames
612      *
613      * @return <code>true</code> if the feature is supported,
614      * <code>false</code> otherwise.
615      *
616      * @since 1.4
617      */
618     boolean canPopFrames();
619 
620     /**
621      * Determines if the target VM supports getting
622      * the source debug extension.
623      * @see ReferenceType#sourceDebugExtension
624      *
625      * @return <code>true</code> if the feature is supported,
626      * <code>false</code> otherwise.
627      *
628      * @since 1.4
629      */
630     boolean canGetSourceDebugExtension();
631 
632     /**
633      * Determines if the target VM supports the creation of
634      * {@link VMDeathRequest}s.
635      * @see EventRequestManager#createVMDeathRequest
636      *
637      * @return <code>true</code> if the feature is supported,
638      * <code>false</code> otherwise.
639      *
640      * @since 1.4
641      */
642     boolean canRequestVMDeathEvent();
643 
644     /**
645      * Determines if the target VM supports the inclusion of return values
646      * in
647      * {@link MethodExitEvent}s.
648      * @see EventRequestManager#createMethodExitRequest
649      *
650      * @return <code>true</code> if the feature is supported,
651      * <code>false</code> otherwise.
652      *
653      * @since 1.6
654      */
655     boolean canGetMethodReturnValues();
656 
657     /**
658      * Determines if the target VM supports the accessing of class instances,
659      * instance counts, and referring objects.
660      *
661      * @see #instanceCounts
662      * @see ReferenceType#instances(long)
663      * @see ObjectReference#referringObjects(long)
664      *
665      * @return <code>true</code> if the feature is supported,
666      * <code>false</code> otherwise.
667      *
668      * @since 1.6
669      */
670     boolean canGetInstanceInfo();
671 
672     /**
673      * Determines if the target VM supports the filtering of
674      * class prepare events by source name.
675      *
676      * see {@link ClassPrepareRequest#addSourceNameFilter}.
677      * @return <code>true</code> if the feature is supported,
678      * <code>false</code> otherwise.
679      *
680      * @since 1.6
681      */
682     boolean canUseSourceNameFilters();
683 
684     /**
685      * Determines if the target VM supports the forcing of a method to
686      * return early.
687      *
688      * @see ThreadReference#forceEarlyReturn(Value)
689      *
690      * @return <code>true</code> if the feature is supported,
691      * <code>false</code> otherwise.
692      *
693      * @since 1.6
694      */
695     boolean canForceEarlyReturn();
696 
697     /**
698      * Determines if the target VM is a read-only VM.  If a method which
699      * would modify the state of the VM is called on a read-only VM,
700      * then {@link VMCannotBeModifiedException} is thrown.
701      *
702      * @return <code>true</code> if the feature is supported,
703      * <code>false</code> otherwise.
704      *
705      * @since 1.5
706      */
707 
708     boolean canBeModified();
709 
710     /**
711      * Determines if the target VM supports the creation of
712      * {@link MonitorContendedEnterRequest}s.
713      * {@link MonitorContendedEnteredRequest}s.
714      * {@link MonitorWaitRequest}s.
715      * {@link MonitorWaitedRequest}s.
716      * @see EventRequestManager#createMonitorContendedEnterRequest
717      * @see EventRequestManager#createMonitorContendedEnteredRequest
718      * @see EventRequestManager#createMonitorWaitRequest
719      * @see EventRequestManager#createMonitorWaitedRequest
720      *
721      * @return <code>true</code> if the feature is supported,
722      * <code>false</code> otherwise.
723      *
724      * @since 1.6
725      */
726 
727     boolean canRequestMonitorEvents();
728 
729     /**
730      * Determines if the target VM supports getting which
731      * frame has acquired a monitor.
732      * @see ThreadReference#ownedMonitorsAndFrames
733      *
734      * @return <code>true</code> if the feature is supported,
735      * <code>false</code> otherwise.
736      *
737      * @since 1.6
738      */
739 
740      boolean canGetMonitorFrameInfo();
741 
742 
743     /**
744      * Determines if the target VM supports reading class file
745      * major and minor versions.
746      *
747      * @see ReferenceType#majorVersion()
748      * @see ReferenceType#minorVersion()
749      *
750      * @return <code>true</code> if the feature is supported,
751      * <code>false</code> otherwise.
752      *
753      * @since 1.6
754      */
755     boolean canGetClassFileVersion();
756 
757     /**
758      * Determines if the target VM supports getting constant pool
759      * information of a class.
760      *
761      * @see ReferenceType#constantPoolCount()
762      * @see ReferenceType#constantPool()
763      *
764      * @return <code>true</code> if the feature is supported,
765      * <code>false</code> otherwise.
766      *
767      * @since 1.6
768      */
769     boolean canGetConstantPool();
770 
771     /**
772      * Determines if the target VM supports getting information about modules.
773      *
774      * @return {@code true} if the feature is supported, {@code false} otherwise
775      *
776      * @implSpec
777      * The default implementation returns {@code false}.
778      *
779      * @see VirtualMachine#allModules()
780      * @see ReferenceType#module()
781      * @see ModuleReference
782      *
783      * @since 9
784      */
785     default boolean canGetModuleInfo() {
786         return false;
787     }
788 
789     /**
790      * Determine if the target VM support virtual threads.
791      *
792      * @return {@code true} if the feature is supported, {@code false} otherwise
793      *
794      * @apiNote
795      * This is a temporary method to test the capability of the target VM.
796      *
797      * @implSpec
798      * The default implementation returns {@code false}.
799      *
800      * @since 99
801      */
802     default boolean supportsVirtualThreads() {
803         return false;
804     }
805 
806     /**
807      * Set this VM's default stratum (see {@link Location} for a
808      * discussion of strata).  Overrides the per-class default set
809      * in the class file.
810      * <P>
811      * Affects location queries (such as,
812      * {@link Location#sourceName()})
813      * and the line boundaries used in
814      * single stepping.
815      *
816      * @param stratum the stratum to set as VM default,
817      * or null to use per-class defaults.
818      *
819      * @throws java.lang.UnsupportedOperationException if the
820      * target virtual machine does not support this operation.
821      *
822      * @since 1.4
823      */
824     void setDefaultStratum(String stratum);
825 
826     /**
827      * Return this VM's default stratum.
828      *
829      * @see #setDefaultStratum(String)
830      * @see ReferenceType#defaultStratum()
831      * @return <code>null</code> (meaning that the per-class
832      * default - {@link ReferenceType#defaultStratum()} -
833      * should be used) unless the default stratum has been
834      * set with
835      * {@link #setDefaultStratum(String)}.
836      *
837      * @since 1.4
838      */
839     String getDefaultStratum();
840 
841     /**
842      * Returns the number of instances of each ReferenceType in the 'refTypes'
843      * list.
844      * Only instances that are reachable for the purposes of garbage collection
845      * are counted.
846      * <p>
847      * Not all target virtual machines support this operation.
848      * Use {@link VirtualMachine#canGetInstanceInfo()}
849      * to determine if the operation is supported.
850      *
851      * @see ReferenceType#instances(long)
852      * @see ObjectReference#referringObjects(long)
853      * @param refTypes the list of {@link ReferenceType} objects for which counts
854      *        are to be obtained.
855      *
856      * @return an array of <code>long</code> containing one element for each
857      *         element in the 'refTypes' list.  Element i of the array contains
858      *         the number of instances in the target VM of the ReferenceType at
859      *         position i in the 'refTypes' list.
860      *         If the 'refTypes' list is empty, a zero-length array is returned.
861      *         If a ReferenceType in refTypes has been garbage collected, zero
862      *         is returned for its instance count.
863      * @throws java.lang.UnsupportedOperationException if
864      * the target virtual machine does not support this
865      * operation - see
866      * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
867      * @throws NullPointerException if the 'refTypes' list is null.
868      * @since 1.6
869      */
870     long[] instanceCounts(List<? extends ReferenceType> refTypes);
871 
872     /**
873      * Returns text information on the target VM and the
874      * debugger support that mirrors it. No specific format
875      * for this information is guaranteed.
876      * Typically, this string contains version information for the
877      * target VM and debugger interfaces.
878      * More precise information
879      * on VM and JDI versions is available through
880      * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion},
881      * and {@link VirtualMachineManager#minorInterfaceVersion}
882      *
883      * @return the description.
884      */
885     String description();
886 
887     /**
888      * Returns the version of the Java Runtime Environment in the target
889      * VM as reported by the property <code>java.version</code>.
890      * For obtaining the JDI interface version, use
891      * {@link VirtualMachineManager#majorInterfaceVersion}
892      * and {@link VirtualMachineManager#minorInterfaceVersion}
893      *
894      * @return the target VM version.
895      */
896     String version();
897 
898     /**
899      * Returns the name of the target VM as reported by the
900      * property <code>java.vm.name</code>.
901      *
902      * @return the target VM name.
903      */
904     String name();
905 
906     /** All tracing is disabled. */
907     int TRACE_NONE        = 0x00000000;
908     /** Tracing enabled for JDWP packets sent to target VM. */
909     int TRACE_SENDS       = 0x00000001;
910     /** Tracing enabled for JDWP packets received from target VM. */
911     int TRACE_RECEIVES    = 0x00000002;
912     /** Tracing enabled for internal event handling. */
913     int TRACE_EVENTS      = 0x00000004;
914     /** Tracing enabled for internal managment of reference types. */
915     int TRACE_REFTYPES    = 0x00000008;
916     /** Tracing enabled for internal management of object references. */
917     int TRACE_OBJREFS      = 0x00000010;
918     /** All tracing is enabled. */
919     int TRACE_ALL         = 0x00ffffff;
920 
921     /**
922      * Traces the activities performed by the com.sun.jdi implementation.
923      * All trace information is output to System.err. The given trace
924      * flags are used to limit the output to only the information
925      * desired. The given flags are in effect and the corresponding
926      * trace will continue until the next call to
927      * this method.
928      * <p>
929      * Output is implementation dependent and trace mode may be ignored.
930      *
931      * @param traceFlags identifies which kinds of tracing to enable.
932      */
933     void setDebugTraceMode(int traceFlags);
934 }