The JDSL Visualizer 1.0

The visualizer is a tool for use with the Library of Data Structures for Java (jdsl) which is produced by the Center for Geometric Computing (geomlib) at Brown University. It is for use with java 1.1.x Virtual Machines, and utilizes the AWT and Networking packages.

0) What is the Visualizer?

1) User Interface Overview

2) Using the History Timeline

3) How to Visualize Your Data Structure

4) Data Structures currently implemented

5) Brief Tutorial

6) Other Frequently Asked Questions

7) Technical Note on Running the Visualizer with your Browser/ Virtual Machine

0) WHAT IS THE VISUALIZER?

The visualizer is a utility that allows you to graphically visualize many of the data structures used in jdsl. It can visualize the interactions of multiple structures at one time and keeps a history of the operations the user has performed on the data structures. It also has the capability to allow the outside user to add snapshots to the history in order to visualize algorithms.

It can be used either to visualize ref implementations of data structures, or can interface with students' implementations of the jdsl interfaces for teaching purposes, so long as the students implement a minimal subset of the methods of the interfaces needed.

1) USER INTERFACE OVERVIEW

1a) Running the Visualizer
The visualizer can be run in two methods: either from the command line or from inside code. It can be run in three fashions:

Standard:(prompts for initial data structure)

Unix Command line: jdslviz

PC Command line: jdslviz.bat

From code: new jdsltools.visualization.jdslviz("");

Invisible: (used if you do not wish the visualizer to prompt for a data structure upon startup, but instead to wait to be passed a data structure from outside) (see section 1h)

Unix Command line: jdslviz invisible

PC Command line:: jdslviz.bat invisible

From code: new jdsltools.visualization.jdslviz("invisible");

As an applet:

appletviewer jdslviz.html

or from your browser jdslviz.html (note: If running the visualizer from a browser, see section 7)

Setting your classpath:

Make sure that your java classpath includes the .jar files in the lib directories of both your jdsl-teach and jdsltools-teach release -- otherwise the visualizer may be unable to find essential classes.

Note:

If you wish for the visualizer to run in the smaller window size when created from code, set the environment variable VIZSIZE=SMALL. 1b) Choosing your data structure
When you add a data structure to the visualizer, the window that pops up prompts you for a visualizer type, a class name, and a name to refer to the structure by (if you allow it to remain as Default, it will be set to the type of structure you have chosen plus a number. It is important to note that you must choose the correct visualizer for your structure, that your structure must correctly implement the necessary interfaces to be visualized by that container visualizer (see that section of Help), and that the classname must be typed in format package.classname ; also note that your classpath must be set so that the visualizer can find your class.(If your package is BT, and is at /u/rsb/16/BT, then your classpath should include /u/rsb/16/

1c) The Visualizer window
The window you see in front of you has four sections. In the top-left we have the data structure which is currently active. At the top-right we have the timeline which represents the history of your structure. At its simplest, you can click and drag along it and the structure window will display your structure at an earlier point in time as you go up. At the bottom-left there is a panel of buttons with which you can interact with your chosen data structure, according to its interface. At the bottom-right, there is a panel that allows you to manipulate the items passed into and returned from your structure.

1d) Menus and menu options
The file menu allows you to quit or pop this window up. As you are looking at this window, it can be inferred you have figured this out. The containers menu allows you to visualize additional containers, delete the currently active container, or to switch which container is currently active by selecting it from the menu.

1e) The Error Window
All exceptions or errors that occur in your structure will appear in an error window.

1f) Selecting Nodes
A position or locator can be selected by clicking on it with the left mouse button. The selected node with turn yellow. For methods that require two nodes, you can select the second one with the right mouse button. It will turn orange.

1g) The locator display box (Heap and Red-Black Tree only)
In some containers, there is a box in the lower-right corner which displays the returned locator, when applicable. This is the locator referenced by such commands as insert(locator) and makeLocator. Click on it to select it.

1h) External interaction with the visualizer
Containers can be added to the visualizer by calling the method viz.VisualizationController.addContainer(Container c, String name);
A snapshot of the visualizer's current state can be taken by viz.VisualizationController.snapshot(java.awt.Color c);

2) USING THE HISTORY TIMELINE

2a) Basics
The bottom of the timeline has the most recent event -- the top of the timeline has the oldest event. Click and drag along the timeline to look at a different point in the history of your structure.

2b) Colors

Red: An event that occurred in the structure currently visible.

Blue: An event that occurred in a different structure

Green: The structure as it currently is.

Other colors: User defined 2c) Taking Snapshots
To take a snapshot of a specific moment in time for the visualizer, Add inside your code at the exact instant you wish the snapshot the line:
viz.VisualizationController.snapshot(java.awt.Color.gray);
(or whatever color you prefer, or leave it blank for default coloration)

3) HOW TO VISUALIZE YOUR OWN DATA STRUCTURE/ALGORITHM

3a) Visualizing Data Structures
You will only be able to visualize your own data structure if it conforms to one of the sets of interfaces discussed in the section at the end.

You must correctly implement the following methods for the visualizer's output to be remotely meaningful:
3a1)Sequence: first(),after()
3a2)Binary Tree: root(),leftChild(),rightChild(),isExternal()
3a3)Restructurable Binary Tree: same as BinaryTree
3a4)Heap: getBinaryTree() must return a valid BinaryTree.
3a5)Red-Black Tree:getBinaryTree() must return a valid BinaryTree.
3b) Visualizing Algorithms
To visualize the operation of an algorithm on a data structure, first make sure that data structure is visualizable. Then add the data structure(s) the alogirthm occurs on to the visualizer if they are not already inside it. You can do this with the command
viz.VisualizationController.addContainer (Container c, String name);
Then, as your algorithm proceeds, instruct the visualizer to take a snapshot along each salient point of the structure's history, as discussed in section 2.

