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