Wednesday, April 2, 2008

"Hacking" JHat API to integrate it to my application

Those that already used jhat may say: "JHat API? I thought it was just a java tool that comes with JDK 6."
I'll explain.

JHat (Java Heap Analysis Tool) is an experimental tool that comes with JDK 6. It can parse a heap dump file (HPROF format) and provide a simple http server (port 7000 as default) where we can execute queries in a simple SQL like language that has some predefined functions.

No big deal so far. All that is documented. A while ago I needed to integrate a memory inspection tool in a Java application that I was developing. I know there are few tools to do that externally but I wanted do memory inspection from a menu option in my application.

Although jhat is available as a command line tool, actually its classes are in the tools.jar file. So, I thought I could try do integrate that with my app. I tried to google some javadocs on jhat. Couldn’t find it. The tool is experimental, I forgot that.

Thanks to decompilers I could see how to start up the query engine. I extracted the code and could adapt it to my needs in my application.

I’ve tried to write the examples in a more didactic method in order to be more understandable. I hope I’ve put it in an easy way.

In order to run the example you would need an HPROF file. There are some ways to obtain a heap dump. The easiest (I think) is to run jmap and get the file dump.

Memory inspection done this way is not real time, since we are analyzing a snapshot of memory. But that helped me a lot. Remember that this is a heavy process that may consume lots of memory.

  1. Run jps to find out the PID of the Java application to take the memory snapshot
  2. Now run: jmap –dump:fomat=b,file=myheapdump.bin
  3. Now: java JHatExample myheapdump.bin

In case of out of memory errors when running the example use the –Xmx option:

java –Xmx512m JHatQueryExample myheapdump.bin

The example consists in three classes:
  • JHatExample: The GUI code
  • JHatWrapper: A class that wraps the access to the jhat API
  • MyQueryVisitor: Implementation of the jhat’s ObjectVisitor interface that provides a call back method on the results of the query.
Running the code will show the following GUI:

With the same query from the picture, if you click execute it will show all referrers to all instances of
Actually the way I print the result of the query is quite confusing...
If anybody ever happen to try to run the code, there is a good link on constructing queries in Sundarajan's blog with nice examples. The code I provided makes some calls to the javascript library that is provided with JHat.
If you uncompress the tools.jar file you may find that library and the help page in:

The purpose of this code is to show the possibility to integrate jhat usage into your application. Normally it is used as a stand alone tool. The stand alone tool is ready to use, but is a side tool that you have to open. What I did in my app (not the one shown here) was to automate the memory dump via a Runtime.exec call to jmap, and then the resulting file was used as a parameter to instatiate the jhat engine.

Since jhat is an experimental tool, it may completely change or become unavailable on Java 7. Use it like I did at your own risk.

Have fun playing with the code!

The GUI Code:

import java.awt.*;
import javax.swing.*;

public class JHatExample extends JFrame {
private JHatWrapper jhat;

public JHatExample(JHatWrapper jhat) {
super("JHat wrapper");
this.jhat = jhat;

private void initComponents() {
final JTextArea queryText = new JTextArea();
JPanel buttonPanel = new JPanel();
JButton executeBtn = new JButton("Execute");
this.add(new JScrollPane(queryText),BorderLayout.CENTER);
executeBtn.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent e) {
try {
} catch (Exception e1) {
JOptionPane.showMessageDialog(JHatExample.this, "Error executing query");

public static void main(String[] args) throws Exception {
if (args.length == 0 || ! new File(args[0]).exists()) {
System.out.println("The program must take a valid file path as parameter");
JHatWrapper jhat = new JHatWrapper(args[0]);
JHatExample frame = new JHatExample(jhat);

Now the wrapper class:

public class JHatWrapper {
private OQLEngine engine;

public JHatWrapper(String s) throws Exception {
PositionDataInputStream positiondatainputstream =
new PositionDataInputStream(new BufferedInputStream(new FileInputStream(s)));
int l;
Snapshot snapshot;
l = positiondatainputstream.readInt();
//I "inferred" the meaning of the parameters below by comparing the decompiled code
//and jhat's command line parameters
int debuglevel = 0;
//Don't know what this is...
int j =1;
HprofReader hprofreader = new HprofReader(s, positiondatainputstream,
j, true, debuglevel);
snapshot =;
//resolve references
engine = new OQLEngine(snapshot);

public void query(String query) throws Exception {
engine.executeQuery(query, new MyQueryVisitor(engine) );

And the Visitor code:

import java.util.Enumeration;


public class MyQueryVisitor implements ObjectVisitor {
private OQLEngine engine;

public MyQueryVisitor(OQLEngine engine) {
this.engine = engine;

public boolean visit(Object obj) {
try {
Object iterator ="wrapIterator",new Object[]{obj});
//Handles result items that are instance of enumeration. Ex: select referrers(x) from x
if (iterator instanceof Enumeration) {
} else {
//handles single result items. Ex: select x from x
JavaHeapObject javaObj = (JavaHeapObject)"unwrapJavaObject",new Object[]{obj});
} catch (Exception e) {
return false;
void handleEnumeration(Enumeration en) {
while (en.hasMoreElements()) {
try {
Object obj = en.nextElement();
JavaHeapObject unwrapped = (JavaHeapObject)"unwrapJavaObject",new Object[]{obj});
} catch (Exception e) {

1 comment:

Max Max said...

well done,
that's what I need.
I will try it.