4) DATA STRUCTURES IN JDSL.CORE.REF CURRENTLY IMPLEMENTED

4a)Sequence

Interface:

jdsl.core.api.Sequence

Containers:

jdsl.core.ref.NodeSequence

jdsl.core.ref.ArraySequence

jdsl.core.ref.HTNodeSequence

jdsl.core.ref.RTNodeSequence2 4b) Binary Tree

Interface:

jdsl.core.api.BinaryTree

Containers:

jdsl.core.ref.BTNodeBinaryTree

jdsl.core.ref.LinkedBinaryTree (limited implementation) 4c) Restructurable Tree

Interface:

jdsl.core.api.RestructurableBinaryTree

Containers:

jdsl.core.ref.RestructurableNodeBinaryTree 4d) Heap

Interfaces:

jdsl.core.api.PriorityQueue

viz.BinaryTreeBased

viz.ComparatorBased

Containers:

jdsltools.visualization.Wrappers.VBTHeap 4e) Red-Black Tree

Interfaces:

jdsl.core.api.Dictionary

jdsltools.visualization.Wrappers.VRBTree

5) BRIEF TUTORIAL

First you must run the visualizer. The visualizer can be run in four different modes -- but for now we will concentrate on its simplest form. So run one of the jdsl structures by typing:
java jdsltools.visualization.jdslviz
(Typing in the class name at the command prompt is optional)

A window will pop up with a popup menu and two text fields. The popup menu allows you to choose which sort of data structure you mean to visualize, the top field lets you choose which class to implement that data structure, and the bottom field lets you name the structure. For now, leave the popup menu at "Sequence" and do not alter the text in either field. Leaving the name as Default means that the visualizer will give your structure an appropriate name. Now click OK.

A window will pop up. There will be some buttons at the Bottom-Left. Click InsertFirst several times. Note that elements appear in the window. Now click on one of the circles with the left mouse button. It hilites yellow. It is now the selected position. Replace its element. The yellow position (or locator) is the currently selected one for any operation.

Click on another with the right mouse button. It will hilite orange. Now click the swap button. If you ever need two different positions for an operation, orange-select the second one.

Now try clicking on some of the other operations -- you will note that operations that return ints or booleans (such as size or isEmpty) return their results in a box next to the button. You will further notice that operations that take an int as input (such as atRank) require you to type the int into a box next to the button. Finally, you will note that operations that return an enumeration create a new enumeration in the list of containers. To return to the original container, select it from the menu list of containers. Also experiment with turning on and off the random element option at bottom-right.

Now let's add a second container. Go to the Containers Menu and select "Add Container". Choose Heap from the popup menu of container types. Click OK.

The first thing you ought to do is click insert(key, element) once. Notice something odd? The nodes are different shapes. The big ones are internal positions with locators (the locators are the squares). The little ones are external positions in the tree (if you don't understand the relevance of the difference between internal and external positions, much less locators, don't worry. You'll learn in lecture.)

Another thing you might find relevant is the little square locator in the bottom right corner. Since locators can exist independent of the data structure, they can be manipulated outside of it too -- right here.

Play around with the structure a bit. Try some of the different buttons. Sooner or later (and if it doesn't happen eventually, click removeMinElement() until it does) you will see a message appear in the mini-window labeled "Error Messages". This means that your structure has generated an error message. Some messages (like that you can't remove the minimum element of an element-free container) are reasonable. Others indicate bugs in your data structure.

Now look at the bar with circles in the upper right corner. This is the history of your data structure. The green box is the current event. Drag the black circle upwards to a red box. This represents an earlier point in the history of your data structure. Now drag to a blue box. Nothing happens, right? Now go to the containers menu and select your other container. It looks different, doesn't it? This is because blue boxes represent events that happened in other containers (this is useful when two data structures affect one another). Note: You can also add your own, user-defined events to the visualizer.

Now quit the visualizer from the File menu. Congratulations! You have just taken a tour of the visualizer. If you want to learn more about how to use it, open it and click on the Help button in the Add Container popup window, or choose Help from the File menu.

PS -- a helpful hint: If you are confused, first check the FAQ at the end of the visualizer help. Your question might just be answered there!

6) FREQUENTLY ASKED QUESTIONS

Q: How do you choose which tree to use in a link or replaceSubtree operation?
A: Select it in the popup menu immediately to the right of the button.

Q: How do you enter integer input for operations like atRank(int)?
A: Type the integer into the box at the right of the button.

Q: How do I insert a premade locator in Heap or Red-Black Tree?
A: Click on the locator in the box at the lower right corner. If it is empty, you can use the makeLocator function to fill it. (You can also click on a locator in the data structure being visualized, if you wish to error-check)

Q: The visualizer was supposed to return a locator that's in the current structure, but it didn't hilite!
A: Look in the bottom-right corner. Locators returned show up there.

Q: I'm creating the visualizer directly from code, and it automatically shows up in a gigantic size!
A: Set environment variable VIZSIZE=SMALL before launching the visualizer.

Q: Who wrote the visualizer?
A: The visualizer has been developed by:

Marcin Romaszewicz Q: I ran the visualizer using my browser, but it didn't work correctly!
A: Read Section 7 for answers to this question

Q: The visualizer crashed when I tried to load a class by URL.
A: Read Section 7 to learn more about this

Q: The visualizer just crashed. Oh, by the way, I'm running it on Java 1.2Beta.
A: Read Section 7 to learn more about this