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