diff -r d6ec6a7db09c -r 1286226d1236 jdk/src/jdk.dev/share/classes/com/sun/tools/hat/resources/oqlhelp.html --- a/jdk/src/jdk.dev/share/classes/com/sun/tools/hat/resources/oqlhelp.html Thu May 21 10:07:38 2015 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,808 +0,0 @@ - - - - - - -Object Query Language (OQL) - - - -

Object Query Language (OQL)

- -

-OQL is SQL-like query language to query Java heap. OQL allows to filter/select information -wanted from Java heap. While pre-defined queries such as "show all instances of class X" -are already supported by HAT, OQL adds more flexibility. OQL is based on JavaScript expression -language. -

- -

-OQL query is of the form - -

-
-         select <JavaScript expression to select>
-         [ from [instanceof] <class name> <identifier>
-         [ where <JavaScript boolean expression to filter> ] ]
-
-
-where class name is fully qualified Java class name (example: java.net.URL) or array class name. -[C is char array name, [Ljava.io.File; is name of java.io.File[] and so on. -Note that fully qualified class name does not always uniquely identify a -Java class at runtime. There may be more than one Java class with the same -name but loaded by different loaders. So, class name is permitted to be -id string of the class object. - -If instanceof keyword is used, subtype objects are selected. If this -keyword is not specified, only the instances of exact class specified are selected. Both -from and where clauses are optional. -

- - -

-In select and (optional) where clauses, the expression -used in JavaScript expression. Java heap objects are wrapped as convenient script objects so that -fields may be accessed in natural syntax. For example, Java fields can be accessed with obj.field_name -syntax and array elements can be accessed with array[index] syntax. Each Java object selected is -bound to a JavaScript variable of the identifier name specified in from clause. -

- -

OQL Examples

- - - -

OQL built-in objects, functions

- -

heap object

- -The heap built-in object supports the following methods: - - - -Examples: - - -

functions on individual objects

- - - - -

allocTrace function

- -This returns allocation site trace of a given Java object if available. -allocTrace returns array of frame objects. Each frame object has the following -properties: - - - -

classof function

- -Returns Class object of a given Java Object. The result object supports the -following properties: - -Class objects have the following methods: - - -Examples: - - - -

forEachReferrer function

- -calls a callback function for each referrer of a given Java object. - - -

identical function

-

-Returns whether two given Java objects are identical or not. -

-Example: -
-
-    select identical(heap.findClass("Foo").statics.bar, heap.findClass("AnotherClass").statics.bar)
-
-
- - -

objectid function

- -

-Returns String id of a given Java object. This id can be passed to -heap.findObject and may also be used to compare -objects for identity. -

-Example: -
-
-    select objectid(o) from java.lang.Object o
-
-
- - -

reachables function

-

-Returns an array of Java objects that are transitively referred from the -given Java object. Optionally accepts a second parameter that is comma -separated field names to be excluded from reachability computation. -Fields are written in class_name.field_name pattern. -

-Examples: - - - -

referrers function

-

-Returns an enumeration of Java objects that hold reference to a given Java -object. -

-Examples: - - - -

referees function

-

-Returns an array of Java objects to which the given Java -object directly refers to. -

-Example: to print all static reference fields of java.io.File class -
-
-    select referees(heap.findClass("java.io.File"))
-
-
- - -

refers function

-

-Returns whether first Java object refers to second Java object or not. -

- - -

root function

-

-If given object is a member of root set of objects, this function returns -a descriptive Root object describing why it is so. -If given object is not a root, then this function returns null. -

- - -

sizeof function

- -Returns size of the given Java object in bytes -Example: -
-
-    select sizeof(o) from [I o
-
-
- - -

toHtml function

- -Returns HTML string for the given Java object. Note that this is called -automatically for objects selected by select expression. But, it may be useful -to print more complex output. - -Example: print hyperlink in bold font weight -
-
-    select "<b>" + toHtml(o) + "</b>" from java.lang.Object o
-
-
- -

Selecting multiple values

-

-Multiple values can be selected using JavaScript object literals or arrays. -

- -Example: show name and thread for each thread object -
-
-    select { name: t.name? t.name.toString() : "null", thread: t } 
-    from instanceof java.lang.Thread t
-
-
- -

array/iterator/enumeration manipulation functions

- -

-These functions accept an array/iterator/enumeration and an -expression string [or a callback function] as input. These functions iterate -the array/iterator/enumeration and apply the expression (or function) on -each element. Note that JavaScript objects are associative arrays. So, -these functions may also be used with arbitrary JavaScript objects. -

- - - - -

concat function

-

-Concatenates two arrays or enumerations (i.e., returns composite -enumeration). -

- - -

contains function

-

-Returns whether the given array/enumeration contains an element -the given boolean expression specified in code. The code evaluated -can refer to the following built-in variables. -

- -Example: select all Properties objects that are referred by -some static field some class. -
-
-    select p from java.util.Properties p
-    where contains(referrers(p), "classof(it).name == 'java.lang.Class'")
-
-
- - -

count function

-

-count function returns the count of elements of the input array/enumeration -that satisfy the given boolean expression. The boolean expression code can -refer to the following built-in variables. -

- -Example: print number of classes that have specific name pattern -
-
-    select count(heap.classes(), "/java.io./.test(it.name)")
-
-
- - -

filter function

-

-filter function returns an array/enumeration that contains elements -of the input array/enumeration that satisfy the given boolean -expression. The boolean expression code can refer to the following built-in -variables. -

- -Examples: - - - -

length function

-

-length function returns number of elements of an array/enumeration. -

- - -

map function

-

-Transforms the given array/enumeration by evaluating given code -on each element. The code evaluated can refer to the following built-in -variables. -

- -

-map function returns an array/enumeration of values created by repeatedly -calling code on each element of input array/enumeration. -

-Example: show all static fields of java.io.File with name and value -
-
-    select map(heap.findClass("java.io.File").statics, "index + '=' + toHtml(it)")
-
-
- - -

max function

-

-returns the maximum element of the given array/enumeration. -Optionally accepts code expression to compare elements of the array. -By default numerical comparison is used. The comparison expression can -use the following built-in variables: -

- -Examples: - - - -

min function

-

-returns the minimum element of the given array/enumeration. Optionally -accepts code expression to compare elements of the array. By default numerical -comparison is used. The comparison expression can use the following built-in -variables: -

- -Examples: - - - -

sort function

-

-sorts given array/enumeration. Optionally accepts code expression to -compare elements of the array. By default numerical comparison is used. -The comparison expression can use the following built-in variables: -

- -Examples: - - - -

sum function

-

-This function returns the sum of all the elements of the given input array or -enumeration. Optionally, accepts an expression as second param. This is used -to map the input elements before summing those. -

-Example: return sum of sizes of the reachable objects from each Properties object -
-
-    select sum(map(reachables(p), 'sizeof(it)')) 
-    from java.util.Properties p
-
-    // or omit the map as in ...
-    select sum(reachables(p), 'sizeof(it)') 
-    from java.util.Properties p
-
-
-
- - -

toArray function

-

-This function returns an array that contains elements of the input -array/enumeration. -

- - -

unique function

-

-This function returns an array/enumeration containing unique elements of the -given input array/enumeration -

-Example: select unique char[] instances referenced from Strings. Note that -more than one String instance can share the same char[] for the content. -
-
-   // number of unique char[] instances referenced from any String
-   select count(unique(map(heap.objects('java.lang.String'), 'it.value')))
-
-   // total number of Strings
-   select count(heap.objects('java.lang.String'))
-
-
- -

More complex examples

- -

Print histogram of each class loader and number of classes loaded by it

- -
-
-   select map(sort(map(heap.objects('java.lang.ClassLoader'), 
-   '{ loader: it, count: it.classes.elementCount }'), 'lhs.count < rhs.count'),
-   'toHtml(it) + "<br>"')
-
-
-

-The above query uses the fact that, java.lang.ClassLoader has a private -field called classes of type java.util.Vector and Vector has a -private field named elementCount that is number of elements in the -vector. We select multiple values (loader, count) using JavaScript object -literal and map function. We sort the result by count (i.e., number of classes -loaded) using sort function with comparison expression. -

- -

Show parent-child chain for each class loader instance

- -
-
-   select map(heap.objects('java.lang.ClassLoader'),
-      function (it) {
-         var res = '';
-         while (it != null) {
-            res += toHtml(it) + "->";
-            it = it.parent;
-         }
-         res += "null";
-         return res + "<br>";
-      })
-
-
-

-Note that we use parent field of java.lang.ClassLoader class -and walk until parent is null using the callback function to map call. -

- -

Printing value of all System properties

- -
-
-   select map(filter(heap.findClass('java.lang.System').statics.props.table, 'it != null'), 
-            function (it) {
-                var res = "";
-                while (it != null) {
-                    res += it.key.value.toString() + '=' +
-                           it.value.value.toString() + '<br>';
-                    it = it.next;
-                }
-                return res;
-            });
-
-
-

-The above query uses the following facts: -

-

-Note that this query (and many other queries) may not be stable - because -private fields of Java platform classes may be modified/removed without any -notification! (implementation detail). But, using such queries on user -classes may be safe - given that user has the control over the classes. -

- - -