1 <!-- |
|
2 Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. |
|
3 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 |
|
5 This code is free software; you can redistribute it and/or modify it |
|
6 under the terms of the GNU General Public License version 2 only, as |
|
7 published by the Free Software Foundation. Oracle designates this |
|
8 particular file as subject to the "Classpath" exception as provided |
|
9 by Oracle in the LICENSE file that accompanied this code. |
|
10 |
|
11 This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 version 2 for more details (a copy is included in the LICENSE file that |
|
15 accompanied this code). |
|
16 |
|
17 You should have received a copy of the GNU General Public License version |
|
18 2 along with this work; if not, write to the Free Software Foundation, |
|
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
|
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
22 or visit www.oracle.com if you need additional information or have any |
|
23 questions. |
|
24 --> |
|
25 |
|
26 <html> |
|
27 <head> |
|
28 <style> |
|
29 .key { color: red; font-weight: bold } |
|
30 </style> |
|
31 <title> |
|
32 Object Query Language (OQL) |
|
33 </title> |
|
34 </head> |
|
35 <body> |
|
36 <h1>Object Query Language (OQL)</h1> |
|
37 |
|
38 <p> |
|
39 OQL is SQL-like query language to query Java heap. OQL allows to filter/select information |
|
40 wanted from Java heap. While pre-defined queries such as "show all instances of class X" |
|
41 are already supported by HAT, OQL adds more flexibility. OQL is based on JavaScript expression |
|
42 language. |
|
43 </p> |
|
44 |
|
45 <p> |
|
46 OQL query is of the form |
|
47 |
|
48 <pre> |
|
49 <code> |
|
50 <span class="key">select</span> <JavaScript expression to select> |
|
51 [ <span class="key">from</span> [<span class="key">instanceof</span>] <class name> <identifier> |
|
52 [ <span class="key">where</span> <JavaScript boolean expression to filter> ] ] |
|
53 </code> |
|
54 </pre> |
|
55 where class name is fully qualified Java class name (example: java.net.URL) or array class name. |
|
56 [C is char array name, [Ljava.io.File; is name of java.io.File[] and so on. |
|
57 Note that fully qualified class name does not always uniquely identify a |
|
58 Java class at runtime. There may be more than one Java class with the same |
|
59 name but loaded by different loaders. So, class name is permitted to be |
|
60 id string of the class object. |
|
61 |
|
62 If <span class="key">instanceof</span> keyword is used, subtype objects are selected. If this |
|
63 keyword is not specified, only the instances of exact class specified are selected. Both |
|
64 <span class="key">from</span> and <span class="key">where</span> clauses are optional. |
|
65 </p> |
|
66 |
|
67 |
|
68 <p> |
|
69 In <span class="key">select</span> and (optional) <span class="key">where</span> clauses, the expression |
|
70 used in JavaScript expression. Java heap objects are wrapped as convenient script objects so that |
|
71 fields may be accessed in natural syntax. For example, Java fields can be accessed with obj.field_name |
|
72 syntax and array elements can be accessed with array[index] syntax. Each Java object selected is |
|
73 bound to a JavaScript variable of the identifier name specified in <span class="key">from</span> clause. |
|
74 </p> |
|
75 |
|
76 <h2>OQL Examples</h2> |
|
77 |
|
78 <ul> |
|
79 <li>select all Strings of length 100 or more |
|
80 <pre> |
|
81 <code> |
|
82 select s from java.lang.String s where s.value.length >= 100 |
|
83 </code> |
|
84 </pre> |
|
85 <li>select all int arrays of length 256 or more |
|
86 <pre> |
|
87 <code> |
|
88 select a from [I a where a.length >= 256 |
|
89 </code> |
|
90 </pre> |
|
91 <li>show content of Strings that match a regular expression |
|
92 <pre> |
|
93 <code> |
|
94 select s.value.toString() from java.lang.String s |
|
95 where /java/.test(s.value.toString()) |
|
96 </code> |
|
97 </pre> |
|
98 <li>show path value of all File objects |
|
99 <pre> |
|
100 <code</b> |
|
101 select file.path.value.toString() from java.io.File file |
|
102 </code> |
|
103 </pre> |
|
104 <li>show names of all ClassLoader classes |
|
105 <pre> |
|
106 <code> |
|
107 select <a href="#classof">classof</a>(cl).name |
|
108 from instanceof java.lang.ClassLoader cl |
|
109 </code> |
|
110 </pre> |
|
111 <li>show instances of the Class identified by given id string |
|
112 <pre> |
|
113 <code> |
|
114 select o from instanceof 0xd404b198 o |
|
115 </code> |
|
116 </pre> |
|
117 Note that 0xd404b198 is id of a Class (in a session). This is found by |
|
118 looking at the id shown in that class's page. |
|
119 </ul> |
|
120 |
|
121 <h2>OQL built-in objects, functions</h2> |
|
122 |
|
123 <h3>heap object</h3> |
|
124 |
|
125 The <b>heap</b> built-in object supports the following methods: |
|
126 |
|
127 <ul> |
|
128 <li><b>heap.forEachClass</b> -- calls a callback function for each Java Class |
|
129 <pre> |
|
130 <code> |
|
131 heap.forEachClass(callback); |
|
132 </code> |
|
133 </pre> |
|
134 <li><b>heap.forEachObject</b> -- calls a callback function for each Java object |
|
135 <pre> |
|
136 <code> |
|
137 heap.forEachObject(callback, clazz, includeSubtypes); |
|
138 </code> |
|
139 </pre> |
|
140 <code>clazz</code> is the class whose instances are selected. If not specified, defaults to java.lang.Object. <code>includeSubtypes</code> is a boolean flag |
|
141 that specifies whether to include subtype instances or not. Default value of |
|
142 this flag is true. |
|
143 <a name="findClass"></a> |
|
144 <li><b>heap.findClass</b> -- finds Java Class of given name |
|
145 <pre> |
|
146 <code> |
|
147 heap.findClass(className); |
|
148 </code> |
|
149 </pre> |
|
150 where <code>className</code> is name of the class to find. The resulting Class |
|
151 object has following properties: |
|
152 <ul> |
|
153 <li>name - name of the class. |
|
154 <li>superclass - Class object for super class (or null if java.lang.Object). |
|
155 <li>statics - name, value pairs for static fields of the Class. |
|
156 <li>fields - array of field objects. field object has name, signature |
|
157 properties. |
|
158 <li>loader - ClassLoader object that loaded this class. |
|
159 <li>signers - signers that signed this class. |
|
160 <li>protectionDomain - protection domain to which this class belongs. |
|
161 </ul> |
|
162 Class objects have the following methods: |
|
163 <ul> |
|
164 <li>isSubclassOf - tests whether given class is direct or indirect |
|
165 subclass of this class or not. |
|
166 <li>isSuperclassOf - tests whether given Class is direct or indirect |
|
167 superclass of this class or not. |
|
168 <li>subclasses - returns array of direct and indirect subclasses. |
|
169 <li>superclasses - returns array of direct and indirect superclasses. |
|
170 </ul> |
|
171 <a name="findObject"></a> |
|
172 <li><b>heap.findObject</b> -- finds object from given object id |
|
173 <pre> |
|
174 <code> |
|
175 heap.findObject(stringIdOfObject); |
|
176 </code> |
|
177 </pre> |
|
178 <a name="classes"></a> |
|
179 <li><b>heap.classes</b> -- returns an enumeration of all Java classes |
|
180 <a name="objects"></a> |
|
181 <li><b>heap.objects</b> -- returns an enumeration of Java objects |
|
182 <pre> |
|
183 <code> |
|
184 heap.objects(clazz, [includeSubtypes], [filter]) |
|
185 </code> |
|
186 </pre> |
|
187 <code>clazz</code> is the class whose instances are selected. If not specified, defaults to java.lang.Object. <code>includeSubtypes</code> is a boolean flag |
|
188 that specifies whether to include subtype instances or not. Default value of |
|
189 this flag is true. This method accepts an optional filter expression to filter |
|
190 the result set of objects. |
|
191 <a name="finalizables"></a> |
|
192 <li><b>heap.finalizables</b> -- returns an enumeration of Java objects that are |
|
193 pending to be finalized. |
|
194 <li><b>heap.livepaths</b> -- return an array of paths by which a given object |
|
195 is alive. This method accepts optional second parameter that is a boolean |
|
196 flag. This flag tells whether to include paths with weak reference(s) or not. |
|
197 By default, paths with weak reference(s) are not included. |
|
198 <pre> |
|
199 <code> |
|
200 select heap.livepaths(s) from java.lang.String s |
|
201 </code> |
|
202 </pre> |
|
203 Each element of this array itself is another array. The later array is |
|
204 contains an objects that are in the 'reference chain' of the path. |
|
205 <li><b>heap.roots</b> -- returns an Enumeration of Roots of the heap. |
|
206 <a name="rootobj"></a> |
|
207 Each Root object has the following properties: |
|
208 <ul> |
|
209 <li>id - String id of the object that is referred by this root |
|
210 <li>type - descriptive type of Root (JNI Global, JNI Local, Java Static etc) |
|
211 <li>description - String description of the Root |
|
212 <li>referrer - Thread Object or Class object that is responsible for this root or null |
|
213 </ul> |
|
214 </ul> |
|
215 |
|
216 Examples: |
|
217 <ul> |
|
218 <li>access static field 'props' of class java.lang.System |
|
219 <pre> |
|
220 <code> |
|
221 select heap.findClass("java.lang.System").statics.props |
|
222 </code> |
|
223 </pre> |
|
224 <li>get number of fields of java.lang.String class |
|
225 <pre> |
|
226 <code> |
|
227 select heap.findClass("java.lang.String").fields.length |
|
228 </code> |
|
229 </pre> |
|
230 <li> find the object whose object id is given |
|
231 <pre> |
|
232 <code> |
|
233 select heap.findObject("0xf3800b58") |
|
234 </code> |
|
235 </pre> |
|
236 <li>select all classes that have name pattern java.net.* |
|
237 <pre> |
|
238 <code> |
|
239 select <a href="#filter">filter</a>(heap.classes(), "/java.net./.test(it.name)") |
|
240 </code> |
|
241 </pre> |
|
242 </ul> |
|
243 |
|
244 <h3>functions on individual objects</h3> |
|
245 |
|
246 <ul> |
|
247 <li><a href="#allocTrace">allocTrace(jobject)</a> |
|
248 <li><a href="#classof">classof(jobject)</a> |
|
249 <li><a href="#forEachReferrer">forEachReferrer(callback, jobject)</a> |
|
250 <li><a href="#identical">identical(o1, o2)</a> |
|
251 <li><a href="#objectid">objectid(jobject)</a> |
|
252 <li><a href="#reachables">reachables(jobject, excludedFields)</a> |
|
253 <li><a href="#referrers">referrers(jobject)</a> |
|
254 <li><a href="#referees">referees(jobject)</a> |
|
255 <li><a href="#refers">refers(jobject)</a> |
|
256 <li><a href="#root">root(jobject)</a> |
|
257 <li><a href="#sizeof">sizeof(jobject)</a> |
|
258 <li><a href="#toHtml">toHtml(obj)</a> |
|
259 </ul> |
|
260 |
|
261 <a name="allocTrace"></a> |
|
262 <h4>allocTrace function</h4> |
|
263 |
|
264 This returns allocation site trace of a given Java object if available. |
|
265 allocTrace returns array of frame objects. Each frame object has the following |
|
266 properties: |
|
267 <ul> |
|
268 <li>className - name of the Java class whose method is running in the frame. |
|
269 <li>methodName - name of the Java method running in the frame. |
|
270 <li>methodSignature - signature of the Java method running in the frame. |
|
271 <li>sourceFileName - name of source file of the Java class running in the frame. |
|
272 <li>lineNumber - source line number within the method. |
|
273 </ul> |
|
274 |
|
275 <a name="classof"></a> |
|
276 <h4>classof function</h4> |
|
277 |
|
278 Returns Class object of a given Java Object. The result object supports the |
|
279 following properties: |
|
280 <ul> |
|
281 <li>name - name of the class. |
|
282 <li>superclass - Class object for super class (or null if java.lang.Object). |
|
283 <li>statics - name, value pairs for static fields of the Class. |
|
284 <li>fields - array of field objects. Field objects have name, signature |
|
285 properties. |
|
286 <li>loader - ClassLoader object that loaded this class. |
|
287 <li>signers - signers that signed this class. |
|
288 <li>protectionDomain - protection domain to which this class belongs. |
|
289 </ul> |
|
290 Class objects have the following methods: |
|
291 <ul> |
|
292 <li>isSubclassOf - tests whether given class is direct or indirect |
|
293 subclass of this class or not. |
|
294 <li>isSuperclassOf - tests whether given Class is direct or indirect |
|
295 superclass of this class or not. |
|
296 <li>subclasses - returns array of direct and indirect subclasses. |
|
297 <li>superclasses - returns array of direct and indirect superclasses. |
|
298 </ul> |
|
299 |
|
300 Examples: |
|
301 <ul> |
|
302 <li>show class name of each Reference type object |
|
303 <pre> |
|
304 <code> |
|
305 select classof(o).name from instanceof java.lang.ref.Reference o |
|
306 </code> |
|
307 <li>show all subclasses of java.io.InputStream |
|
308 <pre> |
|
309 <code> |
|
310 select heap.findClass("java.io.InputStream").subclasses() |
|
311 </code> |
|
312 <li>show all superclasses of java.io.BufferedInputStream |
|
313 <pre> |
|
314 <code> |
|
315 select heap.findClass("java.io.BufferedInputStream").superclasses() |
|
316 </code> |
|
317 </pre> |
|
318 </ul> |
|
319 |
|
320 <a name="forEachReferrer"></a> |
|
321 <h4>forEachReferrer function</h4> |
|
322 |
|
323 calls a callback function for each referrer of a given Java object. |
|
324 |
|
325 <a name="identical"></a> |
|
326 <h4>identical function</h4> |
|
327 <p> |
|
328 Returns whether two given Java objects are identical or not. |
|
329 </p> |
|
330 Example: |
|
331 <pre> |
|
332 <code> |
|
333 select identical(heap.findClass("Foo").statics.bar, heap.findClass("AnotherClass").statics.bar) |
|
334 </code> |
|
335 </pre> |
|
336 |
|
337 <a name="objectid"></a> |
|
338 <h4>objectid function</h4> |
|
339 |
|
340 <p> |
|
341 Returns String id of a given Java object. This id can be passed to |
|
342 <a href="#findObject">heap.findObject</a> and may also be used to compare |
|
343 objects for identity. |
|
344 </p> |
|
345 Example: |
|
346 <pre> |
|
347 <code> |
|
348 select objectid(o) from java.lang.Object o |
|
349 </code> |
|
350 </pre> |
|
351 |
|
352 <a name="reachables"></a> |
|
353 <h4>reachables function</h4> |
|
354 <p> |
|
355 Returns an array of Java objects that are transitively referred from the |
|
356 given Java object. Optionally accepts a second parameter that is comma |
|
357 separated field names to be excluded from reachability computation. |
|
358 Fields are written in class_name.field_name pattern. |
|
359 </p> |
|
360 Examples: |
|
361 <ul> |
|
362 <li>print all reachable objects from each Properties instance. |
|
363 <pre> |
|
364 <code> |
|
365 select reachables(p) from java.util.Properties p |
|
366 </code> |
|
367 </pre> |
|
368 <li>print all reachables from each java.net.URL but omit the objects reachable |
|
369 via the fields specified. |
|
370 <pre> |
|
371 <code> |
|
372 select reachables(u, 'java.net.URL.handler') from java.net.URL u |
|
373 </code> |
|
374 </pre> |
|
375 </ul> |
|
376 |
|
377 <a name="referrers"></a> |
|
378 <h4>referrers function</h4> |
|
379 <p> |
|
380 Returns an enumeration of Java objects that hold reference to a given Java |
|
381 object. |
|
382 </p> |
|
383 Examples: |
|
384 <ul> |
|
385 <li> print number of referrers for each java.lang.Object instance |
|
386 <pre> |
|
387 <code> |
|
388 select count(referrers(o)) from java.lang.Object o |
|
389 </code> |
|
390 </pre> |
|
391 <li>print referrers for each java.io.File object |
|
392 <pre> |
|
393 <code> |
|
394 select referrers(f) from java.io.File f |
|
395 </code> |
|
396 </pre> |
|
397 <li>print URL objects only if referred by 2 or more |
|
398 <pre> |
|
399 <code> |
|
400 select u from java.net.URL u where count(referrers(u)) > 2 |
|
401 </code> |
|
402 </pre> |
|
403 </ul> |
|
404 |
|
405 <a name="referees"></a> |
|
406 <h4>referees function</h4> |
|
407 <p> |
|
408 Returns an array of Java objects to which the given Java |
|
409 object directly refers to. |
|
410 </p> |
|
411 Example: to print all static reference fields of java.io.File class |
|
412 <pre> |
|
413 <code> |
|
414 select referees(<a href="#findClass">heap.findClass</a>("java.io.File")) |
|
415 </code> |
|
416 </pre> |
|
417 |
|
418 <a name="refers"></a> |
|
419 <h4>refers function</h4> |
|
420 <p> |
|
421 Returns whether first Java object refers to second Java object or not. |
|
422 </p> |
|
423 |
|
424 <a name="root"></a> |
|
425 <h4>root function</h4> |
|
426 <p> |
|
427 If given object is a member of root set of objects, this function returns |
|
428 a descriptive <a href="#rootobj">Root object</a> describing why it is so. |
|
429 If given object is not a root, then this function returns null. |
|
430 </p> |
|
431 |
|
432 <a name="sizeof"></a> |
|
433 <h4>sizeof function</h4> |
|
434 |
|
435 Returns size of the given Java object in bytes |
|
436 Example: |
|
437 <pre> |
|
438 <code> |
|
439 select sizeof(o) from [I o |
|
440 </code> |
|
441 </pre> |
|
442 |
|
443 <a name="toHtml"></a> |
|
444 <h4>toHtml function</h4> |
|
445 |
|
446 Returns HTML string for the given Java object. Note that this is called |
|
447 automatically for objects selected by select expression. But, it may be useful |
|
448 to print more complex output. |
|
449 |
|
450 Example: print hyperlink in bold font weight |
|
451 <pre> |
|
452 <code> |
|
453 select "<b>" + toHtml(o) + "</b>" from java.lang.Object o |
|
454 </code> |
|
455 </pre> |
|
456 |
|
457 <h3>Selecting multiple values</h3> |
|
458 <p> |
|
459 Multiple values can be selected using JavaScript object literals or arrays. |
|
460 </p> |
|
461 |
|
462 Example: show name and thread for each thread object |
|
463 <pre> |
|
464 <code> |
|
465 select { name: t.name? t.name.toString() : "null", thread: t } |
|
466 from instanceof java.lang.Thread t |
|
467 </code> |
|
468 </pre> |
|
469 |
|
470 <h3>array/iterator/enumeration manipulation functions</h3> |
|
471 |
|
472 <p> |
|
473 These functions accept an array/iterator/enumeration and an |
|
474 expression string [or a callback function] as input. These functions iterate |
|
475 the array/iterator/enumeration and apply the expression (or function) on |
|
476 each element. Note that JavaScript objects are associative arrays. So, |
|
477 these functions may also be used with arbitrary JavaScript objects. |
|
478 </p> |
|
479 |
|
480 <ul> |
|
481 <li><a href="#concat">concat(array1/enumeration1, array2/enumeration2)</a> |
|
482 <li><a href="#contains">contains(array/enumeration, expression)</a> |
|
483 <li><a href="#count">count(array/enumeration, expression)</a> |
|
484 <li><a href="#filter">filter(array/enumeration, expression)</a> |
|
485 <li><a href="#length">length(array/enumeration)</a> |
|
486 <li><a href="#map">map(array/enumeration, expression)</a> |
|
487 <li><a href="#max">max(array/enumeration, [expression])</a> |
|
488 <li><a href="#min">min(array/enumeration, [expression])</a> |
|
489 <li><a href="#sort">sort(array/enumeration, [expression])</a> |
|
490 <li><a href="#sum">sum(array/enumeration, [expression])</a> |
|
491 <li><a href="#toArray">toArray(array/enumeration)</a> |
|
492 <li><a href="#unique">unique(array/enumeration, [expression])</a> |
|
493 </ul> |
|
494 |
|
495 <a name="concat"></a> |
|
496 <h4>concat function</h4> |
|
497 <p> |
|
498 Concatenates two arrays or enumerations (i.e., returns composite |
|
499 enumeration). |
|
500 </p> |
|
501 |
|
502 <a name="contains"></a> |
|
503 <h4>contains function</h4> |
|
504 <p> |
|
505 Returns whether the given array/enumeration contains an element |
|
506 the given boolean expression specified in code. The code evaluated |
|
507 can refer to the following built-in variables. |
|
508 </p> |
|
509 <ul> |
|
510 <li>it -> currently visited element |
|
511 <li>index -> index of the current element |
|
512 <li>array -> array/enumeration that is being iterated |
|
513 </ul> |
|
514 Example: select all Properties objects that are referred by |
|
515 some static field some class. |
|
516 <pre> |
|
517 <code> |
|
518 select p from java.util.Properties p |
|
519 where contains(<a href="#referrers">referrers</a>(p), "<a href="#classof">classof</a>(it).name == 'java.lang.Class'") |
|
520 </code> |
|
521 </pre> |
|
522 |
|
523 <a name="count"></a> |
|
524 <h4>count function</h4> |
|
525 <p> |
|
526 count function returns the count of elements of the input array/enumeration |
|
527 that satisfy the given boolean expression. The boolean expression code can |
|
528 refer to the following built-in variables. |
|
529 </p> |
|
530 <ul> |
|
531 <li>it -> currently visited element |
|
532 <li>index -> index of the current element |
|
533 <li>array -> array/enumeration that is being iterated |
|
534 </ul> |
|
535 Example: print number of classes that have specific name pattern |
|
536 <pre> |
|
537 <code> |
|
538 select count(<a href="#classes">heap.classes()</a>, "/java.io./.test(it.name)") |
|
539 </code> |
|
540 </pre> |
|
541 |
|
542 <a name="filter"></a> |
|
543 <h4>filter function</h4> |
|
544 <p> |
|
545 filter function returns an array/enumeration that contains elements |
|
546 of the input array/enumeration that satisfy the given boolean |
|
547 expression. The boolean expression code can refer to the following built-in |
|
548 variables. |
|
549 </p> |
|
550 <ul> |
|
551 <li>it -> currently visited element |
|
552 <li>index -> index of the current element |
|
553 <li>array -> array/enumeration that is being iterated |
|
554 <li>result -> result array/enumeration |
|
555 </ul> |
|
556 Examples: |
|
557 <ul> |
|
558 <li>show all classes that have java.io.* name pattern |
|
559 <pre> |
|
560 <code> |
|
561 select filter(<a href="#classes">heap.classes</a>(), "/java.io./.test(it.name)") |
|
562 </code> |
|
563 </pre> |
|
564 <li> show all referrers of URL object where the referrer is not from |
|
565 java.net package |
|
566 <pre> |
|
567 <code> |
|
568 select filter(<a href="#referrers">referrers</a>(u), "! /java.net./.test(<a href="#classof">classof</a>(it).name)") |
|
569 from java.net.URL u |
|
570 </code> |
|
571 </pre> |
|
572 </ul> |
|
573 |
|
574 <a name="length"></a> |
|
575 <h4>length function</h4> |
|
576 <p> |
|
577 length function returns number of elements of an array/enumeration. |
|
578 </p> |
|
579 |
|
580 <a name="map"></a> |
|
581 <h4>map function</h4> |
|
582 <p> |
|
583 Transforms the given array/enumeration by evaluating given code |
|
584 on each element. The code evaluated can refer to the following built-in |
|
585 variables. |
|
586 </p> |
|
587 <ul> |
|
588 <li>it -> currently visited element |
|
589 <li>index -> index of the current element |
|
590 <li>array -> array/enumeration that is being iterated |
|
591 <li>result -> result array/enumeration |
|
592 </ul> |
|
593 <p> |
|
594 map function returns an array/enumeration of values created by repeatedly |
|
595 calling code on each element of input array/enumeration. |
|
596 </p> |
|
597 Example: show all static fields of java.io.File with name and value |
|
598 <pre> |
|
599 <code> |
|
600 select map(<a href="#findClass">heap.findClass</a>("java.io.File").statics, "index + '=' + <a href="#toHtml">toHtml</a>(it)") |
|
601 </code> |
|
602 </pre> |
|
603 |
|
604 <a name="max"></a> |
|
605 <h4>max function</h4> |
|
606 <p> |
|
607 returns the maximum element of the given array/enumeration. |
|
608 Optionally accepts code expression to compare elements of the array. |
|
609 By default numerical comparison is used. The comparison expression can |
|
610 use the following built-in variables: |
|
611 </p> |
|
612 <ul> |
|
613 <li>lhs -> left side element for comparison |
|
614 <li>rhs -> right side element for comparison |
|
615 </ul> |
|
616 Examples: |
|
617 <ul> |
|
618 <li>find the maximum length of any String instance |
|
619 <pre> |
|
620 <code> |
|
621 select max(map(heap.objects('java.lang.String', false), 'it.value.length')) |
|
622 </code> |
|
623 </pre> |
|
624 <li>find string instance that has the maximum length |
|
625 <pre> |
|
626 <code> |
|
627 select max(heap.objects('java.lang.String'), 'lhs.value.length > rhs.value.length') |
|
628 </code> |
|
629 </pre> |
|
630 </ul> |
|
631 |
|
632 <a name="min"></a> |
|
633 <h4>min function</h4> |
|
634 <p> |
|
635 returns the minimum element of the given array/enumeration. Optionally |
|
636 accepts code expression to compare elements of the array. By default numerical |
|
637 comparison is used. The comparison expression can use the following built-in |
|
638 variables: |
|
639 </p> |
|
640 <ul> |
|
641 <li>lhs -> left side element for comparison |
|
642 <li>rhs -> right side element for comparison |
|
643 </ul> |
|
644 Examples: |
|
645 <ul> |
|
646 <li>find the minimum size of any Vector instance |
|
647 <pre> |
|
648 <code> |
|
649 select min(map(heap.objects('java.util.Vector', false), 'it.elementData.length')) |
|
650 </code> |
|
651 </pre> |
|
652 <li>find Vector instance that has the maximum length |
|
653 <pre> |
|
654 <code> |
|
655 select min(heap.objects('java.util.Vector'), 'lhs.elementData.length < rhs.elementData.length') |
|
656 </code> |
|
657 </ul> |
|
658 |
|
659 <a name="sort"></a> |
|
660 <h4>sort function</h4> |
|
661 <p> |
|
662 sorts given array/enumeration. Optionally accepts code expression to |
|
663 compare elements of the array. By default numerical comparison is used. |
|
664 The comparison expression can use the following built-in variables: |
|
665 </p> |
|
666 <ul> |
|
667 <li>lhs -> left side element for comparison |
|
668 <li>rhs -> right side element for comparison |
|
669 </ul> |
|
670 Examples: |
|
671 <ul> |
|
672 <li> print all char[] objects in the order of size. |
|
673 <pre> |
|
674 <code> |
|
675 select sort(<a href="#objects">heap.objects</a>('[C'), '<a href="#sizeof">sizeof</a>(lhs) - sizeof(rhs)') |
|
676 </code> |
|
677 </pre> |
|
678 <li> print all char[] objects in the order of size but print |
|
679 size as well. |
|
680 <pre> |
|
681 <code> |
|
682 select <a href="#map">map</a>(sort(<a href="#objects">heap.objects</a>('[C'), '<a href="#sizeof">sizeof</a>(lhs) - sizeof(rhs)'), '{ size: sizeof(it), obj: it }') |
|
683 </code> |
|
684 </pre> |
|
685 </ul> |
|
686 |
|
687 <a name="sum"></a> |
|
688 <h4>sum function</h4> |
|
689 <p> |
|
690 This function returns the sum of all the elements of the given input array or |
|
691 enumeration. Optionally, accepts an expression as second param. This is used |
|
692 to map the input elements before summing those. |
|
693 </p> |
|
694 Example: return sum of sizes of the reachable objects from each Properties object |
|
695 <pre> |
|
696 <code> |
|
697 select sum(<a href="#map">map</a>(<a href="#reachables">reachables</a>(p), '<a href="#sizeof">sizeof</a>(it)')) |
|
698 from java.util.Properties p |
|
699 |
|
700 // or omit the map as in ... |
|
701 select sum(<a href="#reachables">reachables</a>(p), '<a href="#sizeof">sizeof</a>(it)') |
|
702 from java.util.Properties p |
|
703 </code> |
|
704 </code> |
|
705 </pre> |
|
706 |
|
707 <a name="toArray"></a> |
|
708 <h4>toArray function</h4> |
|
709 <p> |
|
710 This function returns an array that contains elements of the input |
|
711 array/enumeration. |
|
712 </p> |
|
713 |
|
714 <a name="unique"></a> |
|
715 <h4>unique function</h4> |
|
716 <p> |
|
717 This function returns an array/enumeration containing unique elements of the |
|
718 given input array/enumeration |
|
719 </p> |
|
720 Example: select unique char[] instances referenced from Strings. Note that |
|
721 more than one String instance can share the same char[] for the content. |
|
722 <pre> |
|
723 <code> |
|
724 // number of unique char[] instances referenced from any String |
|
725 select count(unique(map(heap.objects('java.lang.String'), 'it.value'))) |
|
726 |
|
727 // total number of Strings |
|
728 select count(heap.objects('java.lang.String')) |
|
729 </code> |
|
730 </pre> |
|
731 |
|
732 <h3>More complex examples</h3> |
|
733 |
|
734 <h4>Print histogram of each class loader and number of classes loaded by it</h4> |
|
735 |
|
736 <pre> |
|
737 <code> |
|
738 select <a href="#map">map</a>(<a href="#sort">sort</a>(map(heap.objects('java.lang.ClassLoader'), |
|
739 '{ loader: it, count: it.classes.elementCount }'), 'lhs.count < rhs.count'), |
|
740 'toHtml(it) + "<br>"') |
|
741 </code> |
|
742 </pre> |
|
743 <p> |
|
744 The above query uses the fact that, <b>java.lang.ClassLoader</b> has a private |
|
745 field called <b>classes</b> of type <b>java.util.Vector</b> and Vector has a |
|
746 private field named <b>elementCount</b> that is number of elements in the |
|
747 vector. We select multiple values (loader, count) using JavaScript object |
|
748 literal and map function. We sort the result by count (i.e., number of classes |
|
749 loaded) using sort function with comparison expression. |
|
750 </p> |
|
751 |
|
752 <h4>Show parent-child chain for each class loader instance</h4> |
|
753 |
|
754 <pre> |
|
755 <code> |
|
756 select <a href="#map">map</a>(heap.objects('java.lang.ClassLoader'), |
|
757 function (it) { |
|
758 var res = ''; |
|
759 while (it != null) { |
|
760 res += toHtml(it) + "->"; |
|
761 it = it.parent; |
|
762 } |
|
763 res += "null"; |
|
764 return res + "<br>"; |
|
765 }) |
|
766 </code> |
|
767 </pre> |
|
768 <p> |
|
769 Note that we use <b>parent</b> field of <b>java.lang.ClassLoader</b> class |
|
770 and walk until parent is null using the callback function to map call. |
|
771 </p> |
|
772 |
|
773 <h4>Printing value of all System properties</h4> |
|
774 |
|
775 <pre> |
|
776 <code> |
|
777 select <a href="#map">map</a>(<a href="#filter">filter(<a href="#findClass">heap.findClass</a>('java.lang.System').statics.props.table, 'it != null'), |
|
778 function (it) { |
|
779 var res = ""; |
|
780 while (it != null) { |
|
781 res += it.key.value.toString() + '=' + |
|
782 it.value.value.toString() + '<br>'; |
|
783 it = it.next; |
|
784 } |
|
785 return res; |
|
786 }); |
|
787 </code> |
|
788 </pre> |
|
789 <p> |
|
790 The above query uses the following facts: |
|
791 <ul> |
|
792 <li>java.lang.System has static field by name 'props' of type java.util.Properties. |
|
793 <li>java.util.Properties has field by 'table' of type java.util.Hashtable$Entry |
|
794 (this field is inherited from java.util.Hashtable). This is the hashtable |
|
795 buckets array. |
|
796 <li>java.util.Hashtable$Entry has 'key', 'value' and 'next' fields. Each |
|
797 entry points the next entry (or null) in the same hashtable bucket. |
|
798 <li>java.lang.String class has 'value' field of type char[]. |
|
799 </ul> |
|
800 <p> |
|
801 <b>Note that this query (and many other queries) may not be stable - because |
|
802 private fields of Java platform classes may be modified/removed without any |
|
803 notification! (implementation detail)</b>. But, using such queries on user |
|
804 classes may be safe - given that user has the control over the classes. |
|
805 </p> |
|
806 |
|
807 </body> |
|
808 </html> |
|