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