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>