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