Method Wrappers Applications

This file describes three sample applications that have been included with the method wrappers source. There is a coverage tool for testing method coverage, an interaction diagram viewer, and a synchronization tool that can be used to make objects thread safe.

Coverage Tool

To install the coverage tool, simply parcel-in Coverage.pcl. You will also need to have installed the Refactoring Browser since it uses several of its interfaces.

To use the coverage tool, evaluate "CoverageTool open". This will open a window similar to:

The top part of the tool shows the methods that you want to instrument. The ones with a check mark are the ones that will be instrumented. You can select a method to be instrumented, by making a selection, and then selecting "add" or "add all" from the menu.

There are several actions that can be performed by the buttons at the bottom of the window. The "Save" and "Load" buttons will save/load the current selection (at the top). The "Install" and "Uninstall" buttons will (un)install the currently selected coverage (note the Install button is not shown, since we have already installed coverage). The "Pause" and "Resume" buttons will pause/resume the coverage if it has already been installed. This will allow you to make some changes without losing the percent of methods covered (the Resume button is not shown since we have not paused it).

The "Coverage" button will open a Refactoring Browser on the current selection and its coverage. The browser will look similar to

Each of the entries will be color-coded base on percentage of coverage for that selection and the colors entered in CoverageNavigator class>>initialize (remember to reinitialize the class after changing the method).

Finally, the "No visual" and "Visual" buttons toggle the visibility of the percent done bar. Since updating the percent done bar runs in a separate process, it might not be desirable for it to be updating when you are running your tests.

Interaction Diagramming Tool

The interaction diagramming tool will automatically create interaction diagrams from your running VisualWorks program. You can select which classes you want to view, execute your code, and then have the tool automatically build an interaction diagram of your code.

The interaction diagramming tool was originally a project done by David Wheeler, Jeff Will, and Jinghu Xu for Prof. Johnson's CS497 class. I rewrote the display code so that it could handle thousands of events (using interval trees), and refactored some of the recording to be more robust. If you want to see the original project notes, you can go here.

To install the interaction-diagramming tool, you need to parcel-in the Interaction.pcl file. Also, you will need to install the RefactoringBrowser.

To run the tool, you need to evaluate "InteractionDiagramApplication open". This will open a window similar to the picture above. After opening the window, the first thing you'll need to do is to select some methods to watch. For example, since you have already installed the Refactoring Browser, you might want to select all methods in the "Refactory*" categories. Once you have selected the methods you want, you need to "Install" the wrappers. Now you need to execute some to generate some events. If you installed the wrappers on the Refactory* categories, then you might want to open a RefactoringBrowser (i.e., "RefactoringBrowser open"). After you have generated some events, you'll need to uninstall the wrappers. When you uninstall the wrappers, the diagram will update with the events you generated.

Reading the results: the diagrams generated by the tool are similar to the interaction diagrams seen in many books, but there is one notable exception. Since we only select a few methods to observe, we miss some messages. As a result, there are times when a message is received, but the last method entered did not send the message. For example, suppose you have:

	Foo>>createBar
		^Bar new

	Bar>>initialize
		"do some initialization"

	Bar class>>new
		^super new initialize

and that you only wrap Foo>>createBar and Bar>>initialize. If you send a Foo the createBar message, that event will be recorded. It will send the new message to Bar class, but since that method is not wrapped, it is not observed. When the new method sends the initialize method to a Bar, it is observed, but the last observed method did not send it. Such events are called indirect message sends and are displayed as yellow lines. In the picture above, we can see that "a RefactoringBrowser" sent a closed message to some object that wasn't wrapped, which resulted in the update:with:from: method being called on "(nothing selected)" (a CodeModel).

There are several features that could be added to the interaction diagramming tool. If you want a feature, you can send me email, but the quickest way to have the feature implemented might be to do it yourself. Since I have several other projects, I cannot dedicate too much time to improving the diagramming tool. I can provide email support for you to implement the feature. Once you have completed the feature, you should submit it so that everyone can use it.

Synchronization wrappers

To install the synchronization wrappers, you just need to parcel-in Synchronization.pcl file.

To synchronize an object, send the message synchronize to the object you want to synchronize (e.g., "Transcript synchronize"). This will make a lightweight class for the object and wrap each of its methods so that different processes cannot access the object at the same time. If you want to uninstall the wrappers, you just need to send the unsynchronize message to the object.

To synchronize a class, send the installOn: message to the SynchronizationWrapper class with the argument of the class you want to synchronize (e.g., "SynchronizationWrapper installOn: TextCollector"). The uninstallOn: message will deinstall the wrappers if you decide that you do not want them.

Pre and Postconditions

The Pre and Postconditions file-in has been removed from the MethodWrappers package since it was out-of-date with the latest version of the Refactoring Browser. I doubt that I'll get around to converting the sources to be current with the browser, so if you would like to convert it, I can mail you the original sources. Anyway, here's a picture of what it looked like: