1
+ − 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>forEachPrimArrayKlass(callback)</dt>
+ − 1112 <dd>
+ − 1113 calls callback with Klass and initiating loader (Oop) for each
+ − 1114 primitive array Klass in the system.
+ − 1115 </dd>
+ − 1116 <dt>findInstanceKlass(name)</dt>
+ − 1117 <dd>
+ − 1118 finds the first instance klass with given name from System dictionary
+ − 1119 </dd>
+ − 1120 </dl>
+ − 1121
+ − 1122 <h4>Thread, Frame Iterators</h4>
+ − 1123 <dl>
+ − 1124 <dt>forEachJavaThread(callback)</dt>
+ − 1125 <dd>calls callback for each Java Thread</dd>
+ − 1126 <dt>forEachFrame(javaThread, callback)</dt>
+ − 1127 <dd>calls callback for each Frame of a given JavaThread</dd>
+ − 1128 <dt>forEachVFrame(javaThread, callback)</dt>
+ − 1129 <dd>calls callback for each JavaVFrame of a given JavaThread</dd>
+ − 1130 <dt>forEachThread(callback)</dt>
+ − 1131 <dd>calls callback for each (native) ThreadProxy (obtained by CDebugger.getThreadList)
+ − 1132 </dd>
+ − 1133 <dt>forEachCFrame(threadProxy, callback)</dt>
+ − 1134 <dd>
+ − 1135 calls callback for each CFrame of a given ThreadProxy object
+ − 1136 </dd>
+ − 1137 </dl>
+ − 1138
+ − 1139 <h4>Code blobs, Interpreter codelets</h4>
+ − 1140 <dl>
+ − 1141 <dt>forEachCodeBlob(callback)</dt>
+ − 1142 <dd>
+ − 1143 calls callback with each code blob in code cache
+ − 1144 </dd>
+ − 1145 <dt>findCodeBlob(address)</dt>
+ − 1146 <dd>
+ − 1147 finds the code blob, if any, that contains the given address.
+ − 1148 Returns null, on failure.
+ − 1149 </dd>
+ − 1150 <dt>findNMethod(address)</dt>
+ − 1151 <dd>
+ − 1152 finds the NMethod that contains given address.
+ − 1153 </dd>
+ − 1154 <dt>pcDescAt(addr)</dt>
+ − 1155 <dd>
+ − 1156 returns PCDesc at given address or null.
+ − 1157 </dd>
+ − 1158 <dt>forEachInterpCodelet(callbacl)</dt>
+ − 1159 <dd>
+ − 1160 calls callback with each Interpreter codelet
+ − 1161 </dd>
+ − 1162 </dl>
+ − 1163
+ − 1164 <h4>VM structs, constants</h4>
+ − 1165 <dl>
+ − 1166 <dt>forEachType(callback)</dt>
+ − 1167 <dd>
+ − 1168 calls callback for each Type in VM's type database
+ − 1169 </dd>
+ − 1170 <dt>forEachVMIntConst(callback)</dt>
+ − 1171 <dd>
+ − 1172 calls callback for each named integer constant. passes name
+ − 1173 as argument.
+ − 1174 </dd>
+ − 1175 <dt>forEachVMLongConst(callback)</dt>
+ − 1176 <dd>
+ − 1177 calls callback for each named long constant. passes name
+ − 1178 as argument.
+ − 1179 </dd>
+ − 1180 <dt>findVMType(name)</dt>
+ − 1181 <dd>
+ − 1182 finds a VM type by name. returns null if no known Type of given name
+ − 1183 exists in type database.
+ − 1184 </dd>
+ − 1185 <dt>findVMIntConst(name)</dt>
+ − 1186 <dd>
+ − 1187 finds an integer constant in type data base by name.
+ − 1188 </dd>
+ − 1189 <dt>findVMLongConst(name)</dt>
+ − 1190 <dd>
+ − 1191 finds an long constant in type data base by name.
+ − 1192 </dd>
+ − 1193 <dt>vmTypeof(addr)</dt>
+ − 1194 <dd>
+ − 1195 returns VM type of object at 'addr' if any. Else, returns null.
+ − 1196 </dd>
+ − 1197 <dt>isOfVMType(addr, type)</dt>
+ − 1198 <dd>
+ − 1199 returns whether object at 'addr' is of VM type 'type' or not.
+ − 1200 </dd>
+ − 1201 <dt>printVMType(type, addr)</dt>
+ − 1202 <dd>
+ − 1203 prints 'addr' as VM object of type 'type'
+ − 1204 </dd>
+ − 1205 <dt>print<i>XXX</i>(addr)</dt>
+ − 1206 <dd>
+ − 1207 For each VM type, these functions are defined. For eg. there is printUniverse,
+ − 1208 printSystemDictionary etc. are available. Without 'addr' being passed static fields are printed. With 'addr' param being passed, instance fields are printed.
+ − 1209 </dd>
+ − 1210 </dl>
+ − 1211
+ − 1212 <h4>Low level debugger facilities</h4>
+ − 1213 <dl>
+ − 1214 <dt>num2addr(number)</dt>
+ − 1215 <dd>
+ − 1216 converts a (long) number to SA Address instance
+ − 1217 </dd>
+ − 1218 <dt>str2addr(string)</dt>
+ − 1219 <dd>
+ − 1220 converts a given hex string to SA Address instance
+ − 1221 </dd>
+ − 1222 <dt>any2addr(any)</dt>
+ − 1223 <dd>
+ − 1224 Takes a number or a string or an Address and returns
+ − 1225 an Address instance. For other types, returns 'undefined'
+ − 1226 </dd>
+ − 1227 <dt>addr2str(addr)</dt>
+ − 1228 <dd>
+ − 1229 converts a given Address instance to a hex string
+ − 1230 </dd>
+ − 1231 <dt>addr2num(addr)</dt>
+ − 1232 <dd>
+ − 1233 converts a given Address instance to a (long) number
+ − 1234 </dd>
+ − 1235 <dt>sym2addr(library, symbol)</dt>
+ − 1236 <dd>
+ − 1237 returns Address of a given symbol in a given library (shared object or DLL)
+ − 1238 Example: sym2addr('jvm.dll', 'JNI_CreateJavaVM')
+ − 1239 <dt>addr2sym(addr)</dt>
+ − 1240 <dd>
+ − 1241 Returns nearest symbol to a given address (if any). If no such symbol is found,
+ − 1242 returns the given address as a string.
+ − 1243 </dd>
+ − 1244 <dt>readBytesAt(addr, num)</dt>
+ − 1245 <dd>
+ − 1246 returns 'num' bytes at 'addr' as a Java byte[]
+ − 1247 </dd>
+ − 1248 <dt>readWordsAt(addr, num)</dt>
+ − 1249 <dd>
+ − 1250 returns 'num' words at 'addr' as a Java long[]
+ − 1251 </dd>
+ − 1252 <dt>readCStrAt(addr)</dt>
+ − 1253 <dd>
+ − 1254 returns 'C' String at given address
+ − 1255 </dd>
+ − 1256 <dt>readCStrLen(addr)</dt>
+ − 1257 <dd>
+ − 1258 returns the length of the 'C' String at given address
+ − 1259 </dd>
+ − 1260 <dt>readRegs(threadProxy)</dt>
+ − 1261 <dd>
+ − 1262 returns register set (of Thread Context) of a given thread specified
+ − 1263 by threadProxy. return value is an associate array having name-value pairs
+ − 1264 of registers.
+ − 1265 </dd>
+ − 1266 <dt>regs(threadProxy)</dt>
+ − 1267 <dd>
+ − 1268 prints register set of a given thread.
+ − 1269 </dd>
+ − 1270 <dt>mem(addr, [num])</dt>
+ − 1271 <dd>
+ − 1272 prints 'num' words (address size) at 'addr'. Prints nearest symbol for address, if found.
+ − 1273 </dd>
+ − 1274 <dt>dis(addr, [num])</dt>
+ − 1275 <dd>prints native code disassembly of 'num' bytes at given address 'addr'.
+ − 1276 Default value of 'num' is 4. This automatically detects whether the given address
+ − 1277 inside a nmethod. If so, it prints safepoint info, entry points , method signature etc.
+ − 1278 of the nmethod.
+ − 1279 </dd>
+ − 1280 <dt>jdis(method [or addr])</dt>
+ − 1281 <dd>
+ − 1282 prints Java bytecode disassembly for given method Oop or address of a method Oop.
+ − 1283 </dd>
+ − 1284 <dt>nmethoddis(nmethod)</dt>
+ − 1285 <dd>
+ − 1286 prints disassembly of given nmethod object. Note that you don't have to call this directly
+ − 1287 instead use 'dis'.
+ − 1288 </dd>
+ − 1289 <dt>where</dt>
+ − 1290 <dd>
+ − 1291 prints Java stack trace for all Java threads
+ − 1292 </dd>
+ − 1293 </dl>
+ − 1294
+ − 1295 <h4>Miscellaneous</h4>
+ − 1296 <dl>
+ − 1297 <dt>addr2oop(addr)</dt>
+ − 1298 <dd>
+ − 1299 converts a given address to a Oop object
+ − 1300 </dd>
+ − 1301 <dt>oop2addr(oop)</dt>
+ − 1302 <dd>
+ − 1303 returns address of a given Oop object
+ − 1304 </dd>
+ − 1305 <dt>isOfVMType(addr, type)</dt>
+ − 1306 <dd>
+ − 1307 returns whether the given 'addr' points to a (C++) VM object of specified
+ − 1308 type. type may be specified by SA Type object or string name of the type.
+ − 1309 </dd>
+ − 1310 <dt>newVMObject(addr)</dt>
+ − 1311 <dd>
+ − 1312 returns instance of SA object for a given address (similar to SA VirtualConstructor
+ − 1313 interface).
+ − 1314 </dd>
+ − 1315 <dt>vmobj2addr(vmobject)</dt>
+ − 1316 <dd>
+ − 1317 returns Address represented by a given SA VMObject
+ − 1318 </dd>
+ − 1319 <dt>addr2vmobj(addr)</dt>
+ − 1320 <dd>same as newVMObject(addr)</dd>
+ − 1321 <dt>whatis(addr)</dt>
+ − 1322 <dd>
+ − 1323 returns string description of given address (using SA FindPointer and guess type API).
+ − 1324 <dt>isOop(addr)</dt>
+ − 1325 <dd>
+ − 1326 returns whether a given address is a valid Oop address or not
+ − 1327 </dd>
+ − 1328 </dl>
+ − 1329
+ − 1330 <h4>Moving b/w jsdb low level and high level interfaces</h4>
+ − 1331
+ − 1332 <p>
+ − 1333 Java objects of debuggee are represented by different script wrappers in high level
+ − 1334 interface. In the low-level interface these are instances of SA Oop class or its'
+ − 1335 subclass. To move b/w low-level and high-level interfaces the following functions may
+ − 1336 be used
+ − 1337 </p>
+ − 1338 <dl>
+ − 1339 <dt>oop2obj(oop)</dt>
+ − 1340 <dd>
+ − 1341 converts a given Oop object to a high-level wrapper object
+ − 1342 </dd>
+ − 1343 <dt>obj2oop(obj)</dt>
+ − 1344 <dd>
+ − 1345 converts a jsdb high level wrapper to underlying Oop instance
+ − 1346 </dd>
+ − 1347 </dl>
+ − 1348
+ − 1349 <h3>JavaScript tips</h3>
+ − 1350
+ − 1351 <ul>
+ − 1352 <li>to know properties, functions of any object, use the script
+ − 1353 <pre>
+ − 1354 <core>
+ − 1355 for(i in object) { println(i); }
+ − 1356 </code>
+ − 1357 </pre>
+ − 1358 <li>to view the source code of any function, just type the name of
+ − 1359 function in jsdb prompt
+ − 1360 <li>to view global functions, properties, run
+ − 1361 <pre>
+ − 1362 <code>
+ − 1363 for(i in this) { println(i); }
+ − 1364 </code>
+ − 1365 </pre>
+ − 1366 </ul>
+ − 1367
+ − 1368 </body>
+ − 1369 </html>