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 * The returned list includes all reference types, including
139 * {@link Class#isHidden hidden classes or interfaces}, loaded
140 * at least to the point of preparation and types (like array)
141 * for which preparation is not defined.
142 *
143 * @return a list of {@link ReferenceType} objects, each mirroring
144 * a loaded type in the target VM.
145 * @see <a href="{@docRoot}/../specs/jvmti/jvmti.html#GetLoadedClasses">
146 * JVM TI GetLoadedClasses</a> regarding how class and interface creation can be triggered
147 */
148 List<ReferenceType> allClasses();
149
150 /**
151 * All classes given are redefined according to the
152 * definitions supplied. A method in a redefined class
153 * is called 'equivalent' (to the old version of the
154 * method) if
155 * <UL>
156 * <LI>their bytecodes are the same except for indicies into
157 * the constant pool, and
158 * <LI>the referenced constants are equal.
159 * </UL>
160 * Otherwise, the new method is called 'non-equivalent'.
161 * If a redefined method has active stack frames, those active
162 * frames continue to run the bytecodes of the previous version of the
163 * method. If the new version of such a method is non-equivalent,
164 * then a method from one of these active frames is called 'obsolete' and
165 * {@link Method#isObsolete Method.isObsolete()}
166 * will return true when called on one of these methods.
167 * If resetting such a frame is desired, use
168 * {@link ThreadReference#popFrames ThreadReference.popFrames(StackFrame)}
169 * to pop the old obsolete method execution from the stack.
170 * New invocations of redefined methods will always invoke the new versions.
171 * <p>
172 * This function does not cause any initialization except
173 * that which would occur under the customary JVM semantics.
174 * In other words, redefining a class does not cause
175 * its initializers to be run. The values of preexisting
176 * static variables will remain as they were prior to the
177 * call. However, completely uninitialized (new) static
178 * variables will be assigned their default value.
179 * <p>
180 * If a redefined class has instances then all those
181 * instances will have the fields defined by the redefined
182 * class at the completion of the call. Preexisting fields
183 * will retain their previous values. Any new fields will
184 * have their default values; no instance initializers or
185 * constructors are run.
186 * <p>
187 * Threads need not be suspended.
188 * <p>
189 * No events are generated by this function.
190 * <p>
191 * All breakpoints in the redefined classes are deleted.
192 * <p>
193 * Not all target virtual machines support this operation.
194 * Use {@link #canRedefineClasses() canRedefineClasses()}
195 * to determine if the operation is supported.
196 * Use {@link #canAddMethod() canAddMethod()}
197 * to determine if the redefinition can add methods.
198 * Use {@link #canUnrestrictedlyRedefineClasses() canUnrestrictedlyRedefineClasses()}
199 * to determine if the redefinition can change the schema,
200 * delete methods, change the class hierarchy, etc.
201 *
202 * @param classToBytes A map from {@link ReferenceType}
203 * to array of byte.
204 * The bytes represent the new class definition and
205 * are in Java Virtual Machine class file format.
206 *
207 * @throws java.lang.UnsupportedOperationException if
208 * the target virtual machine does not support this
209 * operation.
210 * <UL>
211 * <LI>If {@link #canRedefineClasses() canRedefineClasses()}
212 * is false any call of this method will throw this exception.
213 * <LI>If {@link #canAddMethod() canAddMethod()} is false
214 * attempting to add a method will throw this exception.
215 * <LI>If {@link #canUnrestrictedlyRedefineClasses()
216 * canUnrestrictedlyRedefineClasses()}
217 * is false, attempting any of the following will throw
218 * this exception
219 * <UL>
220 * <LI>changing the schema (the fields)
221 * <LI>changing the hierarchy (superclasses, interfaces)
222 * <LI>deleting a method
223 * <LI>changing class modifiers
224 * <LI>changing method modifiers
225 * <LI>changing the {@code NestHost}, {@code NestMembers}, or {@code Record} class attributes
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
599 * changes when performing class redefinition that are
600 * otherwise restricted by {@link #redefineClasses}.
601 * @see #redefineClasses
602 *
603 * @return <code>true</code> if the feature is supported,
604 * <code>false</code> otherwise.
605 *
606 * @since 1.4
607 */
608 boolean canUnrestrictedlyRedefineClasses();
609
610 /**
611 * Determines if the target VM supports popping
612 * frames of a threads stack.
613 * @see ThreadReference#popFrames
614 *
615 * @return <code>true</code> if the feature is supported,
616 * <code>false</code> otherwise.
617 *
618 * @since 1.4
619 */
620 boolean canPopFrames();
621
622 /**
623 * Determines if the target VM supports getting
624 * the source debug extension.
625 * @see ReferenceType#sourceDebugExtension
626 *
627 * @return <code>true</code> if the feature is supported,
628 * <code>false</code> otherwise.
629 *
630 * @since 1.4
631 */
632 boolean canGetSourceDebugExtension();
633
634 /**
635 * Determines if the target VM supports the creation of
636 * {@link VMDeathRequest}s.
637 * @see EventRequestManager#createVMDeathRequest
638 *
639 * @return <code>true</code> if the feature is supported,
640 * <code>false</code> otherwise.
641 *
642 * @since 1.4
643 */
644 boolean canRequestVMDeathEvent();
645
646 /**
647 * Determines if the target VM supports the inclusion of return values
648 * in
649 * {@link MethodExitEvent}s.
650 * @see EventRequestManager#createMethodExitRequest
651 *
652 * @return <code>true</code> if the feature is supported,
653 * <code>false</code> otherwise.
654 *
655 * @since 1.6
656 */
657 boolean canGetMethodReturnValues();
658
659 /**
660 * Determines if the target VM supports the accessing of class instances,
661 * instance counts, and referring objects.
662 *
663 * @see #instanceCounts
664 * @see ReferenceType#instances(long)
665 * @see ObjectReference#referringObjects(long)
666 *
667 * @return <code>true</code> if the feature is supported,
668 * <code>false</code> otherwise.
669 *
670 * @since 1.6
671 */
672 boolean canGetInstanceInfo();
673
674 /**
675 * Determines if the target VM supports the filtering of
676 * class prepare events by source name.
677 *
678 * see {@link ClassPrepareRequest#addSourceNameFilter}.
679 * @return <code>true</code> if the feature is supported,
680 * <code>false</code> otherwise.
681 *
682 * @since 1.6
683 */
684 boolean canUseSourceNameFilters();
685
686 /**
687 * Determines if the target VM supports the forcing of a method to
688 * return early.
689 *
690 * @see ThreadReference#forceEarlyReturn(Value)
691 *
692 * @return <code>true</code> if the feature is supported,
693 * <code>false</code> otherwise.
694 *
695 * @since 1.6
696 */
697 boolean canForceEarlyReturn();
698
699 /**
700 * Determines if the target VM is a read-only VM. If a method which
701 * would modify the state of the VM is called on a read-only VM,
702 * then {@link VMCannotBeModifiedException} is thrown.
703 *
704 * @return <code>true</code> if the feature is supported,
705 * <code>false</code> otherwise.
706 *
707 * @since 1.5
708 */
709
710 boolean canBeModified();
711
712 /**
713 * Determines if the target VM supports the creation of
714 * {@link MonitorContendedEnterRequest}s.
715 * {@link MonitorContendedEnteredRequest}s.
716 * {@link MonitorWaitRequest}s.
717 * {@link MonitorWaitedRequest}s.
718 * @see EventRequestManager#createMonitorContendedEnterRequest
719 * @see EventRequestManager#createMonitorContendedEnteredRequest
720 * @see EventRequestManager#createMonitorWaitRequest
721 * @see EventRequestManager#createMonitorWaitedRequest
722 *
723 * @return <code>true</code> if the feature is supported,
724 * <code>false</code> otherwise.
725 *
726 * @since 1.6
727 */
728
729 boolean canRequestMonitorEvents();
730
731 /**
732 * Determines if the target VM supports getting which
733 * frame has acquired a monitor.
734 * @see ThreadReference#ownedMonitorsAndFrames
735 *
736 * @return <code>true</code> if the feature is supported,
737 * <code>false</code> otherwise.
738 *
739 * @since 1.6
740 */
741
742 boolean canGetMonitorFrameInfo();
743
744
745 /**
746 * Determines if the target VM supports reading class file
747 * major and minor versions.
748 *
749 * @see ReferenceType#majorVersion()
750 * @see ReferenceType#minorVersion()
751 *
752 * @return <code>true</code> if the feature is supported,
753 * <code>false</code> otherwise.
754 *
755 * @since 1.6
756 */
757 boolean canGetClassFileVersion();
758
759 /**
760 * Determines if the target VM supports getting constant pool
761 * information of a class.
762 *
763 * @see ReferenceType#constantPoolCount()
764 * @see ReferenceType#constantPool()
765 *
766 * @return <code>true</code> if the feature is supported,
767 * <code>false</code> otherwise.
768 *
769 * @since 1.6
770 */
771 boolean canGetConstantPool();
772
773 /**
774 * Determines if the target VM supports getting information about modules.
775 *
776 * @return {@code true} if the feature is supported, {@code false} otherwise
777 *
778 * @implSpec
779 * The default implementation returns {@code false}.
780 *
781 * @see VirtualMachine#allModules()
782 * @see ReferenceType#module()
783 * @see ModuleReference
784 *
785 * @since 9
786 */
787 default boolean canGetModuleInfo() {
788 return false;
789 }
790
791 /**
792 * Set this VM's default stratum (see {@link Location} for a
793 * discussion of strata). Overrides the per-class default set
794 * in the class file.
795 * <P>
796 * Affects location queries (such as,
797 * {@link Location#sourceName()})
798 * and the line boundaries used in
799 * single stepping.
800 *
801 * @param stratum the stratum to set as VM default,
802 * or null to use per-class defaults.
803 *
804 * @throws java.lang.UnsupportedOperationException if the
805 * target virtual machine does not support this operation.
806 *
807 * @since 1.4
808 */
809 void setDefaultStratum(String stratum);
810
811 /**
812 * Return this VM's default stratum.
813 *
814 * @see #setDefaultStratum(String)
815 * @see ReferenceType#defaultStratum()
816 * @return <code>null</code> (meaning that the per-class
817 * default - {@link ReferenceType#defaultStratum()} -
818 * should be used) unless the default stratum has been
819 * set with
820 * {@link #setDefaultStratum(String)}.
821 *
822 * @since 1.4
823 */
824 String getDefaultStratum();
825
826 /**
827 * Returns the number of instances of each ReferenceType in the 'refTypes'
828 * list.
829 * Only instances that are reachable for the purposes of garbage collection
830 * are counted.
831 * <p>
832 * Not all target virtual machines support this operation.
833 * Use {@link VirtualMachine#canGetInstanceInfo()}
834 * to determine if the operation is supported.
835 *
836 * @see ReferenceType#instances(long)
837 * @see ObjectReference#referringObjects(long)
838 * @param refTypes the list of {@link ReferenceType} objects for which counts
839 * are to be obtained.
840 *
841 * @return an array of <code>long</code> containing one element for each
842 * element in the 'refTypes' list. Element i of the array contains
843 * the number of instances in the target VM of the ReferenceType at
844 * position i in the 'refTypes' list.
845 * If the 'refTypes' list is empty, a zero-length array is returned.
846 * If a ReferenceType in refTypes has been garbage collected, zero
847 * is returned for its instance count.
848 * @throws java.lang.UnsupportedOperationException if
849 * the target virtual machine does not support this
850 * operation - see
851 * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
852 * @throws NullPointerException if the 'refTypes' list is null.
853 * @since 1.6
854 */
855 long[] instanceCounts(List<? extends ReferenceType> refTypes);
856
857 /**
858 * Returns text information on the target VM and the
859 * debugger support that mirrors it. No specific format
860 * for this information is guaranteed.
861 * Typically, this string contains version information for the
862 * target VM and debugger interfaces.
863 * More precise information
864 * on VM and JDI versions is available through
865 * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion},
866 * and {@link VirtualMachineManager#minorInterfaceVersion}
867 *
868 * @return the description.
869 */
870 String description();
871
872 /**
873 * Returns the version of the Java Runtime Environment in the target
874 * VM as reported by the property <code>java.version</code>.
875 * For obtaining the JDI interface version, use
876 * {@link VirtualMachineManager#majorInterfaceVersion}
877 * and {@link VirtualMachineManager#minorInterfaceVersion}
878 *
879 * @return the target VM version.
880 */
881 String version();
882
883 /**
884 * Returns the name of the target VM as reported by the
885 * property <code>java.vm.name</code>.
886 *
887 * @return the target VM name.
888 */
889 String name();
890
891 /** All tracing is disabled. */
892 int TRACE_NONE = 0x00000000;
893 /** Tracing enabled for JDWP packets sent to target VM. */
894 int TRACE_SENDS = 0x00000001;
895 /** Tracing enabled for JDWP packets received from target VM. */
896 int TRACE_RECEIVES = 0x00000002;
897 /** Tracing enabled for internal event handling. */
898 int TRACE_EVENTS = 0x00000004;
899 /** Tracing enabled for internal managment of reference types. */
900 int TRACE_REFTYPES = 0x00000008;
901 /** Tracing enabled for internal management of object references. */
902 int TRACE_OBJREFS = 0x00000010;
903 /** All tracing is enabled. */
904 int TRACE_ALL = 0x00ffffff;
905
906 /**
907 * Traces the activities performed by the com.sun.jdi implementation.
908 * All trace information is output to System.err. The given trace
909 * flags are used to limit the output to only the information
910 * desired. The given flags are in effect and the corresponding
911 * trace will continue until the next call to
912 * this method.
913 * <p>
914 * Output is implementation dependent and trace mode may be ignored.
915 *
916 * @param traceFlags identifies which kinds of tracing to enable.
917 */
918 void setDebugTraceMode(int traceFlags);
919 }