001: /*
002: * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.jdi;
027:
028: import com.sun.jdi.event.EventQueue;
029: import com.sun.jdi.request.EventRequestManager;
030:
031: import java.util.List;
032: import java.util.Map;
033:
034: /**
035: * A virtual machine targeted for debugging.
036: * More precisely, a {@link Mirror mirror} representing the
037: * composite state of the target VM.
038: * All other mirrors are associated with an instance of this
039: * interface. Access to all other mirrors is achieved
040: * directly or indirectly through an instance of this
041: * interface.
042: * Access to global VM properties and control of VM execution
043: * are supported directly by this interface.
044: * <P>
045: * Instances of this interface are created by instances of
046: * {@link com.sun.jdi.connect.Connector}. For example,
047: * an {@link com.sun.jdi.connect.AttachingConnector AttachingConnector}
048: * attaches to a target VM and returns its virtual machine mirror.
049: * A Connector will typically create a VirtualMachine by invoking
050: * the VirtualMachineManager's {@link
051: * com.sun.jdi.VirtualMachineManager#createVirtualMachine(Connection)}
052: * createVirtualMachine(Connection) method.
053: * <p>
054: * Note that a target VM launched by a launching connector is not
055: * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been
056: * received.
057: * <p>
058: * Any method on <code>VirtualMachine</code> which
059: * takes <code>VirtualMachine</code> as an parameter may throw
060: * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
061: * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
062: * available to be read from the {@link com.sun.jdi.event.EventQueue}.
063: * <p>
064: * Any method on <code>VirtualMachine</code> which
065: * takes <code>VirtualMachine</code> as an parameter may throw
066: * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
067: *
068: * @author Robert Field
069: * @author Gordon Hirsch
070: * @author James McIlree
071: * @since 1.3
072: */
073: public interface VirtualMachine extends Mirror {
074:
075: /**
076: * Returns the loaded reference types that
077: * match a given name. The name must be fully qualified
078: * (for example, java.lang.String). The returned list
079: * will contain a {@link ReferenceType} for each class
080: * or interface found with the given name. The search
081: * is confined to loaded classes only; no attempt is made
082: * to load a class of the given name.
083: * <P>
084: * The returned list will include reference types
085: * loaded at least to the point of preparation and
086: * types (like array) for which preparation is
087: * not defined.
088: *
089: * @param className the class/interface name to search for
090: * @return a list of {@link ReferenceType} objects, each
091: * mirroring a type in the target VM with the given name.
092: */
093: List<ReferenceType> classesByName(String className);
094:
095: /**
096: * Returns all loaded types. For each loaded type in the target
097: * VM a {@link ReferenceType} will be placed in the returned list.
098: * The list will include ReferenceTypes which mirror classes,
099: * interfaces, and array types.
100: * <P>
101: * The returned list will include reference types
102: * loaded at least to the point of preparation and
103: * types (like array) for which preparation is
104: * not defined.
105: *
106: * @return a list of {@link ReferenceType} objects, each mirroring
107: * a loaded type in the target VM.
108: */
109: List<ReferenceType> allClasses();
110:
111: /**
112: * All classes given are redefined according to the
113: * definitions supplied. A method in a redefined class
114: * is called 'equivalent' (to the old version of the
115: * method) if
116: * <UL>
117: * <LI>their bytecodes are the same except for indicies into
118: * the constant pool, and
119: * <LI>the referenced constants are equal.
120: * </UL>
121: * Otherwise, the new method is called 'non-equivalent'.
122: * If a redefined method has active stack frames, those active
123: * frames continue to run the bytecodes of the previous version of the
124: * method. If the new version of such a method is non-equivalent,
125: * then a method from one of these active frames is called 'obsolete' and
126: * {@link Method#isObsolete Method.isObsolete()}
127: * will return true when called on one of these methods.
128: * If resetting such a frame is desired, use
129: * {@link ThreadReference#popFrames ThreadReference.popFrames(StackFrame)}
130: * to pop the old obsolete method execution from the stack.
131: * New invocations of redefined methods will always invoke the new versions.
132: * <p>
133: * This function does not cause any initialization except
134: * that which would occur under the customary JVM semantics.
135: * In other words, redefining a class does not cause
136: * its initializers to be run. The values of preexisting
137: * static variables will remain as they were prior to the
138: * call. However, completely uninitialized (new) static
139: * variables will be assigned their default value.
140: * <p>
141: * If a redefined class has instances then all those
142: * instances will have the fields defined by the redefined
143: * class at the completion of the call. Preexisting fields
144: * will retain their previous values. Any new fields will
145: * have their default values; no instance initializers or
146: * constructors are run.
147: * <p>
148: * Threads need not be suspended.
149: * <p>
150: * No events are generated by this function.
151: * <p>
152: * All breakpoints in the redefined classes are deleted.
153: * <p>
154: * Not all target virtual machines support this operation.
155: * Use {@link #canRedefineClasses() canRedefineClasses()}
156: * to determine if the operation is supported.
157: * Use {@link #canAddMethod() canAddMethod()}
158: * to determine if the redefinition can add methods.
159: * Use {@link #canUnrestrictedlyRedefineClasses() canUnrestrictedlyRedefineClasses()}
160: * to determine if the redefinition can change the schema,
161: * delete methods, change the class hierarchy, etc.
162: *
163: * @param classToBytes A map from {@link ReferenceType}
164: * to array of byte.
165: * The bytes represent the new class definition and
166: * are in Java Virtual Machine class file format.
167: *
168: * @throws java.lang.UnsupportedOperationException if
169: * the target virtual machine does not support this
170: * operation.
171: * <UL>
172: * <LI>If {@link #canRedefineClasses() canRedefineClasses()}
173: * is false any call of this method will throw this exception.
174: * <LI>If {@link #canAddMethod() canAddMethod()} is false
175: * attempting to add a method will throw this exception.
176: * <LI>If {@link #canUnrestrictedlyRedefineClasses()
177: * canUnrestrictedlyRedefineClasses()}
178: * is false, attempting any of the following will throw
179: * this exception
180: * <UL>
181: * <LI>changing the schema (the fields)
182: * <LI>changing the hierarchy (subclasses, interfaces)
183: * <LI>deleting a method
184: * <LI>changing class modifiers
185: * <LI>changing method modifiers
186: * </UL>
187: * </UL>
188: *
189: * @throws java.lang.NoClassDefFoundError if the bytes
190: * don't correspond to the reference type (the names
191: * don't match).
192: *
193: * @throws java.lang.VerifyError if a "verifier" detects
194: * that a class, though well formed, contains an internal
195: * inconsistency or security problem.
196: *
197: * @throws java.lang.ClassFormatError if the bytes
198: * do not represent a valid class.
199: *
200: * @throws java.lang.ClassCircularityError if a
201: * circularity has been detected while initializing a class.
202: *
203: * @throws java.lang.UnsupportedClassVersionError if the
204: * major and minor version numbers in bytes
205: * are not supported by the VM.
206: *
207: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
208: *
209: * @see Method#isObsolete
210: * @see ThreadReference#popFrames
211: * @see #canRedefineClasses
212: * @see #canAddMethod
213: * @see #canUnrestrictedlyRedefineClasses
214: *
215: * @since 1.4
216: */
217: void redefineClasses(
218: 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: * Creates a {@link VoidValue}. This value
398: * can be passed to {@link ThreadReference#forceEarlyReturn}
399: * when a void method is to be exited.
400: *
401: * @return the {@link VoidValue}.
402: */
403: VoidValue mirrorOfVoid();
404:
405: /**
406: * Returns the {@link java.lang.Process} object for this
407: * virtual machine if launched
408: * by a {@link com.sun.jdi.connect.LaunchingConnector}
409: *
410: * @return the {@link java.lang.Process} object for this virtual
411: * machine, or null if it was not launched by a
412: * {@link com.sun.jdi.connect.LaunchingConnector}.
413: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
414: * -see {@link VirtualMachine#canBeModified()}.
415: */
416: Process process();
417:
418: /**
419: * Invalidates this virtual machine mirror.
420: * The communication channel to the target VM is closed, and
421: * the target VM prepares to accept another subsequent connection
422: * from this debugger or another debugger, including the
423: * following tasks:
424: * <ul>
425: * <li>All event requests are cancelled.
426: * <li>All threads suspended by {@link #suspend} or by
427: * {@link ThreadReference#suspend} are resumed as many
428: * times as necessary for them to run.
429: * <li>Garbage collection is re-enabled in all cases where it was
430: * disabled through {@link ObjectReference#disableCollection}.
431: * </ul>
432: * Any current method invocations executing in the target VM
433: * are continued after the disconnection. Upon completion of any such
434: * method invocation, the invoking thread continues from the
435: * location where it was originally stopped.
436: * <p>
437: * Resources originating in
438: * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
439: * will become invalid.
440: */
441: void dispose();
442:
443: /**
444: * Causes the mirrored VM to terminate with the given error code.
445: * All resources associated with this VirtualMachine are freed.
446: * If the mirrored VM is remote, the communication channel
447: * to it will be closed. Resources originating in
448: * this VirtualMachine (ObjectReferences, ReferenceTypes, etc.)
449: * will become invalid.
450: * <p>
451: * Threads running in the mirrored VM are abruptly terminated.
452: * A thread death exception is not thrown and
453: * finally blocks are not run.
454: *
455: * @param exitCode the exit code for the target VM. On some platforms,
456: * the exit code might be truncated, for example, to the lower order 8 bits.
457: *
458: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
459: */
460: void exit(int exitCode);
461:
462: /**
463: * Determines if the target VM supports watchpoints
464: * for field modification.
465: *
466: * @return <code>true</code> if the feature is supported,
467: * <code>false</code> otherwise.
468: */
469: boolean canWatchFieldModification();
470:
471: /**
472: * Determines if the target VM supports watchpoints
473: * for field access.
474: *
475: * @return <code>true</code> if the feature is supported,
476: * <code>false</code> otherwise.
477: */
478: boolean canWatchFieldAccess();
479:
480: /**
481: * Determines if the target VM supports the retrieval
482: * of a method's bytecodes.
483: *
484: * @return <code>true</code> if the feature is supported,
485: * <code>false</code> otherwise.
486: */
487: boolean canGetBytecodes();
488:
489: /**
490: * Determines if the target VM supports the query
491: * of the synthetic attribute of a method or field.
492: *
493: * @return <code>true</code> if the feature is supported,
494: * <code>false</code> otherwise.
495: */
496: boolean canGetSyntheticAttribute();
497:
498: /**
499: * Determines if the target VM supports the retrieval
500: * of the monitors owned by a thread.
501: *
502: * @return <code>true</code> if the feature is supported,
503: * <code>false</code> otherwise.
504: */
505: boolean canGetOwnedMonitorInfo();
506:
507: /**
508: * Determines if the target VM supports the retrieval
509: * of the monitor for which a thread is currently waiting.
510: *
511: * @return <code>true</code> if the feature is supported,
512: * <code>false</code> otherwise.
513: */
514: boolean canGetCurrentContendedMonitor();
515:
516: /**
517: * Determines if the target VM supports the retrieval
518: * of the monitor information for an object.
519: *
520: * @return <code>true</code> if the feature is supported,
521: * <code>false</code> otherwise.
522: */
523: boolean canGetMonitorInfo();
524:
525: /**
526: * Determines if the target VM supports filtering
527: * events by specific instance object. For example,
528: * see {@link com.sun.jdi.request.BreakpointRequest#addInstanceFilter}.
529: *
530: * @return <code>true</code> if the feature is supported,
531: * <code>false</code> otherwise.
532: */
533: boolean canUseInstanceFilters();
534:
535: /**
536: * Determines if the target VM supports any level
537: * of class redefinition.
538: * @see #redefineClasses
539: *
540: * @return <code>true</code> if the feature is supported,
541: * <code>false</code> otherwise.
542: *
543: * @since 1.4
544: */
545: boolean canRedefineClasses();
546:
547: /**
548: * Determines if the target VM supports the addition
549: * of methods when performing class redefinition.
550: * @see #redefineClasses
551: *
552: * @return <code>true</code> if the feature is supported,
553: * <code>false</code> otherwise.
554: *
555: * @since 1.4
556: */
557: boolean canAddMethod();
558:
559: /**
560: * Determines if the target VM supports unrestricted
561: * changes when performing class redefinition.
562: * @see #redefineClasses
563: *
564: * @return <code>true</code> if the feature is supported,
565: * <code>false</code> otherwise.
566: *
567: * @since 1.4
568: */
569: boolean canUnrestrictedlyRedefineClasses();
570:
571: /**
572: * Determines if the target VM supports popping
573: * frames of a threads stack.
574: * @see ThreadReference#popFrames
575: *
576: * @return <code>true</code> if the feature is supported,
577: * <code>false</code> otherwise.
578: *
579: * @since 1.4
580: */
581: boolean canPopFrames();
582:
583: /**
584: * Determines if the target VM supports getting
585: * the source debug extension.
586: * @see ReferenceType#sourceDebugExtension
587: *
588: * @return <code>true</code> if the feature is supported,
589: * <code>false</code> otherwise.
590: *
591: * @since 1.4
592: */
593: boolean canGetSourceDebugExtension();
594:
595: /**
596: * Determines if the target VM supports the creation of
597: * {@link com.sun.jdi.request.VMDeathRequest}s.
598: * @see com.sun.jdi.request.EventRequestManager#createVMDeathRequest
599: *
600: * @return <code>true</code> if the feature is supported,
601: * <code>false</code> otherwise.
602: *
603: * @since 1.4
604: */
605: boolean canRequestVMDeathEvent();
606:
607: /**
608: * Determines if the target VM supports the inclusion of return values
609: * in
610: * {@link com.sun.jdi.event.MethodExitEvent}s.
611: * @see com.sun.jdi.request.EventRequestManager#createMethodExitRequest
612: *
613: * @return <code>true</code> if the feature is supported,
614: * <code>false</code> otherwise.
615: *
616: * @since 1.6
617: */
618: boolean canGetMethodReturnValues();
619:
620: /**
621: * Determines if the target VM supports the accessing of class instances,
622: * instance counts, and referring objects.
623: *
624: * @see #instanceCounts
625: * @see ReferenceType#instances(long)
626: * @see ObjectReference#referringObjects(long)
627: *
628: * @return <code>true</code> if the feature is supported,
629: * <code>false</code> otherwise.
630: *
631: * @since 1.6
632: */
633: boolean canGetInstanceInfo();
634:
635: /**
636: * Determines if the target VM supports the filtering of
637: * class prepare events by source name.
638: *
639: * see {@link com.sun.jdi.request.ClassPrepareRequest#addSourceNameFilter}.
640: * @return <code>true</code> if the feature is supported,
641: * <code>false</code> otherwise.
642: *
643: * @since 1.6
644: */
645: boolean canUseSourceNameFilters();
646:
647: /**
648: * Determines if the target VM supports the forcing of a method to
649: * return early.
650: *
651: * @see ThreadReference#forceEarlyReturn(Value)
652: *
653: * @return <code>true</code> if the feature is supported,
654: * <code>false</code> otherwise.
655: *
656: * @since 1.6
657: */
658: boolean canForceEarlyReturn();
659:
660: /**
661: * Determines if the target VM is a read-only VM. If a method which
662: * would modify the state of the VM is called on a read-only VM,
663: * then {@link VMCannotBeModifiedException} is thrown.
664: *
665: * @return <code>true</code> if the feature is supported,
666: * <code>false</code> otherwise.
667: *
668: * @since 1.5
669: */
670:
671: boolean canBeModified();
672:
673: /**
674: * Determines if the target VM supports the creation of
675: * {@link com.sun.jdi.request.MonitorContendedEnterRequest}s.
676: * {@link com.sun.jdi.request.MonitorContendedEnteredRequest}s.
677: * {@link com.sun.jdi.request.MonitorWaitRequest}s.
678: * {@link com.sun.jdi.request.MonitorWaitedRequest}s.
679: * @see com.sun.jdi.request.EventRequestManager#createMonitorContendedEnterRequest
680: * @see com.sun.jdi.request.EventRequestManager#createMonitorContendedEnteredRequest
681: * @see com.sun.jdi.request.EventRequestManager#createMonitorWaitRequest
682: * @see com.sun.jdi.request.EventRequestManager#createMonitorWaitedRequest
683: *
684: * @return <code>true</code> if the feature is supported,
685: * <code>false</code> otherwise.
686: *
687: * @since 1.6
688: */
689:
690: boolean canRequestMonitorEvents();
691:
692: /**
693: * Determines if the target VM supports getting which
694: * frame has acquired a monitor.
695: * @see com.sun.jdi.ThreadReference#ownedMonitorsAndFrames
696: *
697: * @return <code>true</code> if the feature is supported,
698: * <code>false</code> otherwise.
699: *
700: * @since 1.6
701: */
702:
703: boolean canGetMonitorFrameInfo();
704:
705: /**
706: * Determines if the target VM supports reading class file
707: * major and minor versions.
708: *
709: * @see ReferenceType#majorVersion()
710: * @see ReferenceType#minorVersion()
711: *
712: * @return <code>true</code> if the feature is supported,
713: * <code>false</code> otherwise.
714: *
715: * @since 1.6
716: */
717: boolean canGetClassFileVersion();
718:
719: /**
720: * Determines if the target VM supports getting constant pool
721: * information of a class.
722: *
723: * @see ReferenceType#constantPoolCount()
724: * @see ReferenceType#constantPool()
725: *
726: * @return <code>true</code> if the feature is supported,
727: * <code>false</code> otherwise.
728: *
729: * @since 1.6
730: */
731: boolean canGetConstantPool();
732:
733: /**
734: * Set this VM's default stratum (see {@link Location} for a
735: * discussion of strata). Overrides the per-class default set
736: * in the class file.
737: * <P>
738: * Affects location queries (such as,
739: * {@link Location#sourceName()})
740: * and the line boundaries used in
741: * single stepping.
742: *
743: * @param stratum the stratum to set as VM default,
744: * or null to use per-class defaults.
745: *
746: * @throws java.lang.UnsupportedOperationException if the
747: * target virtual machine does not support this operation.
748: *
749: * @since 1.4
750: */
751: void setDefaultStratum(String stratum);
752:
753: /**
754: * Return this VM's default stratum.
755: *
756: * @see #setDefaultStratum(String)
757: * @see ReferenceType#defaultStratum()
758: * @return <code>null</code> (meaning that the per-class
759: * default - {@link ReferenceType#defaultStratum()} -
760: * should be used) unless the default stratum has been
761: * set with
762: * {@link #setDefaultStratum(String)}.
763: *
764: * @since 1.4
765: */
766: String getDefaultStratum();
767:
768: /**
769: * Returns the number of instances of each ReferenceType in the 'refTypes'
770: * list.
771: * Only instances that are reachable for the purposes of garbage collection
772: * are counted.
773: * <p>
774: * Not all target virtual machines support this operation.
775: * Use {@link VirtualMachine#canGetInstanceInfo()}
776: * to determine if the operation is supported.
777: *
778: * @see ReferenceType#instances(long)
779: * @see ObjectReference#referringObjects(long)
780: * @param refTypes the list of {@link ReferenceType} objects for which counts
781: * are to be obtained.
782: *
783: * @return an array of <code>long</code> containing one element for each
784: * element in the 'refTypes' list. Element i of the array contains
785: * the number of instances in the target VM of the ReferenceType at
786: * position i in the 'refTypes' list.
787: * If the 'refTypes' list is empty, a zero-length array is returned.
788: * If a ReferenceType in refTypes has been garbage collected, zero
789: * is returned for its instance count.
790: * @throws java.lang.UnsupportedOperationException if
791: * the target virtual machine does not support this
792: * operation - see
793: * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
794: * @throws NullPointerException if the 'refTypes' list is null.
795: * @since 1.6
796: */
797: long[] instanceCounts(List<? extends ReferenceType> refTypes);
798:
799: /**
800: * Returns text information on the target VM and the
801: * debugger support that mirrors it. No specific format
802: * for this information is guaranteed.
803: * Typically, this string contains version information for the
804: * target VM and debugger interfaces.
805: * More precise information
806: * on VM and JDI versions is available through
807: * {@link #version}, {@link VirtualMachineManager#majorInterfaceVersion},
808: * and {@link VirtualMachineManager#minorInterfaceVersion}
809: *
810: * @return the description.
811: */
812: String description();
813:
814: /**
815: * Returns the version of the Java Runtime Environment in the target
816: * VM as reported by the property <code>java.version</code>.
817: * For obtaining the JDI interface version, use
818: * {@link VirtualMachineManager#majorInterfaceVersion}
819: * and {@link VirtualMachineManager#minorInterfaceVersion}
820: *
821: * @return the target VM version.
822: */
823: String version();
824:
825: /**
826: * Returns the name of the target VM as reported by the
827: * property <code>java.vm.name</code>.
828: *
829: * @return the target VM name.
830: */
831: String name();
832:
833: /** All tracing is disabled. */
834: int TRACE_NONE = 0x00000000;
835: /** Tracing enabled for JDWP packets sent to target VM. */
836: int TRACE_SENDS = 0x00000001;
837: /** Tracing enabled for JDWP packets received from target VM. */
838: int TRACE_RECEIVES = 0x00000002;
839: /** Tracing enabled for internal event handling. */
840: int TRACE_EVENTS = 0x00000004;
841: /** Tracing enabled for internal managment of reference types. */
842: int TRACE_REFTYPES = 0x00000008;
843: /** Tracing enabled for internal management of object references. */
844: int TRACE_OBJREFS = 0x00000010;
845: /** All tracing is enabled. */
846: int TRACE_ALL = 0x00ffffff;
847:
848: /**
849: * Traces the activities performed by the com.sun.jdi implementation.
850: * All trace information is output to System.err. The given trace
851: * flags are used to limit the output to only the information
852: * desired. The given flags are in effect and the corresponding
853: * trace will continue until the next call to
854: * this method.
855: * <p>
856: * Output is implementation dependent and trace mode may be ignored.
857: *
858: * @param traceFlags identifies which kinds of tracing to enable.
859: */
860: void setDebugTraceMode(int traceFlags);
861: }
|