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