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 } 865
