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 @@ - - - -
- --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. -
- -
-
- select s from java.lang.String s where s.value.length >= 100
-
-
-
-
- select a from [I a where a.length >= 256
-
-
-
-
- select s.value.toString() from java.lang.String s
- where /java/.test(s.value.toString())
-
-
-
-
- select file.path.value.toString() from java.io.File file
-
-
-
-
- select classof(cl).name
- from instanceof java.lang.ClassLoader cl
-
-
-
-
- select o from instanceof 0xd404b198 o
-
-
-Note that 0xd404b198 is id of a Class (in a session). This is found by
-looking at the id shown in that class's page.
-
-
- heap.forEachClass(callback);
-
-
-
-
- heap.forEachObject(callback, clazz, includeSubtypes);
-
-
-clazz
is the class whose instances are selected. If not specified, defaults to java.lang.Object. includeSubtypes
is a boolean flag
-that specifies whether to include subtype instances or not. Default value of
-this flag is true.
-
-
-
- heap.findClass(className);
-
-
-where className
is name of the class to find. The resulting Class
-object has following properties:
-
-
- heap.findObject(stringIdOfObject);
-
-
-
-
-
- heap.objects(clazz, [includeSubtypes], [filter])
-
-
-clazz
is the class whose instances are selected. If not specified, defaults to java.lang.Object. includeSubtypes
is a boolean flag
-that specifies whether to include subtype instances or not. Default value of
-this flag is true. This method accepts an optional filter expression to filter
-the result set of objects.
-
-
-
- select heap.livepaths(s) from java.lang.String s
-
-
-Each element of this array itself is another array. The later array is
-contains an objects that are in the 'reference chain' of the path.
-
-
- select heap.findClass("java.lang.System").statics.props
-
-
-
-
- select heap.findClass("java.lang.String").fields.length
-
-
-
-
- select heap.findObject("0xf3800b58")
-
-
-
-
- select filter(heap.classes(), "/java.net./.test(it.name)")
-
-
-
-
- select classof(o).name from instanceof java.lang.ref.Reference o
-
-
-
- select heap.findClass("java.io.InputStream").subclasses()
-
-
-
- select heap.findClass("java.io.BufferedInputStream").superclasses()
-
-
--Returns whether two given Java objects are identical or not. -
-Example: -
-
- select identical(heap.findClass("Foo").statics.bar, heap.findClass("AnotherClass").statics.bar)
-
-
-
-
--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
-
-
-
-
--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: -
-
- select reachables(p) from java.util.Properties p
-
-
-
-
- select reachables(u, 'java.net.URL.handler') from java.net.URL u
-
-
--Returns an enumeration of Java objects that hold reference to a given Java -object. -
-Examples: -
-
- select count(referrers(o)) from java.lang.Object o
-
-
-
-
- select referrers(f) from java.io.File f
-
-
-
-
- select u from java.net.URL u where count(referrers(u)) > 2
-
-
--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"))
-
-
-
-
--Returns whether first Java object refers to second Java object or not. -
- - --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. -
- - -
-
- select sizeof(o) from [I o
-
-
-
-
-
-
- select "<b>" + toHtml(o) + "</b>" from java.lang.Object o
-
-
-
--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
-
-
-
--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. -
- --Concatenates two arrays or enumerations (i.e., returns composite -enumeration). -
- - --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. -
-
-
- select p from java.util.Properties p
- where contains(referrers(p), "classof(it).name == 'java.lang.Class'")
-
-
-
-
--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. -
-
-
- select count(heap.classes(), "/java.io./.test(it.name)")
-
-
-
-
--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. -
-
-
- select filter(heap.classes(), "/java.io./.test(it.name)")
-
-
-
-
- select filter(referrers(u), "! /java.net./.test(classof(it).name)")
- from java.net.URL u
-
-
--length function returns number of elements of an array/enumeration. -
- - --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)")
-
-
-
-
--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: -
-
-
- select max(map(heap.objects('java.lang.String', false), 'it.value.length'))
-
-
-
-
- select max(heap.objects('java.lang.String'), 'lhs.value.length > rhs.value.length')
-
-
--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: -
-
-
- select min(map(heap.objects('java.util.Vector', false), 'it.elementData.length'))
-
-
-
-
- select min(heap.objects('java.util.Vector'), 'lhs.elementData.length < rhs.elementData.length')
-
-
-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: -
-
-
- select sort(heap.objects('[C'), 'sizeof(lhs) - sizeof(rhs)')
-
-
-
-
- select map(sort(heap.objects('[C'), 'sizeof(lhs) - sizeof(rhs)'), '{ size: sizeof(it), obj: it }')
-
-
--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
-
-
-
-
-
--This function returns an array that contains elements of the input -array/enumeration. -
- - --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'))
-
-
-
-
-
- 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. -
- -
-
- 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. -
- -
-
- 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. -
- - -