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