Tuesday, December 22, 2009

Diving into the unknown

If you wanted to find out quickly the interplay of objects in a (Java) code base unknown to you, an elegant way to do it would be to use the DIVER perspective in Eclipse

This quick tutorial walks you through the important steps and some cool features of DIVER. As an aside, I had never played around with Eclipse earlier – having used Visual Studio and Intellij Idea in my previous life :) I’ll talk about some of the unique features of Eclipse that I encountered along the way. I used SQuirreL SQL as my representative project to test drive DIVER and see if I could make sense of the codebase quickly.

The first thing you need to do is to install the DIVER ‘perspective’. We’ll get to the concept of Eclipse perspectives in a minute. The first step is to extend the eclipse IDE with the DIVER perspective. The way to do this in the IDE is to select the option to install new software and then copy-paste the URL of DIVER from their website.





You need to follow the wizard steps but that’s straightforward.

Once the install is done, you can open the DIVER perspective. In Eclipse, a perspective seems to represent a logical collection of views which will help you achieve the goal of the perspective. For example, you have a Debug perspective which will show you your regular debugging aids everyone’s familiar with – call stack window, breakpoints & variables view etc. Similarly in the DIVER perspective, you have the program traces view, the sequence window, the sequence outline and so on. You can come to a perspective from the Window->Open Perspective menu option. Once opened, the list of open perspectives appears as a toolbar at the top. As you get comfortable, you can compact the view to show only the perspective icons.  Also, as you work your way around the perspective, you tend to re-arrange windows and if you might find it difficult to locate a specific window, then the reset perspective option from the Windows menu should help you restore your sanity!


The default DIVER perspective looks like this:




Now, that you have the DIVER perspective installed, the next step would be to get the SQuirreL SQL sources into your workspace. In Eclipse jargon, a workspace represents a physical location on the file system and can contain multiple projects. You can create working sets to filter out what you want to see in the package explorer. To get integration with a source control repository, you would need to install a SVN perspective or a CVS perspective installed just like we did for DIVER.  That’s cool as you use the same UI paradigm for disparate set of tasks. To that extent I am guessing that the Eclipse framework is really bare-bones. The value-add comes from all the installed perspectives. The other nice thing I liked about the SVN/CVS perspective was that you could just paste the connection string from sourceforge websites and that would be automatically mapped to a connection object. Neat! Paste the SQuirreL SQL connection string and checkout the sources into an eclipse project (Identify the folder in the sources which has a .project extension and you will automatically get that recognized in Eclipse as a suitable project to create). 


Now that we are all setup, let us run SQuirreL SQL. For that, switch to the Java perspective and create a new 'Run configuration' under Java application (Run -> Run Configurations. Select Java application from the tree and click on New.)





You need to fill in the main class section. Since you don’t really understand this codebase, typically you would search for the main class and then filter on the key-word ‘main’ to guess which would be the right class.




While, we are at it, you may want to create a new configuration for the Java application trace. This will be used by DIVER as well when we enter the DIVER perspective.




Run the squirrel configuration and you should see the application up and running. Now, let’s close the application and go back to the DIVER perspective. Let’s run the squirreltrace configuration just created.The way DIVER works is that it logs all the interesting events in the system and then uses that information to build up a sequence view of the interested path. To use it effectively (Tracing slows the application down), tracing is paused by default. The recommended way to use this tool is to figure out the workflow you are interested in understanding (from a code-perspective). And only trace out that section.


For pedagogical reasons, let us try to understand the code structure for saving SQuirreL SQL preferences. To that extent, we will focus on the workflow for changing the SQL login timeout from 30 seconds to 45 seconds in the global preferences dialog.






To start off a DIVER trace, run the application trace configuration created previously




After the application launches and you have clicked on the global preferences menu, start a trace, change the timeout in the application and then stop a trace.  Do keep in mind that the trace configuration defaults to paused on start. So if you need to see a trace, then you would need to resume it at the interesting points in your application workflow.






Once you have collected the trace information, it’s time to analyze the trace! This is where it gets interesting!

You need to go the Program Traces view, select the trace data you have just collected and activate it



Activating a trace filters methods and classes used in this particular sequence in the Package Explorer. This is extremely good feature to have because even simple traces have an overwhelming amount of information and you need to use the package view and the sequence view together to discover what you are searching for.


Since, we are on the UI thread, most of the fun happens on the AWT-EventQueue-0 thread. So we open up the sequence viewer for that thread.  You notice after expanding a few nodes that the only events in the system are generic java events and they give you real clue on how to move ahead. Unless you have the patience to expand out each and every node or expand all activations (Which could take a while!)



That’s where you need to use the various views in the DIVER perspective effectively. You know you are dealing with a textbox widget and you open the src/ui folders. Notice that this view is already filtered out based on what we have traced. So you are guaranteed that all these methods/classes are going to be used in the sequence diagram. The IntegerField class looks interesting and seems to be a possible candidate to start the exploration.  You can reveal the sequence around this class by using the reveal-in feature




Voila! This expands the sequence diagram to take you to the interesting part of the sequence viewer.



Also, note that you have a small blue line in the time line bar. They represent calls to methods of that class on the timeline. You can center on that particular occurrence in the following way



If you find that this looks messy. If you want you can filter out further. Notice the small W on the top of the window. If you click it, you are shown a hierarchy of packages which you can collapse out in your sequence diagram.



For example, you can filter out the javax.* classes. With some measured filtering, the sequence diagram reduces to



 The tool also allows you see the corresponding code for the clicks you are making in the sequence viewer




As an aside, the other interesting feature is that you can use the up/down arrow keys to quickly find the next occurrence of an activity on a selected lifeline.

That’s a quick roundup and a motivation to use a tool like this. The detailed tutorial for DIVER is here and the author’s blog is here.

This tool does a great job in giving you the ability to filter away un-interesting parts of the sequence diagram - to reduce the noise - so that you can quickly come to the classes and interactions which matter. Having the reveal-in feature and the markings on the timeline allow you to understand the code-structure starting from the classes which could possibly be interesting.

Give it a spin in the (java) sources you want to understand!



It's been a while

since I blogged last. Hope this time around I will be more regular :)