| author | chegar |
| Sun, 17 Aug 2014 15:54:13 +0100 | |
| changeset 25859 | 3317bb8137f4 |
| parent 23010 | jdk/src/share/classes/com/sun/tools/hat/resources/oqlhelp.html@6dadb192ad81 |
| permissions | -rw-r--r-- |
| 2 | 1 |
<!-- |
|
23010
6dadb192ad81
8029235: Update copyright year to match last edit in jdk8 jdk repository for 2013
lana
parents:
19222
diff
changeset
|
2 |
Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. |
| 2 | 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 |
|
| 5506 | 7 |
published by the Free Software Foundation. Oracle designates this |
| 2 | 8 |
particular file as subject to the "Classpath" exception as provided |
| 5506 | 9 |
by Oracle in the LICENSE file that accompanied this code. |
| 2 | 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 |
||
|
5551
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
21 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
22 |
or visit www.oracle.com if you need additional information or have any |
|
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
23 |
questions. |
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
82 |
select s from java.lang.String s where s.value.length >= 100 |
| 2 | 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 |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
95 |
where /java/.test(s.value.toString()) |
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
239 |
select <a href="#filter">filter</a>(heap.classes(), "/java.net./.test(it.name)") |
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
538 |
select count(<a href="#classes">heap.classes()</a>, "/java.io./.test(it.name)") |
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
561 |
select filter(<a href="#classes">heap.classes</a>(), "/java.io./.test(it.name)") |
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
568 |
select filter(<a href="#referrers">referrers</a>(u), "! /java.net./.test(<a href="#classof">classof</a>(it).name)") |
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
621 |
select max(map(heap.objects('java.lang.String', false), 'it.value.length'))
|
| 2 | 622 |
</code> |
623 |
</pre> |
|
624 |
<li>find string instance that has the maximum length |
|
625 |
<pre> |
|
626 |
<code> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
627 |
select max(heap.objects('java.lang.String'), 'lhs.value.length > rhs.value.length')
|
| 2 | 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> |
|
|
19222
19707772a06c
8022483: Nashorn compatibility issues in jhat's OQL feature
sundar
parents:
5551
diff
changeset
|
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'),
|
| 2 | 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> |