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 * A class or interface creation can be triggered by one of the following:
139 * <ul>
140 * <li>by loading and deriving a class from a `class` file representation
141 * using class loader (see JVMS {@jvms 5.3}).
142 * <li>by invoking {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, java.lang.invoke.MethodHandles.Lookup.ClassOption...)
143 * Lookup::defineHiddenClass} that creates a {@link Class#isHidden
144 * hidden class or interface} from a {@code class} file representation.
145 * <li>by invoking methods in certain Java SE Platform API such as reflection.
146 * </ul>
147 * <p>
148 * An array class is created directly by Java virtual machine. An array
149 * class creation can be triggered by using class loaders or by invoking
150 * methods in certain Java SE Platform API such as reflection.
151 * <p>
152 * The returned list will include all reference types, including
153 * {@link Class#isHidden hidden classes or interfaces}, loaded
154 * at least to the point of preparation and types (like array)
155 * for which preparation is not defined.
156 *
157 * @return a list of {@link ReferenceType} objects, each mirroring
158 * a loaded type in the target VM.
159 * @jvms 5.3 Creation and Loading
160 */
161 List<ReferenceType> allClasses();
162
163 /**
164 * All classes given are redefined according to the
165 * definitions supplied. A method in a redefined class
166 * is called 'equivalent' (to the old version of the
167 * method) if
168 * <UL>
169 * <LI>their bytecodes are the same except for indicies into
170 * the constant pool, and
171 * <LI>the referenced constants are equal.
172 * </UL>
173 * Otherwise, the new method is called 'non-equivalent'.
174 * If a redefined method has active stack frames, those active
175 * frames continue to run the bytecodes of the previous version of the
176 * method. If the new version of such a method is non-equivalent,
177 * then a method from one of these active frames is called 'obsolete' and
178 * {@link Method#isObsolete Method.isObsolete()}
179 * will return true when called on one of these methods.
180 * If resetting such a frame is desired, use
181 * {@link ThreadReference#popFrames ThreadReference.popFrames(StackFrame)}
182 * to pop the old obsolete method execution from the stack.
183 * New invocations of redefined methods will always invoke the new versions.
184 * <p>
185 * This function does not cause any initialization except
186 * that which would occur under the customary JVM semantics.
187 * In other words, redefining a class does not cause
188 * its initializers to be run. The values of preexisting
189 * static variables will remain as they were prior to the
190 * call. However, completely uninitialized (new) static
191 * variables will be assigned their default value.
192 * <p>
193 * If a redefined class has instances then all those
194 * instances will have the fields defined by the redefined
195 * class at the completion of the call. Preexisting fields
196 * will retain their previous values. Any new fields will
197 * have their default values; no instance initializers or
198 * constructors are run.
199 * <p>
200 * Threads need not be suspended.
201 * <p>
202 * No events are generated by this function.
203 * <p>
204 * All breakpoints in the redefined classes are deleted.
205 * <p>
206 * Not all target virtual machines support this operation.
207 * Use {@link #canRedefineClasses() canRedefineClasses()}
208 * to determine if the operation is supported.
209 * Use {@link #canAddMethod() canAddMethod()}
210 * to determine if the redefinition can add methods.
211 * Use {@link #canUnrestrictedlyRedefineClasses() canUnrestrictedlyRedefineClasses()}
212 * to determine if the redefinition can change the schema,
213 * delete methods, change the class hierarchy, etc.
214 *
215 * @param classToBytes A map from {@link ReferenceType}
216 * to array of byte.
217 * The bytes represent the new class definition and
218 * are in Java Virtual Machine class file format.
219 *
220 * @throws java.lang.UnsupportedOperationException if
221 * the target virtual machine does not support this
222 * operation.
223 * <UL>
224 * <LI>If {@link #canRedefineClasses() canRedefineClasses()}
225 * is false any call of this method will throw this exception.
226 * <LI>If {@link #canAddMethod() canAddMethod()} is false
227 * attempting to add a method will throw this exception.
228 * <LI>If {@link #canUnrestrictedlyRedefineClasses()
229 * canUnrestrictedlyRedefineClasses()}
230 * is false, attempting any of the following will throw
231 * this exception
232 * <UL>
233 * <LI>changing the schema (the fields)
234 * <LI>changing the hierarchy (superclasses, interfaces)
235 * <LI>deleting a method
236 * <LI>changing class modifiers
237 * <LI>changing method modifiers
238 * <LI>changing the {@code NestHost}, {@code NestMembers}, or {@code Record} class attributes
239 * </UL>
240 * </UL>
241 *
242 * @throws java.lang.NoClassDefFoundError if the bytes
243 * don't correspond to the reference type (the names
244 * don't match).
245 *
246 * @throws java.lang.VerifyError if a "verifier" detects
247 * that a class, though well formed, contains an internal
248 * inconsistency or security problem.
249 *
250 * @throws java.lang.ClassFormatError if the bytes
251 * do not represent a valid class.
252 *
253 * @throws java.lang.ClassCircularityError if a
254 * circularity has been detected while initializing a class.
255 *
256 * @throws java.lang.UnsupportedClassVersionError if the
257 * major and minor version numbers in bytes
258 * are not supported by the VM.
259 *
260 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
261 *
262 * @see Method#isObsolete
263 * @see ThreadReference#popFrames
264 * @see #canRedefineClasses
265 * @see #canAddMethod
266 * @see #canUnrestrictedlyRedefineClasses
267 *
268 * @since 1.4
269 */
270 void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes);
271
272 /**
273 * Returns a list of the currently running threads. For each
274 * running thread in the target VM, a {@link ThreadReference}
275 * that mirrors it is placed in the list.
276 * The returned list contains threads created through
277 * java.lang.Thread, all native threads attached to
278 * the target VM through JNI, and system threads created
279 * by the target VM. Thread objects that have
280 * not yet been started
281 * (see {@link java.lang.Thread#start Thread.start()})
282 * and thread objects that have
283 * completed their execution are not included in the returned list.
284 *
285 * @return a list of {@link ThreadReference} objects, one for each
286 * running thread in the mirrored VM.
287 */
288 List<ThreadReference> allThreads();
289
290 /**
291 * Suspends the execution of the application running in this
292 * virtual machine. All threads currently running will be suspended.
293 * <p>
294 * Unlike {@link java.lang.Thread#suspend Thread.suspend()},
295 * suspends of both the virtual machine and individual threads are
296 * counted. Before a thread will run again, it must be resumed
297 * (through {@link #resume} or {@link ThreadReference#resume})
298 * the same number of times it has been suspended.
299 *
300 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
301 */
302 void suspend();
303
304 /**
305 * Continues the execution of the application running in this
306 * virtual machine. All threads are resumed as documented in
307 * {@link ThreadReference#resume}.
308 *
309 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
310 *
311 * @see #suspend
312 */
313 void resume();
314
315 /**
316 * Returns each thread group which does not have a parent. For each
317 * top level thread group a {@link ThreadGroupReference} is placed in the
318 * returned list.
319 * <p>
320 * This command may be used as the first step in building a tree
321 * (or trees) of the existing thread groups.
322 *
323 * @return a list of {@link ThreadGroupReference} objects, one for each
324 * top level thread group.
325 */
326 List<ThreadGroupReference> topLevelThreadGroups();
327
328 /**
329 * Returns the event queue for this virtual machine.
330 * A virtual machine has only one {@link EventQueue} object, this
331 * method will return the same instance each time it
332 * is invoked.
333 *
334 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
335 *
336 * @return the {@link EventQueue} for this virtual machine.
337 */
338 EventQueue eventQueue();
339
340 /**
341 * Returns the event request manager for this virtual machine.
342 * The {@link EventRequestManager} controls user settable events
343 * such as breakpoints.
344 * A virtual machine has only one {@link EventRequestManager} object,
345 * this method will return the same instance each time it
346 * is invoked.
347 *
348 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
349 *
350 * @return the {@link EventRequestManager} for this virtual machine.
351 */
352 EventRequestManager eventRequestManager();
353
354 /**
355 * Creates a {@link BooleanValue} 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 boolean for which to create the value
360 * @return the {@link BooleanValue} for the given boolean.
361 */
362 BooleanValue mirrorOf(boolean value);
363
364 /**
365 * Creates a {@link ByteValue} 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 byte for which to create the value
370 * @return the {@link ByteValue} for the given byte.
371 */
372 ByteValue mirrorOf(byte value);
373
374 /**
375 * Creates a {@link CharValue} 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 a char for which to create the value
380 * @return the {@link CharValue} for the given char.
381 */
382 CharValue mirrorOf(char value);
383
384 /**
385 * Creates a {@link ShortValue} 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 short for which to create the value
390 * @return the {@link ShortValue} for the given short.
391 */
392 ShortValue mirrorOf(short value);
393
394 /**
395 * Creates an {@link IntegerValue} 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 an int for which to create the value
400 * @return the {@link IntegerValue} for the given int.
401 */
402 IntegerValue mirrorOf(int value);
403
404 /**
405 * Creates a {@link LongValue} 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 long for which to create the value
410 * @return the {@link LongValue} for the given long.
411 */
412 LongValue mirrorOf(long value);
413
414 /**
415 * Creates a {@link FloatValue} for the given value. This value
416 * can be used for setting and comparing against a value retrieved
417 * from a variable or field in this virtual machine.
418 *
419 * @param value a float for which to create the value
420 * @return the {@link FloatValue} for the given float.
421 */
422 FloatValue mirrorOf(float value);
423
424 /**
425 * Creates a {@link DoubleValue} for the given value. This value
426 * can be used for setting and comparing against a value retrieved
427 * from a variable or field in this virtual machine.
428 *
429 * @param value a double for which to create the value
430 * @return the {@link DoubleValue} for the given double.
431 */
432 DoubleValue mirrorOf(double value);
433
434 /**
435 * Creates a string in this virtual machine.
436 * The created string can be used for setting and comparing against
437 * a string value retrieved from a variable or field in this
438 * virtual machine.
439 *
440 * @param value the string to be created
441 * @return a {@link StringReference} that mirrors the newly created
442 * string in the target VM.
443 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
444 * -see {@link VirtualMachine#canBeModified()}.
445 */
446 StringReference mirrorOf(String value);
447
448
449 /**
450 * Creates a {@link VoidValue}. This value
451 * can be passed to {@link ThreadReference#forceEarlyReturn}
452 * when a void method is to be exited.
453 *
454 * @return the {@link VoidValue}.
455 */
456 VoidValue mirrorOfVoid();
457
458 /**
459 * Returns the {@link java.lang.Process} object for this
460 * virtual machine if launched by a {@link LaunchingConnector}
461 *
462 * @return the {@link java.lang.Process} object for this virtual
463 * machine, or null if it was not launched by a {@link LaunchingConnector}.
464 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
465 * -see {@link VirtualMachine#canBeModified()}.
466 */
467 Process process();
468
469 /**
470 * Invalidates this virtual machine mirror.
471 * The communication channel to the target VM is closed, and
472 * the target VM prepares to accept another subsequent connection
473 * from this debugger or another debugger, including the
474 * following tasks:
475 * <ul>
476 * <li>All event requests are cancelled.
477 * <li>All threads suspended by {@link #suspend} or by
478 * {@link ThreadReference#suspend} are resumed as many
479 * times as necessary for them to run.
480 * <li>Garbage collection is re-enabled in all cases where it was
481 * disabled through {@link ObjectReference#disableCollection}.
482 * </ul>
483 * Any current method invocations executing in the target VM
484 * are continued after the disconnection. Upon completion of any such
485 * method invocation, the invoking thread continues from the
486 * location where it was originally stopped.
487 * <p>
488 * Resources originating in
489 * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
490 * will become invalid.
491 */
492 void dispose();
493
494 /**
495 * Causes the mirrored VM to terminate with the given error code.
496 * All resources associated with this VirtualMachine are freed.
497 * If the mirrored VM is remote, the communication channel
498 * to it will be closed. Resources originating in
499 * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
500 * will become invalid.
501 * <p>
502 * Threads running in the mirrored VM are abruptly terminated.
503 * A thread death exception is not thrown and
504 * finally blocks are not run.
505 *
506 * @param exitCode the exit code for the target VM. On some platforms,
507 * the exit code might be truncated, for example, to the lower order 8 bits.
508 *
509 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
510 */
511 void exit(int exitCode);
512
513 /**
514 * Determines if the target VM supports watchpoints
515 * for field modification.
516 *
517 * @return <code>true</code> if the feature is supported,
518 * <code>false</code> otherwise.
519 */
520 boolean canWatchFieldModification();
521
522 /**
523 * Determines if the target VM supports watchpoints
524 * for field access.
525 *
526 * @return <code>true</code> if the feature is supported,
527 * <code>false</code> otherwise.
528 */
529 boolean canWatchFieldAccess();
530
531 /**
532 * Determines if the target VM supports the retrieval
533 * of a method's bytecodes.
534 *
535 * @return <code>true</code> if the feature is supported,
536 * <code>false</code> otherwise.
537 */
538 boolean canGetBytecodes();
539
540 /**
541 * Determines if the target VM supports the query
542 * of the synthetic attribute of a method or field.
543 *
544 * @return <code>true</code> if the feature is supported,
545 * <code>false</code> otherwise.
546 */
547 boolean canGetSyntheticAttribute();
548
549 /**
550 * Determines if the target VM supports the retrieval
551 * of the monitors owned by a thread.
552 *
553 * @return <code>true</code> if the feature is supported,
554 * <code>false</code> otherwise.
555 */
556 boolean canGetOwnedMonitorInfo();
557
558 /**
559 * Determines if the target VM supports the retrieval
560 * of the monitor for which a thread is currently waiting.
561 *
562 * @return <code>true</code> if the feature is supported,
563 * <code>false</code> otherwise.
564 */
565 boolean canGetCurrentContendedMonitor();
566
567 /**
568 * Determines if the target VM supports the retrieval
569 * of the monitor information for an object.
570 *
571 * @return <code>true</code> if the feature is supported,
572 * <code>false</code> otherwise.
573 */
574 boolean canGetMonitorInfo();
575
576 /**
577 * Determines if the target VM supports filtering
578 * events by specific instance object. For example,
579 * see {@link BreakpointRequest#addInstanceFilter}.
580 *
581 * @return <code>true</code> if the feature is supported,
582 * <code>false</code> otherwise.
583 */
584 boolean canUseInstanceFilters();
585
586 /**
587 * Determines if the target VM supports any level
588 * of class redefinition.
589 * @see #redefineClasses
590 *
591 * @return <code>true</code> if the feature is supported,
592 * <code>false</code> otherwise.
593 *
594 * @since 1.4
595 */
596 boolean canRedefineClasses();
597
598 /**
599 * Determines if the target VM supports the addition
600 * of methods when performing class redefinition.
601 * @see #redefineClasses
602 *
603 * @return <code>true</code> if the feature is supported,
604 * <code>false</code> otherwise.
605 *
606 * @since 1.4
607 */
608 boolean canAddMethod();
609
610 /**
611 * Determines if the target VM supports
612 * changes when performing class redefinition that are
613 * otherwise restricted by {@link #redefineClasses}.
614 * @see #redefineClasses
615 *
616 * @return <code>true</code> if the feature is supported,
617 * <code>false</code> otherwise.
618 *
619 * @since 1.4
620 */
621 boolean canUnrestrictedlyRedefineClasses();
622
623 /**
624 * Determines if the target VM supports popping
625 * frames of a threads stack.
626 * @see ThreadReference#popFrames
627 *
628 * @return <code>true</code> if the feature is supported,
629 * <code>false</code> otherwise.
630 *
631 * @since 1.4
632 */
633 boolean canPopFrames();
634
635 /**
636 * Determines if the target VM supports getting
637 * the source debug extension.
638 * @see ReferenceType#sourceDebugExtension
639 *
640 * @return <code>true</code> if the feature is supported,
641 * <code>false</code> otherwise.
642 *
643 * @since 1.4
644 */
645 boolean canGetSourceDebugExtension();
646
647 /**
648 * Determines if the target VM supports the creation of
649 * {@link VMDeathRequest}s.
650 * @see EventRequestManager#createVMDeathRequest
651 *
652 * @return <code>true</code> if the feature is supported,
653 * <code>false</code> otherwise.
654 *
655 * @since 1.4
656 */
657 boolean canRequestVMDeathEvent();
658
659 /**
660 * Determines if the target VM supports the inclusion of return values
661 * in
662 * {@link MethodExitEvent}s.
663 * @see EventRequestManager#createMethodExitRequest
664 *
665 * @return <code>true</code> if the feature is supported,
666 * <code>false</code> otherwise.
667 *
668 * @since 1.6
669 */
670 boolean canGetMethodReturnValues();
671
672 /**
673 * Determines if the target VM supports the accessing of class instances,
674 * instance counts, and referring objects.
675 *
676 * @see #instanceCounts
677 * @see ReferenceType#instances(long)
678 * @see ObjectReference#referringObjects(long)
679 *
680 * @return <code>true</code> if the feature is supported,
681 * <code>false</code> otherwise.
682 *
683 * @since 1.6
684 */
685 boolean canGetInstanceInfo();
686
687 /**
688 * Determines if the target VM supports the filtering of
689 * class prepare events by source name.
690 *
691 * see {@link ClassPrepareRequest#addSourceNameFilter}.
692 * @return <code>true</code> if the feature is supported,
693 * <code>false</code> otherwise.
694 *
695 * @since 1.6
696 */
697 boolean canUseSourceNameFilters();
698
699 /**
700 * Determines if the target VM supports the forcing of a method to
701 * return early.
702 *
703 * @see ThreadReference#forceEarlyReturn(Value)
704 *
705 * @return <code>true</code> if the feature is supported,
706 * <code>false</code> otherwise.
707 *
708 * @since 1.6
709 */
710 boolean canForceEarlyReturn();
711
712 /**
713 * Determines if the target VM is a read-only VM. If a method which
714 * would modify the state of the VM is called on a read-only VM,
715 * then {@link VMCannotBeModifiedException} is thrown.
716 *
717 * @return <code>true</code> if the feature is supported,
718 * <code>false</code> otherwise.
719 *
720 * @since 1.5
721 */
722
723 boolean canBeModified();
724
725 /**
726 * Determines if the target VM supports the creation of
727 * {@link MonitorContendedEnterRequest}s.
728 * {@link MonitorContendedEnteredRequest}s.
729 * {@link MonitorWaitRequest}s.
730 * {@link MonitorWaitedRequest}s.
731 * @see EventRequestManager#createMonitorContendedEnterRequest
732 * @see EventRequestManager#createMonitorContendedEnteredRequest
733 * @see EventRequestManager#createMonitorWaitRequest
734 * @see EventRequestManager#createMonitorWaitedRequest
735 *
736 * @return <code>true</code> if the feature is supported,
737 * <code>false</code> otherwise.
738 *
739 * @since 1.6
740 */
741
742 boolean canRequestMonitorEvents();
743
744 /**
745 * Determines if the target VM supports getting which
746 * frame has acquired a monitor.
747 * @see ThreadReference#ownedMonitorsAndFrames
748 *
749 * @return <code>true</code> if the feature is supported,
750 * <code>false</code> otherwise.
751 *
752 * @since 1.6
753 */
754
755 boolean canGetMonitorFrameInfo();
756
757
758 /**
759 * Determines if the target VM supports reading class file
760 * major and minor versions.
761 *
762 * @see ReferenceType#majorVersion()
763 * @see ReferenceType#minorVersion()
764 *
765 * @return <code>true</code> if the feature is supported,
766 * <code>false</code> otherwise.
767 *
768 * @since 1.6
769 */
770 boolean canGetClassFileVersion();
771
772 /**
773 * Determines if the target VM supports getting constant pool
774 * information of a class.
775 *
776 * @see ReferenceType#constantPoolCount()
777 * @see ReferenceType#constantPool()
778 *
779 * @return <code>true</code> if the feature is supported,
780 * <code>false</code> otherwise.
781 *
782 * @since 1.6
783 */
784 boolean canGetConstantPool();
785
786 /**
787 * Determines if the target VM supports getting information about modules.
788 *
789 * @return {@code true} if the feature is supported, {@code false} otherwise
790 *
791 * @implSpec
792 * The default implementation returns {@code false}.
793 *
794 * @see VirtualMachine#allModules()
795 * @see ReferenceType#module()
796 * @see ModuleReference
797 *
798 * @since 9
799 */
800 default boolean canGetModuleInfo() {
801 return false;
802 }
803
804 /**
805 * Set this VM's default stratum (see {@link Location} for a
806 * discussion of strata). Overrides the per-class default set
807 * in the class file.
808 * <P>
809 * Affects location queries (such as,
810 * {@link Location#sourceName()})
811 * and the line boundaries used in
812 * single stepping.
813 *
814 * @param stratum the stratum to set as VM default,
815 * or null to use per-class defaults.
816 *
817 * @throws java.lang.UnsupportedOperationException if the
818 * target virtual machine does not support this operation.
819 *
820 * @since 1.4
821 */
822 void setDefaultStratum(String stratum);
823
824 /**
825 * Return this VM's default stratum.
826 *
827 * @see #setDefaultStratum(String)
828 * @see ReferenceType#defaultStratum()
829 * @return <code>null</code> (meaning that the per-class
830 * default - {@link ReferenceType#defaultStratum()} -
831 * should be used) unless the default stratum has been
832 * set with
833 * {@link #setDefaultStratum(String)}.
834 *
835 * @since 1.4
836 */
837 String getDefaultStratum();
838
839 /**
840 * Returns the number of instances of each ReferenceType in the 'refTypes'
841 * list.
842 * Only instances that are reachable for the purposes of garbage collection
843 * are counted.
844 * <p>
845 * Not all target virtual machines support this operation.
846 * Use {@link VirtualMachine#canGetInstanceInfo()}
847 * to determine if the operation is supported.
848 *
849 * @see ReferenceType#instances(long)
850 * @see ObjectReference#referringObjects(long)
851 * @param refTypes the list of {@link ReferenceType} objects for which counts
852 * are to be obtained.
853 *
854 * @return an array of <code>long</code> containing one element for each
855 * element in the 'refTypes' list. Element i of the array contains
856 * the number of instances in the target VM of the ReferenceType at
857 * position i in the 'refTypes' list.
858 * If the 'refTypes' list is empty, a zero-length array is returned.
859 * If a ReferenceType in refTypes has been garbage collected, zero
860 * is returned for its instance count.
861 * @throws java.lang.UnsupportedOperationException if
862 * the target virtual machine does not support this
863 * operation - see
864 * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
865 * @throws NullPointerException if the 'refTypes' list is null.
866 * @since 1.6
867 */
868 long[] instanceCounts(List<? extends ReferenceType> refTypes);
869
870 /**
871 * Returns text information on the target VM and the
872 * debugger support that mirrors it. No specific format
873 * for this information is guaranteed.
874 * Typically, this string contains version information for the
875 * target VM and debugger interfaces.
876 * More precise information
877 * on VM and JDI versions is available through
878 * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion},
879 * and {@link VirtualMachineManager#minorInterfaceVersion}
880 *
881 * @return the description.
882 */
883 String description();
884
885 /**
886 * Returns the version of the Java Runtime Environment in the target
887 * VM as reported by the property <code>java.version</code>.
888 * For obtaining the JDI interface version, use
889 * {@link VirtualMachineManager#majorInterfaceVersion}
890 * and {@link VirtualMachineManager#minorInterfaceVersion}
891 *
892 * @return the target VM version.
893 */
894 String version();
895
896 /**
897 * Returns the name of the target VM as reported by the
898 * property <code>java.vm.name</code>.
899 *
900 * @return the target VM name.
901 */
902 String name();
903
904 /** All tracing is disabled. */
905 int TRACE_NONE = 0x00000000;
906 /** Tracing enabled for JDWP packets sent to target VM. */
907 int TRACE_SENDS = 0x00000001;
908 /** Tracing enabled for JDWP packets received from target VM. */
909 int TRACE_RECEIVES = 0x00000002;
910 /** Tracing enabled for internal event handling. */
911 int TRACE_EVENTS = 0x00000004;
912 /** Tracing enabled for internal managment of reference types. */
913 int TRACE_REFTYPES = 0x00000008;
914 /** Tracing enabled for internal management of object references. */
915 int TRACE_OBJREFS = 0x00000010;
916 /** All tracing is enabled. */
917 int TRACE_ALL = 0x00ffffff;
918
919 /**
920 * Traces the activities performed by the com.sun.jdi implementation.
921 * All trace information is output to System.err. The given trace
922 * flags are used to limit the output to only the information
923 * desired. The given flags are in effect and the corresponding
924 * trace will continue until the next call to
925 * this method.
926 * <p>
927 * Output is implementation dependent and trace mode may be ignored.
928 *
929 * @param traceFlags identifies which kinds of tracing to enable.
930 */
931 void setDebugTraceMode(int traceFlags);
932 }