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