0N/ACopyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 2362N/Aunder the terms of the GNU General Public License version 2 only, as 0N/Apublished by the Free Software Foundation. Sun designates this 2362N/Aparticular file as subject to the "Classpath" exception as provided 0N/Aby Sun in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A.key { color: red; font-weight: bold }
0N/AObject Query Language (OQL)
0N/A<
h1>Object Query Language (OQL)</
h1>
0N/AOQL is SQL-like query language to query Java heap. OQL allows to
filter/
select information
0N/Awanted from Java heap. While pre-defined queries such as "show all instances of class X"
0N/Aare already supported by HAT, OQL adds more flexibility. OQL is based on JavaScript expression
0N/AOQL query is of the form
0N/A <
span class="key">select</
span> <JavaScript expression to select>
0N/A [ <
span class="key">from</
span> [<
span class="key">instanceof</
span>] <class name> <identifier>
0N/A [ <
span class="key">where</
span> <JavaScript boolean expression to filter> ] ]
0N/Awhere class name is fully qualified Java class name (example:
java.
net.
URL) or array class name.
0N/ANote that fully qualified class name does not always uniquely identify a
0N/AJava class at runtime. There may be more than one Java class with the same
0N/Aname but loaded by different loaders. So, class name is permitted to be
0N/Aid string of the class object.
0N/AIf <
span class="key">instanceof</
span> keyword is used, subtype objects are selected. If this
0N/Akeyword is not specified, only the instances of exact class specified are selected. Both
0N/A<
span class="key">from</
span> and <
span class="key">where</
span> clauses are optional.
0N/AIn <
span class="key">select</
span> and (optional) <
span class="key">where</
span> clauses, the expression
0N/Aused in JavaScript expression. Java heap objects are wrapped as convenient script objects so that
0N/Afields may be accessed in natural syntax. For example, Java fields can be accessed with
obj.field_name 0N/Asyntax and array elements can be accessed with array[index] syntax. Each Java object selected is
0N/Abound to a JavaScript variable of the identifier name specified in <
span class="key">from</
span> clause.
0N/A<
h2>OQL Examples</
h2>
0N/A<
li>select all Strings of length 100 or more
0N/A<
li>select all int arrays of length 256 or more
0N/A<
li>show content of Strings that match a regular expression
0N/A<
li>show path value of all File objects
0N/A<
li>show names of all ClassLoader classes
0N/A select <
a href="#classof">classof</
a>(cl).name
0N/A<
li>show instances of the Class identified by given id string
0N/A select o from instanceof 0xd404b198 o
0N/ANote that 0xd404b198 is id of a Class (in a session). This is found by
0N/Alooking at the id shown in that class's page.
0N/A<
h2>OQL built-in objects, functions</
h2>
0N/AThe <
b>heap</
b> built-in object supports the following methods:
0N/A<
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
0N/Athat specifies whether to include subtype instances or not. Default value of
0N/A<
a name="findClass"></
a>
0N/Awhere <
code>className</
code> is name of the class to find. The resulting Class
0N/Aobject has following properties:
0N/A<
li>name - name of the class.
0N/A<
li>statics - name, value pairs for static fields of the Class.
0N/A<
li>fields - array of field objects. field object has name, signature
0N/A<
li>loader - ClassLoader object that loaded this class.
0N/A<
li>signers - signers that signed this class.
0N/A<
li>protectionDomain - protection domain to which this class belongs.
0N/AClass objects have the following methods:
0N/A<
li>isSubclassOf - tests whether given class is direct or indirect
0N/Asubclass of this class or not.
0N/A<
li>isSuperclassOf - tests whether given Class is direct or indirect
0N/Asuperclass of this class or not.
0N/A<
li>subclasses - returns array of direct and indirect subclasses.
0N/A<
li>superclasses - returns array of direct and indirect superclasses.
0N/A<
a name="findObject"></
a>
0N/A<
a name="classes"></
a>
0N/A<
a name="objects"></
a>
0N/A<
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
0N/Athat specifies whether to include subtype instances or not. Default value of
0N/Athis flag is true. This method accepts an optional filter expression to filter
0N/Athe result set of objects.
0N/A<
a name="finalizables"></
a>
0N/Apending to be finalized.
0N/Ais alive. This method accepts optional second parameter that is a boolean
0N/Aflag. This flag tells whether to include paths with weak reference(s) or not.
0N/ABy default, paths with weak reference(s) are not included.
0N/AEach element of this array itself is another array. The later array is
0N/Acontains an objects that are in the 'reference chain' of the path.
0N/A<
li><
b>
heap.roots</
b> -- returns an Enumeration of Roots of the heap.
0N/A<
a name="rootobj"></
a>
0N/AEach Root object has the following properties:
0N/A<
li>id - String id of the object that is referred by this root
0N/A<
li>type - descriptive type of Root (JNI Global, JNI Local, Java Static etc)
0N/A<
li>description - String description of the Root
0N/A<
li>referrer - Thread Object or Class object that is responsible for this root or null
0N/A<
li> find the object whose object id is given
0N/A<
h3>functions on individual objects</
h3>
0N/A<
li><
a href="#allocTrace">allocTrace(jobject)</
a>
0N/A<
li><
a href="#classof">classof(jobject)</
a>
0N/A<
li><
a href="#forEachReferrer">forEachReferrer(callback, jobject)</
a>
0N/A<
li><
a href="#identical">identical(o1, o2)</
a>
0N/A<
li><
a href="#objectid">objectid(jobject)</
a>
0N/A<
li><
a href="#reachables">reachables(jobject, excludedFields)</
a>
0N/A<
li><
a href="#referrers">referrers(jobject)</
a>
0N/A<
li><
a href="#referees">referees(jobject)</
a>
0N/A<
li><
a href="#refers">refers(jobject)</
a>
0N/A<
li><
a href="#root">root(jobject)</
a>
0N/A<
li><
a href="#sizeof">sizeof(jobject)</
a>
0N/A<
li><
a href="#toHtml">toHtml(obj)</
a>
0N/A<
a name="allocTrace"></
a>
0N/A<
h4>allocTrace function</
h4>
0N/AThis returns allocation site trace of a given Java object if available.
0N/AallocTrace returns array of frame objects. Each frame object has the following
0N/A<
li>className - name of the Java class whose method is running in the frame.
0N/A<
li>methodName - name of the Java method running in the frame.
0N/A<
li>methodSignature - signature of the Java method running in the frame.
0N/A<
li>sourceFileName - name of source file of the Java class running in the frame.
0N/A<
li>lineNumber - source line number within the method.
0N/A<
a name="classof"></
a>
0N/A<
h4>classof function</
h4>
0N/AReturns Class object of a given Java Object. The result object supports the
0N/Afollowing properties:
0N/A<
li>name - name of the class.
0N/A<
li>statics - name, value pairs for static fields of the Class.
0N/A<
li>fields - array of field objects. Field objects have name, signature
0N/A<
li>loader - ClassLoader object that loaded this class.
0N/A<
li>signers - signers that signed this class.
0N/A<
li>protectionDomain - protection domain to which this class belongs.
0N/AClass objects have the following methods:
0N/A<
li>isSubclassOf - tests whether given class is direct or indirect
0N/Asubclass of this class or not.
0N/A<
li>isSuperclassOf - tests whether given Class is direct or indirect
0N/Asuperclass of this class or not.
0N/A<
li>subclasses - returns array of direct and indirect subclasses.
0N/A<
li>superclasses - returns array of direct and indirect superclasses.
0N/A<
li>show class name of each Reference type object
0N/A<
a name="forEachReferrer"></
a>
0N/A<
h4>forEachReferrer function</
h4>
0N/Acalls a callback function for each referrer of a given Java object.
0N/A<
a name="identical"></
a>
0N/A<
h4>identical function</
h4>
0N/AReturns whether two given Java objects are identical or not.
0N/A<
a name="objectid"></
a>
0N/A<
h4>objectid function</
h4>
0N/AReturns String id of a given Java object. This id can be passed to
0N/Aobjects for identity.
0N/A<
a name="reachables"></
a>
0N/A<
h4>reachables function</
h4>
0N/AReturns an array of Java objects that are transitively referred from the
0N/Agiven Java object. Optionally accepts a second parameter that is comma
0N/Aseparated field names to be excluded from reachability computation.
0N/A<
li>print all reachable objects from each Properties instance.
0N/A<
li>print all reachables from each
java.
net.
URL but omit the objects reachable
0N/Avia the fields specified.
0N/A<
a name="referrers"></
a>
0N/A<
h4>referrers function</
h4>
0N/AReturns an enumeration of Java objects that hold reference to a given Java
0N/A<
li>print URL objects only if referred by 2 or more
0N/A<
a name="referees"></
a>
0N/A<
h4>referees function</
h4>
0N/AReturns an array of Java objects to which the given Java
0N/Aobject directly refers to.
0N/AExample: to print all static reference fields of
java.
io.
File class
0N/A<
a name="refers"></
a>
0N/A<
h4>refers function</
h4>
0N/AReturns whether first Java object refers to second Java object or not.
0N/A<
h4>root function</
h4>
0N/AIf given object is a member of root set of objects, this function returns
0N/Aa descriptive <
a href="#rootobj">Root object</
a> describing why it is so.
0N/AIf given object is not a root, then this function returns null.
0N/A<
a name="sizeof"></
a>
0N/A<
h4>sizeof function</
h4>
0N/AReturns size of the given Java object in bytes
0N/A select sizeof(o) from [I o
0N/A<
a name="toHtml"></
a>
0N/A<
h4>toHtml function</
h4>
0N/AReturns HTML string for the given Java object. Note that this is called
0N/Aautomatically for objects selected by select expression. But, it may be useful
0N/Ato print more complex output.
0N/AExample: print hyperlink in bold font weight
0N/A<
h3>Selecting multiple values</
h3>
0N/AMultiple values can be selected using JavaScript object literals or arrays.
0N/AExample: show name and thread for each thread object
0N/Aexpression string [or a callback function] as input. These functions iterate
0N/Aeach element. Note that JavaScript objects are associative arrays. So,
0N/Athese functions may also be used with arbitrary JavaScript objects.
0N/A<
a name="concat"></
a>
0N/A<
h4>concat function</
h4>
0N/AConcatenates two arrays or enumerations (
i.e., returns composite
0N/A<
a name="contains"></
a>
0N/A<
h4>contains function</
h4>
0N/Athe given boolean expression specified in code. The code evaluated
0N/Acan refer to the following built-in variables.
0N/A<
li>it -> currently visited element
0N/A<
li>index -> index of the current element
0N/AExample: select all Properties objects that are referred by
0N/Asome static field some class.
0N/A where contains(<
a href="#referrers">referrers</
a>(p), "<
a href="#classof">classof</
a>(it).name == '
java.
lang.
Class'")
0N/A<
h4>count function</
h4>
0N/Athat satisfy the given boolean expression. The boolean expression code can
0N/Arefer to the following built-in variables.
0N/A<
li>it -> currently visited element
0N/A<
li>index -> index of the current element
0N/AExample: print number of classes that have specific name pattern
0N/A<
a name="filter"></
a>
0N/A<
h4>filter function</
h4>
0N/Aexpression. The boolean expression code can refer to the following built-in
0N/A<
li>it -> currently visited element
0N/A<
li>index -> index of the current element
0N/A<
li> show all referrers of URL object where the referrer is not from
0N/A select filter(<
a href="#referrers">referrers</
a>(u), "! /
java.net./(<
a href="#classof">classof</
a>(it).name)")
0N/A<
a name="length"></
a>
0N/A<
h4>length function</
h4>
0N/A<
h4>map function</
h4>
0N/Aon each element. The code evaluated can refer to the following built-in
0N/A<
li>it -> currently visited element
0N/A<
li>index -> index of the current element
0N/AExample: show all static fields of
java.
io.
File with name and value
0N/A<
h4>max function</
h4>
0N/AOptionally accepts code expression to compare elements of the array.
0N/ABy default numerical comparison is used. The comparison expression can
0N/Ause the following built-in variables:
0N/A<
li>lhs -> left side element for comparison
0N/A<
li>rhs -> right side element for comparison
0N/A<
li>find the maximum length of any String instance
0N/A<
li>find string instance that has the maximum length
0N/A<
h4>min function</
h4>
0N/Aaccepts code expression to compare elements of the array. By default numerical
0N/Acomparison is used. The comparison expression can use the following built-in
0N/A<
li>lhs -> left side element for comparison
0N/A<
li>rhs -> right side element for comparison
0N/A<
li>find the minimum size of any Vector instance
0N/A<
li>find Vector instance that has the maximum length
0N/A<h4>sort function</h4> 0N/Acompare elements of the array. By default numerical comparison is used. 0N/AThe comparison expression can use the following built-in variables: 0N/A<li>lhs -> left side element for comparison 0N/A<li>rhs -> right side element for comparison 0N/A<li> print all char[] objects in the order of size. 0N/A select sort(<a href="#objects">heap.objects</a>('[
C'), '<a href="#sizeof">sizeof</
a>(lhs) - sizeof(rhs)')
0N/A<
li> print all char[] objects in the order of size but print
0N/A 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 }')
0N/A<
h4>sum function</
h4>
0N/AThis function returns the sum of all the elements of the given input array or
0N/Aenumeration. Optionally, accepts an expression as second param. This is used
0N/Ato map the input elements before summing those.
0N/AExample: return sum of sizes of the reachable objects from each Properties object
0N/A select sum(<
a href="#map">map</
a>(<
a href="#reachables">reachables</
a>(p), '<
a href="#sizeof">sizeof</
a>(it)'))
0N/A // or omit the map as in ...
0N/A select sum(<
a href="#reachables">reachables</
a>(p), '<
a href="#sizeof">sizeof</
a>(it)')
0N/A<
a name="toArray"></
a>
0N/A<
h4>toArray function</
h4>
0N/AThis function returns an array that contains elements of the input
0N/A<
a name="unique"></
a>
0N/A<
h4>unique function</
h4>
0N/AExample: select unique char[] instances referenced from Strings. Note that
0N/Amore than one String instance can share the same char[] for the content.
0N/A // number of unique char[] instances referenced from any String
0N/A // total number of Strings
0N/A<
h3>More complex examples</
h3>
0N/A<
h4>Print histogram of each class loader and number of classes loaded by it</
h4>
0N/A 'toHtml(
it) +
"<br>"') 0N/Aprivate field named <b>elementCount</b> that is number of elements in the 0N/Avector. We select multiple values (loader, count) using JavaScript object 0N/Aliteral and map function. We sort the result by count (i.e., number of classes 0N/Aloaded) using sort function with comparison expression. 0N/A<h4>Show parent-child chain for each class loader instance</h4> 0N/A while (it != null) { 0N/A res += toHtml(it) + "->"; 0N/A return res + "<br>"; 0N/Aand walk until parent is null using the callback function to map call. 0N/A<h4>Printing value of all System properties</h4> 0N/A while (it != null) { 0N/AThe above query uses the following facts: 0N/Aentry points the next entry (or null) in the same hashtable bucket. 0N/A<b>Note that this query (and many other queries) may not be stable - because 0N/Anotification! (implementation detail)</b>. But, using such queries on user 0N/Aclasses may be safe - given that user has the control over the classes.