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