Java Call Trace to UML Sequence Diagram Files

 ************************************************************************************
 * Copyright 2009 Syed Ali Jafar Naqvi												*
 *																					*
 * This file is part of Java Call Tracer.											*
 *																					*
 * Java Call Tracer is free software: you can redistribute it and/or modify			*
 * it under the terms of the Lesser GNU General Public License as published by		*
 * the Free Software Foundation, either version 3 of the License, or				*
 * (at your option) any later version.												*
 *																					*
 * Java Call Tracer is distributed in the hope that it will be useful,				*
 * but WITHOUT ANY WARRANTY; without even the implied warranty of					*
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the					*
 * Lesser GNU General Public License for more details.								*
 *																					*
 * You should have received a copy of the Lesser GNU General Public License			*
 * along with Java Call Tracer.  If not, see <http://www.gnu.org/licenses/>.		*
 ************************************************************************************

When to use the tool
--------------------
This is a reverse engineering tool for Java/J2EE programs. Lets say you are in a situation where you need to analyze a java program that was developed by someone else and there is not much documentation available about the program. Normally the way people work in such a situation is that they study the source code to understand its working. But this is a very time consuming and error prone process and generally the output is a sequence diagram. This tool takes that manual work and automates it, which saves a lot of time and effort.

This tool can also be used to do design validation after the coding phase of a project. So once all the code has been written I as an architect can just run the program and generate all the sequence diagrams from the working program and compare them to my design sequence diagram to check if the design was properly followed.


How to use the tool
-------------------
Once you have downloaded the tool and configured it as mentioned in "1, 2, 3 How to Install", you can start generating UML sequence diagrams. This tool is actually a combination of 2 tools
1] Calltracer
2] Calltrace2Seq

The Calltracer tool attaches to the JVM of your java program (while it is running) and records the call trace. This can then be printed out in XML or Text formats.

Once you have used the Calltracer tool to generate a XML output you can then use the Calltrace2Seq tool (which is a simple java program) to convert it to a UML sequence diagram. More details are available at "Using the Calltrace2Seq tool".

The sequence diagram will be generated in SVG format. You can read more about SVG at "How to see the SVG output from Calltrace2Seq".


1, 2, 3 of how to install the tool
------------------------------
1] Download the javacalltracer.zip and extract it's contents
2] Define a filter file using inclusive & exclusive filters
3] Run your java program with the JVM parameters as defined in the readme.txt file under the Calltracer folder

The output will be generated in XML format, you can then use the Calltrace2Seq tool to convert the XML to UML sequence diagram.

If you are using jdk1.4 please note that in addition to the steps mentioned above you will have to set the folder in which calltracer2.dll is placed in the Path of Windows and then restart your console. This is to avoid the error "Could not find -Xrun library: calltracer2.dll".


Using the Calltrace2Seq tool
----------------------------
Once you have generated a XML output using the calltracer tool you can use the Calltrace2Seq tool to convert it to a UML sequence diagram.

Incase your java program has a single thread the output of the calltracer tool will have just one thread element. You need to just take out the thread element, put it into a file and feed it to the Calltrace2Seq tool. You can choose to change the value of the id attribute of the thread element to a more legible value. The id element is used to name the sequence diagram by the Calltrace2Seq tool.

Incase your java program has multiple threads, you will find that the generated output has multiple Thread elements. Each thread element has the call trace coresponding to a thread of the program. You can either choose to take each thread element and convert it to a UML sequence diagram individually or you can use two or more thread elements to generate one UML sequence diagram. In the former case just take the thread element you are interested in, put it into a file and feed it to the Calltrace2Seq tool. In the later case just add a wrapper element around the thread elements and add an id attribute to the wrapper element and give a legible name. Then put the entire thing in a file and feed it to the Calltrace2Seq tool.

Please note that the output generated by the calltracer tool has some header information that will not allow it (the output) to be used directly as an input to the Calltrace2Seq tool. You can either copy the thread elements, as described above, into another file and feed it to the Calltrace2Seq tool or remove the header from the output file and use it directly.


How to see the SVG output from Calltrace2Seq
--------------------------------------------
SVG stands for Simple Vector Graphics, you can open the SVG file in your browser. If your sequence diagram is big you will see vertical and horizontal scroll bars in your browser, except if you are using IE. Incase you are using IE and you have a big sequence diagram you can scroll through the diagram by using the Alt key and your mouse.

Please note that the SVG output has some javascripts in it that come handy incase you have a big sequence diagram. For example if you are way down in your sequence diagram and you cannot see the Class elements you can simply click the call element you are interested in and you will be able to see the details right there.


Could not find -Xrun library: calltracer2.dll
---------------------------------------------
If you get an error "Could not find -Xrun library: calltracer2.dll" (with jdk 1.4) all you need to do is set the folder in which calltracer2.dll is placed in the Path of Windows and then restart your console.