1 <html> 2 <head> 3 <title> 4 JavaScript interface to Hotspot Serviceability Agent 5 </title> 6 </head> 7 <body> 8 <h1>JavaScript interface to Hotspot Serviceability Agent</h1> 9 10 <p> 11 Serviceability Agent (SA) provides Java API and tools to diagnose HotSpot Virtual Machine and 12 Java apps running on it. SA is a snapshot debugger -- can be used to observe state of a frozen java process or java core dump. 13 </p> 14 15 <h2>Existing SA APIs</h2> 16 <p> 17 There are two application programmer interfaces (APIs) for SA: 18 <dl> 19 <dt>1. Private java API 20 </dt> 21 <dd> 22 This tries to mimic hotspot VM's internal C++ classes and methods. Because VM data structures 23 are a moving target, this API can never be 'stable'! Besides, to use SA's private API knowledge of 24 HotSpot code base is essential. 25 </dd> 26 <dt>2. SA-JDI -- Java Debugger Interface read-only subset API 27 </dt> 28 <dd> 29 This is read-only subset of JDI (Java Debugger Interface) 30 This is a standardized interface to get java level state of a java process or java core dump. While this 31 interface is useful, this misses parts of java level state from target process or core such as 32 <ul> 33 <li>heap walking interface -- only objects traceable to static variables (of classes) and local 34 variables of stack frames can be accessed. 35 <li>re-constructing .class from debuggee are missing. 36 <li>re-constructing object mirrors for Java objects of the debuggee. 37 </ul> 38 </dd> 39 </dl> 40 </p> 41 42 <h2>SA Scripting interface</h2> 43 44 <p> 45 Traditionally, platform debuggers such as dbx, gdb and Solaris mdb (Module Debugger), provide a scripting 46 language interface. Scripting language interface provides easy-to-use, dynamically typed 47 interface to access data structures from debuggee. dbx and mdb even allow user to write 48 C/C++ modules to extend the scripting language commands. 49 </p> 50 51 <p> 52 SA provides SOQL - Simple Object Query Language -- a SQL-like query language to access 53 Java heap as an object database. SA's main GUI (HSDB) also exposes scripting interface of underlying debugger such as dbx, windbg. 54 But to use this interface, user has to learn scripting interface of multiple debugger back-ends such as dbx, windbg. 55 And these scripting interfaces are 'raw' in the sense that no java state is exposed -- only C/C++ state of VM is exposed. 56 Higher level SA services are not available through scripting interface. 57 </p> 58 59 <p> 60 <b>jsdb -- JavaScript Debugger</b> attempts to provide JavaScript interface to SA. 61 jsdb provides 62 63 <ul> 64 <li>high-level hotspot (and SA) independent scripting interface 65 <li>low-level SA-aware scripting interface. 66 </ul> 67 </p> 68 69 <h2>High level interface (Java State)</h2> 70 71 <b>jsdb</b> is a command line <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">JavaScript</a> shell based on 72 <a href="http://www.mozilla.org/rhino/">Mozilla's Rhino JavaScript Engine</a>. 73 This command line utility attaches to Java process or core file or remote debug server and waits for user input. 74 This shell supports the following global functions and objects in addition to the standard JavaScript functions and 75 objects: 76 77 <h3>jdsb globals</h3> 78 79 <table border="1"> 80 <tr> 81 <th>Function/Variable</th> 82 <th>Description</th> 83 </tr> 84 <tr> 85 <td> 86 address(jobject) 87 </td> 88 <td> 89 function that returns the address of the Java object as a string 90 </td> 91 </tr> 92 <td> 93 classof(jobject) 94 </td> 95 <td> 96 function that returns the JavaScript object that represents class object of the Java object 97 </td> 98 </tr> 99 <td> 100 dumpClass(jclass,[dir]) 101 </td> 102 <td> 103 function that writes .class for the given Java Class. Optionally (second arg) accepts the directory where the 104 .class has to be written. 105 </td> 106 </tr> 107 <td> 108 help() 109 </td> 110 <td> 111 function that prints help message for global functions and objects 112 </td> 113 </tr> 114 <tr> 115 <td> 116 identityHash(jobject) 117 </td> 118 <td> 119 function that returns the identity hashCode of the Java object 120 </td> 121 </tr> 122 <tr> 123 <td> 124 mirror(jobject) 125 </td> 126 <td> 127 function that returns a local mirror of the Java object. 128 </td> 129 </tr> 130 <tr> 131 <td> 132 load([file1, file2,...]) 133 </td> 134 <td> 135 function that loads zero or more JavaScript file(s). With no arguments, reads <stdin> for 136 JavaScript code. 137 </td> 138 </tr> 139 <tr> 140 <td> 141 object(string) 142 </td> 143 <td> 144 function that converts a string address into Java object 145 </td> 146 </tr> 147 <tr> 148 <td> 149 owner(jobject) 150 </td> 151 <td> 152 function that returns the owner thread of this monitor or null 153 </td> 154 </tr> 155 <tr> 156 <td> 157 sizeof(jobject) 158 </td> 159 <td> 160 function that returns the size of Java object in bytes 161 </td> 162 </tr> 163 <tr> 164 <td> 165 staticof(jclass, field) 166 </td> 167 <td> 168 function that returns the value of given field of the given Java class 169 </td> 170 </tr> 171 <tr> 172 <td> 173 print(expr1, expr2,...) 174 </td> 175 <td> 176 function that prints zero or more JavaScript expressions after converting those as strings 177 </td> 178 </tr> 179 <tr> 180 <td> 181 println(expr1, expr2..) 182 </td> 183 <td> 184 function that same as print, but prints a newline at the end 185 </td> 186 </tr> 187 <tr> 188 <td> 189 read([prompt]) 190 </td> 191 <td> 192 function that reads a single line from standard input 193 </td> 194 </tr> 195 <tr> 196 <td> 197 quit() 198 </td> 199 <td> 200 function that quits the interactive load call as well as the shell 201 </td> 202 </tr> 203 <tr> 204 <td> 205 jvm 206 </td> 207 <td> 208 variable -- a JavaScript object that represents the target jvm that is being debugged 209 </td> 210 </tr> 211 </table> 212 213 <h3>jvm object</h3> 214 215 <p> 216 jvm object supports the following read-only properties. 217 </p> 218 219 <table border="1"> 220 <tr> 221 <th> 222 Property name 223 </th> 224 <th> 225 Description 226 </th> 227 </tr> 228 <tr> 229 <td> 230 threads 231 </td> 232 <td> 233 array of Java threads from the debuggee 234 </td> 235 </tr> 236 <tr> 237 <td> 238 heap 239 </td> 240 <td> 241 object representing the heap of the debuggee 242 </td> 243 </tr> 244 <tr> 245 <td> 246 type 247 </td> 248 <td> 249 string value that is either "Server" or "Client" or "Core" -- the flavour of debuggee VM 250 </td> 251 </tr> 252 <tr> 253 <td> 254 bootClassPath 255 </td> 256 <td> 257 string value of bootclasspath of the debuggee 258 </td> 259 </tr> 260 <tr> 261 <td> 262 cpu 263 </td> 264 <td> 265 string value of cpu on which the debuggee runs/ran 266 </td> 267 </tr> 268 <tr> 269 <td> 270 sysProps 271 </td> 272 <td> 273 name-value pairs (JavaScript associative array) of Java System properties of the debuggee 274 </td> 275 </tr> 276 <tr> 277 <td> 278 addressSize 279 </td> 280 <td> 281 int value -- 32 for 32 bit debuggee, 64 for 64 bit debuggee 282 </td> 283 </tr> 284 <tr> 285 <td> 286 os 287 </td> 288 <td> 289 string value of OS on which the debuggee runs/ran 290 </td> 291 </tr> 292 <tr> 293 <td> 294 buildInfo 295 </td> 296 <td> 297 internal build info string from debuggee 298 </td> 299 </tr> 300 <tr> 301 <td> 302 flags 303 </td> 304 <td> 305 name-value pairs (JavaScript associative array) of JVM command line flags of the debuggee 306 </td> 307 </tr> 308 <tr> 309 <td> 310 classPath 311 </td> 312 <td> 313 string value of classpath of the debuggee 314 </td> 315 </tr> 316 <tr> 317 <td> 318 userDir 319 </td> 320 <td> 321 string value of user.dir System property of the debuggee 322 </td> 323 </tr> 324 </table> 325 326 <h3>heap object</h3> 327 328 <p> 329 heap object represents Java heap of the debuggee VM 330 </p> 331 <table border="1"> 332 <tr> 333 <th> 334 Function or property name 335 </th> 336 <th> 337 Description 338 </th> 339 </tr> 340 <tr> 341 <td> 342 capacity 343 </td> 344 <td> 345 byte size of capacity of the heap 346 </td> 347 </tr> 348 <tr> 349 <td> 350 used 351 </td> 352 <td> 353 byte size of used portion (of live objects) of the heap 354 </td> 355 </tr> 356 <tr> 357 <td> 358 forEachObject(func, [class], [include subtypes -- true|false]) 359 </td> 360 <td> 361 This function accepts a callback function 'func' and optionally class name and boolean arguments. 362 This function calls the callback for each Java object in the debuggee's heap. The optional class 363 argument may be used to receive objects of given class only. The third arguments specifies whether 364 to include objects of subtype of given class [or interface] or not. The default value of class is "java.lang.Object" 365 and and that of the third argument is true. i.e., by default all objects are included. 366 </td> 367 </tr> 368 <tr> 369 <td> 370 forEachClass(func, [initiating loader -- true|false]) 371 </td> 372 <td> 373 This function accepts a callback function 'func'. This function iterates through the classes of the debuggee and calls the 374 callback for each class. The second parameter tells whether to pass initiating loader to the iterator callback or not. 375 </td> 376 </tr> 377 </table> 378 379 <h3>Accessing Java objects and arrays in script</h3> 380 381 <p> 382 From a given Java object, we can access all fields of the Java object by usual '.' operator. i.e., if you got a Java object 383 called 'o' of type java.lang.Thread from debuggee, you can access 'stackSize' field by o.stackSize syntax. Similarly, length of Java array 384 objects can be accessed by length property. And array indexing follows usual syntax. i.e., n'th element of array 'a' is 385 accessed by a[n]. 386 </p> 387 388 <h3>jvm.threads array</h3> 389 390 <p> 391 This is a JavaScript array of Java threads of the debuggee. As usual, 'length' property tells the number of threads and individual 392 threads may be accessed by index operator -- i.e, jvm.threads[0] returns the first thread. 393 </p> 394 395 <h3>thread object</h3> 396 397 398 <p> 399 In addition to the fields of java.lang.Thread (or subclass) fields, thread objects have two additional properties. 400 401 <ul> 402 <li>frames -- array of stack frame objects 403 <li>monitors -- array of monitor objects owned by the thread 404 </ul> 405 406 </p> 407 408 <h3>stack frame object</h3> 409 410 <table border="1"> 411 <tr> 412 <th> 413 Property name 414 </th> 415 <th> 416 Description 417 </th> 418 </tr> 419 <td> 420 thisObject 421 </td> 422 <td> 423 Object representing 'this' of the current frame [will be null for static methods] 424 </td> 425 </tr> 426 <tr> 427 <td> 428 locals 429 </td> 430 <td> 431 name-value pairs of local variables [JavaScript associative array] 432 </td> 433 </tr> 434 <tr> 435 <td> 436 line 437 </td> 438 <td> 439 Java source line number at which the frame is executing 440 </td> 441 </tr> 442 <tr> 443 <td> 444 bci 445 </td> 446 <td> 447 byte code index of the bytecode that the frame is executing 448 </td> 449 </tr> 450 <tr> 451 <td> 452 thread 453 </td> 454 <td> 455 thread to which this frame belongs 456 </td> 457 </tr> 458 <tr> 459 <td> 460 method 461 </td> 462 <td> 463 Java method that the frame is executing 464 </td> 465 </tr> 466 </table> 467 468 <h3>method object</h3> 469 470 <p> 471 method object represents a Java method of debuggee 472 </p> 473 474 <table border="1"> 475 <tr> 476 <th> 477 Property name 478 </th> 479 <th> 480 Description 481 </th> 482 </tr> 483 <tr> 484 <td> 485 isStatic 486 </td> 487 <td> 488 boolean - true for static methods and false for non-static methods 489 </td> 490 </tr> 491 492 <tr> 493 <td> 494 isSynchronized 495 </td> 496 <td> 497 boolean - true for synchronized methods and false for non-synchronized methods 498 </td> 499 </tr> 500 501 <tr> 502 <td> 503 isNative 504 </td> 505 <td> 506 boolean - true for native methods and false for non-native methods 507 </td> 508 </tr> 509 510 <tr> 511 <td> 512 isProtected 513 </td> 514 <td> 515 boolean - true for protected methods and false for non-protected methods 516 </td> 517 </tr> 518 519 <tr> 520 <td> 521 isPrivate 522 </td> 523 <td> 524 boolean - true for private methods and false for non-private methods 525 </td> 526 </tr> 527 528 <tr> 529 <td> 530 isSynthetic 531 </td> 532 <td> 533 boolean - true for Javac generated synthetic methods and false for non-synthetic methods 534 </td> 535 </tr> 536 537 <tr> 538 <td> 539 isPackagePrivate 540 </td> 541 <td> 542 boolean - true for package-private methods and false for non-package-private methods 543 </td> 544 </tr> 545 546 <tr> 547 <td> 548 isPublic 549 </td> 550 <td> 551 boolean - true for public methods and false for non-public methods 552 </td> 553 </tr> 554 555 <tr> 556 <td> 557 holder 558 </td> 559 <td> 560 an object that represents Class that contains this method 561 </td> 562 </tr> 563 564 <tr> 565 <td> 566 signature 567 </td> 568 <td> 569 string -- signature of this method 570 </td> 571 </tr> 572 573 <tr> 574 <td> 575 isObsolete 576 </td> 577 <td> 578 boolean - true for obsolete (hotswapped) methods and false for non-obsolete methods 579 </td> 580 </tr> 581 582 <tr> 583 <td> 584 isStrict 585 </td> 586 <td> 587 boolean - true for strictfp methods and false for non-strictfp methods 588 </td> 589 </tr> 590 591 <tr> 592 <td> 593 isFinal 594 </td> 595 <td> 596 boolean - true for final methods and false for non-final methods 597 </td> 598 </tr> 599 600 <tr> 601 <td> 602 name 603 </td> 604 <td> 605 string - name of this method 606 </td> 607 </tr> 608 </table> 609 610 <h3>class object</h3> 611 612 <p> 613 A class object represents loaded Java class in debuggee VM. This represents java.lang.Class instance in the debuggee. 614 This is type of return value of classof global function. Also, method.holder property and field.holder are 615 of this type. 616 </p> 617 618 <table border="1"> 619 <tr> 620 <th> 621 Property name 622 </th> 623 <th> 624 Description 625 </th> 626 </tr> 627 628 <tr> 629 <td> 630 name 631 </td> 632 <td> 633 name of this class 634 </td> 635 </tr> 636 637 <tr> 638 <td> 639 superClass 640 </td> 641 <td> 642 class object representing super class of this class 643 </td> 644 </tr> 645 646 <tr> 647 <td> 648 isArrayClass 649 </td> 650 <td> 651 boolean -- is the current class an array class? 652 </td> 653 </tr> 654 655 <tr> 656 <td> 657 isStatic 658 </td> 659 <td> 660 boolean -- is the current class static or not 661 </td> 662 </tr> 663 664 <tr> 665 <td> 666 isInterface 667 </td> 668 <td> 669 boolean -- is the current class an interface 670 </td> 671 </tr> 672 673 <tr> 674 <td> 675 isAbstract 676 </td> 677 <td> 678 boolean -- is the current class abstract or not 679 </td> 680 </tr> 681 682 <tr> 683 <td> 684 isProtected 685 </td> 686 <td> 687 boolean -- is the current class protected or not 688 </td> 689 </tr> 690 691 <tr> 692 <td> 693 isPrivate 694 </td> 695 <td> 696 boolean -- is the current class private or not 697 </td> 698 </tr> 699 700 <tr> 701 <td> 702 isPackagePrivate 703 </td> 704 <td> 705 boolean -- is the current class package private or not 706 </td> 707 </tr> 708 709 <tr> 710 <td> 711 isSynthetic 712 </td> 713 <td> 714 boolean -- is the current class synthetic or not 715 </td> 716 </tr> 717 718 <tr> 719 <td> 720 classLoader 721 </td> 722 <td> 723 object that represents ClassLoader object that loaded the current class 724 </td> 725 </tr> 726 727 728 <tr> 729 <td> 730 fields 731 </td> 732 <td> 733 array of static and instance fields of the current class 734 </td> 735 </tr> 736 737 <tr> 738 <td> 739 protectionDomain 740 </td> 741 <td> 742 protection domain to which current class belongs 743 </td> 744 </tr> 745 746 <tr> 747 <td> 748 isPublic 749 </td> 750 <td> 751 boolean -- is the current class public or not 752 </td> 753 </tr> 754 755 <tr> 756 <td> 757 signers 758 </td> 759 <td> 760 array of signers for current class 761 </td> 762 </tr> 763 764 <tr> 765 <td> 766 sourceFile 767 </td> 768 <td> 769 string -- name of the source file for current class 770 </td> 771 </tr> 772 773 <tr> 774 <td> 775 interfaces 776 </td> 777 <td> 778 array -- interfaces implemented by current class 779 </td> 780 </tr> 781 782 <tr> 783 <td> 784 isStrict 785 </td> 786 <td> 787 boolean -- is the current class strictfp or not 788 </td> 789 </tr> 790 791 <tr> 792 <td> 793 methods 794 </td> 795 <td> 796 array of methods (static and instance) of the current class 797 </td> 798 </tr> 799 800 801 <tr> 802 <td> 803 isFinal 804 </td> 805 <td> 806 boolean -- is the current class final or not 807 </td> 808 </tr> 809 810 <tr> 811 <td> 812 statics 813 </td> 814 <td> 815 name-value pairs (JavaScript associate array) of static fields of the current class 816 </td> 817 </tr> 818 </table> 819 820 <h3>field object</h3> 821 <p> 822 field represents a static or instance field of some class in debuggee 823 </p> 824 825 <table border="1"> 826 <tr> 827 <th> 828 Property name 829 </th> 830 <th> 831 Description 832 </th> 833 </tr> 834 835 <tr> 836 <td> 837 isStatic 838 </td> 839 <td> 840 boolean -- is this field a static field? 841 </td> 842 </tr> 843 844 <tr> 845 <td> 846 holder 847 </td> 848 <td> 849 class that owns this field 850 </td> 851 </tr> 852 853 <tr> 854 <td> 855 signature 856 </td> 857 <td> 858 string signature of this field 859 </td> 860 </tr> 861 862 <tr> 863 <td> 864 isProtected 865 </td> 866 <td> 867 boolean - is this field a protected field or not? 868 </td> 869 </tr> 870 871 <tr> 872 <td> 873 isPrivate 874 </td> 875 <td> 876 boolean - is this field a private field or not? 877 </td> 878 </tr> 879 880 <tr> 881 <td> 882 isSynthetic 883 </td> 884 <td> 885 boolean - is this javac generated synthetic field or not? 886 </td> 887 </tr> 888 889 <tr> 890 <td> 891 isPackagePrivate 892 </td> 893 <td> 894 boolean - is this field a package private field or not? 895 </td> 896 </tr> 897 898 <tr> 899 <td> 900 isTransient 901 </td> 902 <td> 903 boolean - is this field a transient field or not? 904 </td> 905 </tr> 906 907 <tr> 908 <td> 909 isFinal 910 </td> 911 <td> 912 boolean - is this field final or not? 913 </td> 914 </tr> 915 916 <tr> 917 <td> 918 name 919 </td> 920 <td> 921 string - name of this field 922 </td> 923 </tr> 924 925 <tr> 926 <td> 927 isPublic 928 </td> 929 <td> 930 boolean - is this field public or not? 931 </td> 932 </tr> 933 </table> 934 935 <h3>Initialization Script</h3> 936 <p> 937 jsdb engine looks for initialization script file named <b>jsdb.js</b> in user's home directory. If found, it loads just after attaching to debuggee but before printing prompt for user's input. User can assume that s/he can access debuggee VM 938 state during initialization script. 939 </p> 940 941 <h3>Sample scripts</h3> 942 943 Semantics and knowledge of application classes (for eg. AppServer's classes) would be needed to create app specific 944 scripts. The following script samples are app-independent and provide a flavour of kind of scripts that can be written. 945 946 <h4>Script to print system properties of JVM</h4> 947 948 <pre> 949 <code> 950 jvm.sysProps.toString() 951 </code> 952 </pre> 953 954 <h4>Script to print JVM command line flags</h4> 955 <pre> 956 <code> 957 jvm.flags.toString() 958 </code> 959 </pre> 960 961 962 <h4>Script to print class-wise histogram of objects</h4> 963 964 <pre> 965 <code> 966 967 // associate array to hold histogram 968 var histo; 969 function func(obj) { 970 var classname = classof(obj).name; 971 if (histo[classname] == undefined) { 972 // first time we are visiting this class type 973 histo[classname] = 1; 974 } else { 975 histo[classname]++; 976 } 977 } 978 979 // iterate through java heap calling 'func' for each object 980 jvm.heap.forEachObject(func); 981 982 // print the histogram 983 for (i in histo) { 984 println('number of instances of ', i, ' = ', histo[i]); 985 } 986 987 </code> 988 </pre> 989 990 <h4>Script to print stack trace of all Java threads</h4> 991 992 <pre> 993 <code> 994 995 function printStackTrace(t) { 996 println(t.name); 997 println(''); 998 for (i in t.frames) { 999 println(t.frames[i]); 1000 } 1001 println(''); 1002 } 1003 1004 // walk through the list of threads and call printStackTrace 1005 // for each thread 1006 for (o in jvm.threads) { 1007 printStackTrace(jvm.threads[o]); 1008 } 1009 1010 1011 </code> 1012 </pre> 1013 1014 1015 <h4>Script to re-construct .class files for all non-bootstrap classes</h4> 1016 1017 <pre> 1018 <code> 1019 1020 function dump(cl) { 1021 if (!cl.isArrayClass && cl.classLoader != null) { 1022 // not an array class and a non-bootstrap class 1023 // create .class files in e:\tmp dir 1024 dumpClass(cl, "e:\\tmp); 1025 } else { 1026 println("skipping bootstrap class ", cl.name); 1027 } 1028 } 1029 1030 // walk thru heap and call callback for each java.lang.Class instance 1031 jvm.heap.forEachObject(dump, "java.lang.Class"); 1032 </code> 1033 </pre> 1034 1035 <h4>Script to print paths of all java.io.File's currently accessed</h4> 1036 1037 <pre> 1038 <code> 1039 1040 function printFile(f) { 1041 // construct a mirror java.io.File here and 1042 // print absolute path here 1043 println(mirror(f).getAbsolutePath()); 1044 } 1045 1046 jvm.heap.forEachObject(printFile, "java.io.File"); 1047 1048 </code> 1049 </pre> 1050 1051 <h4>Script to print static fields of java.lang.Thread class</h4> 1052 <pre> 1053 <code> 1054 1055 var threadClass = classof("java.lang.Thread"); 1056 for (i in threadClass.statics) { 1057 println(i, '=', threadClass.statics[i]); 1058 } 1059 1060 </code> 1061 </pre> 1062 1063 <h3>Low level interface (VM State)</h3> 1064 1065 <p> 1066 Low level jsdb interface works by <a href="http://www.mozilla.org/rhino/ScriptingJava.html">JavaScript-to-Java (previously known as "LiveConnect") 1067 interface</a> provided by Rhino JavaScript engine. 1068 </p> 1069 1070 <h2>sapkg object</h2> 1071 <p> 1072 This object provides short names for SA package names. For eg. instead of writing 1073 Packages.sun.jvm.hotspot.memory, we can write sapkg.memory. 1074 </p> 1075 1076 <h2>sa object</h2> 1077 <p> 1078 This object contains all SA singleton objects such as VM, Universe, SymbolTable, 1079 SystemDictionary, ObjectHeap, CollectedHeap, Debugger, CDebugger (if available), 1080 Interpreter, TypeDataBase and Threads. For eg. to access SymbolTable of Java debuggee, 1081 we can use sa.symbolTable. User can execute the following code to get fields of this object. 1082 </p> 1083 <pre> 1084 <code> 1085 for (i in sa) { 1086 println(i); 1087 } 1088 </code> 1089 </pre> 1090 1091 <h4>Heap Iterators</h4> 1092 <dl> 1093 <dt>forEachOop(callback)</dt> 1094 <dd>calls a callback function for each Oop in Java heap</dd> 1095 <dt>forEachOopOfKlass(callback, klass, [includeSubtypes])</dt> 1096 <dd>calls a callback function for each Oop of a give Klass type 1097 Optinally, third argument can specify whether to include subtype Oops 1098 or not. 1099 </dd> 1100 </dl> 1101 1102 <h4>System Dictionary Access</h4> 1103 <dl> 1104 <dt>forEachKlass(callback)</dt> 1105 <dd>calls a callback function for each Klass in Java heap</dd> 1106 <dt>forEachKlassAndLoader(callback)</dt> 1107 <dd> 1108 calls callback with Klass and initiating loader (Oop) for System dictionary 1109 entry. 1110 </dd> 1111 <dt>findInstanceKlass(name)</dt> 1112 <dd> 1113 finds the first instance klass with given name from System dictionary 1114 </dd> 1115 </dl> 1116 1117 <h4>Thread, Frame Iterators</h4> 1118 <dl> 1119 <dt>forEachJavaThread(callback)</dt> 1120 <dd>calls callback for each Java Thread</dd> 1121 <dt>forEachFrame(javaThread, callback)</dt> 1122 <dd>calls callback for each Frame of a given JavaThread</dd> 1123 <dt>forEachVFrame(javaThread, callback)</dt> 1124 <dd>calls callback for each JavaVFrame of a given JavaThread</dd> 1125 <dt>forEachThread(callback)</dt> 1126 <dd>calls callback for each (native) ThreadProxy (obtained by CDebugger.getThreadList) 1127 </dd> 1128 <dt>forEachCFrame(threadProxy, callback)</dt> 1129 <dd> 1130 calls callback for each CFrame of a given ThreadProxy object 1131 </dd> 1132 </dl> 1133 1134 <h4>Code blobs, Interpreter codelets</h4> 1135 <dl> 1136 <dt>forEachCodeBlob(callback)</dt> 1137 <dd> 1138 calls callback with each code blob in code cache 1139 </dd> 1140 <dt>findCodeBlob(address)</dt> 1141 <dd> 1142 finds the code blob, if any, that contains the given address. 1143 Returns null, on failure. 1144 </dd> 1145 <dt>findNMethod(address)</dt> 1146 <dd> 1147 finds the NMethod that contains given address. 1148 </dd> 1149 <dt>pcDescAt(addr)</dt> 1150 <dd> 1151 returns PCDesc at given address or null. 1152 </dd> 1153 <dt>forEachInterpCodelet(callbacl)</dt> 1154 <dd> 1155 calls callback with each Interpreter codelet 1156 </dd> 1157 </dl> 1158 1159 <h4>VM structs, constants</h4> 1160 <dl> 1161 <dt>forEachType(callback)</dt> 1162 <dd> 1163 calls callback for each Type in VM's type database 1164 </dd> 1165 <dt>forEachVMIntConst(callback)</dt> 1166 <dd> 1167 calls callback for each named integer constant. passes name 1168 as argument. 1169 </dd> 1170 <dt>forEachVMLongConst(callback)</dt> 1171 <dd> 1172 calls callback for each named long constant. passes name 1173 as argument. 1174 </dd> 1175 <dt>findVMType(name)</dt> 1176 <dd> 1177 finds a VM type by name. returns null if no known Type of given name 1178 exists in type database. 1179 </dd> 1180 <dt>findVMIntConst(name)</dt> 1181 <dd> 1182 finds an integer constant in type data base by name. 1183 </dd> 1184 <dt>findVMLongConst(name)</dt> 1185 <dd> 1186 finds an long constant in type data base by name. 1187 </dd> 1188 <dt>vmTypeof(addr)</dt> 1189 <dd> 1190 returns VM type of object at 'addr' if any. Else, returns null. 1191 </dd> 1192 <dt>isOfVMType(addr, type)</dt> 1193 <dd> 1194 returns whether object at 'addr' is of VM type 'type' or not. 1195 </dd> 1196 <dt>printVMType(type, addr)</dt> 1197 <dd> 1198 prints 'addr' as VM object of type 'type' 1199 </dd> 1200 <dt>print<i>XXX</i>(addr)</dt> 1201 <dd> 1202 For each VM type, these functions are defined. For eg. there is printUniverse, 1203 printSystemDictionary etc. are available. Without 'addr' being passed static fields are printed. With 'addr' param being passed, instance fields are printed. 1204 </dd> 1205 </dl> 1206 1207 <h4>Low level debugger facilities</h4> 1208 <dl> 1209 <dt>num2addr(number)</dt> 1210 <dd> 1211 converts a (long) number to SA Address instance 1212 </dd> 1213 <dt>str2addr(string)</dt> 1214 <dd> 1215 converts a given hex string to SA Address instance 1216 </dd> 1217 <dt>any2addr(any)</dt> 1218 <dd> 1219 Takes a number or a string or an Address and returns 1220 an Address instance. For other types, returns 'undefined' 1221 </dd> 1222 <dt>addr2str(addr)</dt> 1223 <dd> 1224 converts a given Address instance to a hex string 1225 </dd> 1226 <dt>addr2num(addr)</dt> 1227 <dd> 1228 converts a given Address instance to a (long) number 1229 </dd> 1230 <dt>sym2addr(library, symbol)</dt> 1231 <dd> 1232 returns Address of a given symbol in a given library (shared object or DLL) 1233 Example: sym2addr('jvm.dll', 'JNI_CreateJavaVM') 1234 <dt>addr2sym(addr)</dt> 1235 <dd> 1236 Returns nearest symbol to a given address (if any). If no such symbol is found, 1237 returns the given address as a string. 1238 </dd> 1239 <dt>readBytesAt(addr, num)</dt> 1240 <dd> 1241 returns 'num' bytes at 'addr' as a Java byte[] 1242 </dd> 1243 <dt>readWordsAt(addr, num)</dt> 1244 <dd> 1245 returns 'num' words at 'addr' as a Java long[] 1246 </dd> 1247 <dt>readCStrAt(addr)</dt> 1248 <dd> 1249 returns 'C' String at given address 1250 </dd> 1251 <dt>readCStrLen(addr)</dt> 1252 <dd> 1253 returns the length of the 'C' String at given address 1254 </dd> 1255 <dt>readRegs(threadProxy)</dt> 1256 <dd> 1257 returns register set (of Thread Context) of a given thread specified 1258 by threadProxy. return value is an associate array having name-value pairs 1259 of registers. 1260 </dd> 1261 <dt>regs(threadProxy)</dt> 1262 <dd> 1263 prints register set of a given thread. 1264 </dd> 1265 <dt>mem(addr, [num])</dt> 1266 <dd> 1267 prints 'num' words (address size) at 'addr'. Prints nearest symbol for address, if found. 1268 </dd> 1269 <dt>dis(addr, [num])</dt> 1270 <dd>prints native code disassembly of 'num' bytes at given address 'addr'. 1271 Default value of 'num' is 4. This automatically detects whether the given address 1272 inside a nmethod. If so, it prints safepoint info, entry points , method signature etc. 1273 of the nmethod. 1274 </dd> 1275 <dt>jdis(method [or addr])</dt> 1276 <dd> 1277 prints Java bytecode disassembly for given method Oop or address of a method Oop. 1278 </dd> 1279 <dt>nmethoddis(nmethod)</dt> 1280 <dd> 1281 prints disassembly of given nmethod object. Note that you don't have to call this directly 1282 instead use 'dis'. 1283 </dd> 1284 <dt>where</dt> 1285 <dd> 1286 prints Java stack trace for all Java threads 1287 </dd> 1288 </dl> 1289 1290 <h4>Miscellaneous</h4> 1291 <dl> 1292 <dt>addr2oop(addr)</dt> 1293 <dd> 1294 converts a given address to a Oop object 1295 </dd> 1296 <dt>oop2addr(oop)</dt> 1297 <dd> 1298 returns address of a given Oop object 1299 </dd> 1300 <dt>isOfVMType(addr, type)</dt> 1301 <dd> 1302 returns whether the given 'addr' points to a (C++) VM object of specified 1303 type. type may be specified by SA Type object or string name of the type. 1304 </dd> 1305 <dt>newVMObject(addr)</dt> 1306 <dd> 1307 returns instance of SA object for a given address (similar to SA VirtualConstructor 1308 interface). 1309 </dd> 1310 <dt>vmobj2addr(vmobject)</dt> 1311 <dd> 1312 returns Address represented by a given SA VMObject 1313 </dd> 1314 <dt>addr2vmobj(addr)</dt> 1315 <dd>same as newVMObject(addr)</dd> 1316 <dt>whatis(addr)</dt> 1317 <dd> 1318 returns string description of given address (using SA FindPointer and guess type API). 1319 <dt>isOop(addr)</dt> 1320 <dd> 1321 returns whether a given address is a valid Oop address or not 1322 </dd> 1323 </dl> 1324 1325 <h4>Moving b/w jsdb low level and high level interfaces</h4> 1326 1327 <p> 1328 Java objects of debuggee are represented by different script wrappers in high level 1329 interface. In the low-level interface these are instances of SA Oop class or its' 1330 subclass. To move b/w low-level and high-level interfaces the following functions may 1331 be used 1332 </p> 1333 <dl> 1334 <dt>oop2obj(oop)</dt> 1335 <dd> 1336 converts a given Oop object to a high-level wrapper object 1337 </dd> 1338 <dt>obj2oop(obj)</dt> 1339 <dd> 1340 converts a jsdb high level wrapper to underlying Oop instance 1341 </dd> 1342 </dl> 1343 1344 <h3>JavaScript tips</h3> 1345 1346 <ul> 1347 <li>to know properties, functions of any object, use the script 1348 <pre> 1349 <core> 1350 for(i in object) { println(i); } 1351 </code> 1352 </pre> 1353 <li>to view the source code of any function, just type the name of 1354 function in jsdb prompt 1355 <li>to view global functions, properties, run 1356 <pre> 1357 <code> 1358 for(i in this) { println(i); } 1359 </code> 1360 </pre> 1361 </ul> 1362 1363 </body> 1364 </html>