Dowser Class Extractor Usage Manual

Daniel Popescu
Georgia Institute of Technology

Introduction

This document describes how to install and how to use the Dowser ClassExtractor.

Install

Binary installation

Base functionality

The binaries were compiled for the Cygwin platform Version 1.15.18. Cygwin is a Linux-like environment for Windows. It consists of two parts:

A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing substantial Linux API functionality.
A collection of tools, which provide Linux look and feel.

Additionally to the Cygwin environment, the Dowser ClassExtractor requires an installation of WordNet. WordNet can be installed with the Cygwin Setup program.

After downloading the binaries, the Dowser ClassExtractor can be extracted. In this stage the tool can already be used to extract class diagrams from text files. However, the base functionality can only create one Java file, which contains all extracted classes. To visualize the result in a UML diagram, three more tools are required.

Visualizing Functionality

The Dowser ClassExtractor creates a Java file. This file can be visualized with the tool UMLGraph. UMLGraph allows the declarative specification and drawing of UML class and sequence diagrams. The Dowser ClassExtractor uses the current version 4.1 of UMLGraph. UMLGraph is a Java program which uses javadoc to translate a Java file into a dot file. The program Graphviz can convert this dot file into popular graphic formats like JPEG, GIF or PNG.

To summerize, the following programs are needed to visualize the UML diagrams.

Java V1.4 or a newer version
UMLGraph V4.1
Graphviz V2.6

All these tools can be downloaded from the Internet and can be used without any charge. See the specific licenses of the tools for details.

Source code installation

The program can be compiled using the GNU C Compiler with the provided Makefile. Additionally, compiling requires the WordNet library in the library path. Although compiling was only tested in the Cygwin environment, it should be possible to compile the program under Linux. The source code can be downloaded from the Dowser ClassExtractor homepage. After the source code is extracted, the program can be compiled by typing make within the shell. In this stage the tool can already be used to extract class diagrams from text files. However, the base functionality can only create one Java file, which contains all extracted classes. To visualize the result in a UML diagram, three more tools are required. Section 2.1.2 describes the additional required tools.

How to use the Dowser ClassExtractor

The Dowser ClassExtractor is a command line tool. This section describes with the help of an example, how to use the Dowser ClassExtractor. First, it is described how to transform a text file into a Java file, which contains the UML model. The second step, shows how to use UMLGraph and Graphviz to convert the Java file into a UML visualization of the created model. Thereafter, a variation of the first scenario is described. The second scenario declares actors for which no classes should be created during the extraction of the object oriented analysis model. Afterwards, the object oriented model is created again.

Extracting an object oriented analysis model

The Dowser ClassExtractor reads an ASCII text from the standard input. It extract the model from the text and stores it in the file model.java. In this example the file elevator.txt is transformed.

The content of elevator.txt:

An elevator system is to be installed in a building with floors.

Each elevator has buttons. Each elevator has one button for each floor. When a user presses a button, the button becomes illuminated and the elevator visits the corresponding floor. When the elevator visits a floor, the elevator cancels the corresponding illumination.
Each floor has two buttons. (except ground and top). If the user presses the up-button, an up-elevator is requested. If the user presses the down-button, a down-elevator is requested. If the user presses a button, this button becomes illuminated. When the elevator visits a floor, the elevator cancels the corresponding illumination of the button in the desired direction. The system minimizes the waiting time.
When an elevator has not to service any requests, the elevator remains at its final destination and the doors of the elevator are closed. The elevator awaits further requests.
The elevators service all requests from floors eventually with equal priority.
If a user presses a button within the elevator, the elevator services this request eventually in the direction of travel.

With the following command the model can be extracted:

cat elevator.txt | ./classExtractor

While processing the file the program prints out which rules are applied. In the end the folder contains the file model.java, which describes the extracted model.

In this elevator example model.java contains the following classes:

class building {
}
/**
* @has - - - illumination
*/
class button {
private int illuminated;

private int illuminated;

}
class door {
private int closed;

}
class down_button {
}
class down_elevator {
private int requested;

}
/**
* @has - - - button
* @has - - - door
* @navassoc - await - request
* @navassoc - cancel - illumination
* @navassoc - service - request
* @navassoc - visit - floor
*/
class elevator {
void remain();

}
/**
* @navassoc - installed_in - building
*/
class elevator_system {
}
/**
* @has - - - button
*/
class floor {
}
class illumination {
}
class request {
}
class up_button {
}
class up_elevator {
private int requested;

}
/**
* @navassoc - press - button
* @navassoc - press - down_button
* @navassoc - press - up_button
*/
class user {
}
class waiting_time {
void minimize();

}

Visualizing the object oriented analysis model

This subsection describes, how the above created model.java is transformed into a UML model. PNG is the target format of the model.

model.java has to be copied into the UMLGraph folder.

The following command converts the Java file into a dot file, which the tool Graphviz can interpret.

javadoc -docletpath UmlGraph.jar -doclet UmlGraph 
  -attributes -operations -private model.java

If the Graphviz path is set in in the path variable, the following command creates the final UML model as a PNG file.
```
dot -Tpng -ograph.png graph.dot
```

The result of the transformation should look like Figure 1.

**Figure 1:** The automatically created analysis model from the elevator example.

Extracting an object oriented analysis model without the actors

The above created object oriented analysis model contains a class user. However, the user is not part of the system which should be developed. The Dowser ClassExtractor offers an option to automatically remove the not desired classes. All classes that should not be part of the model have to be described in an external file. For this example, the file noClassFor.txt is created. It contains the words elevator_system, building and user. All words within this file must have a semicolon at the end. Therefore, noClassFor.txt contains the line elevator_system;user;building;. To create the model.java without the classes from noClassFor.txt, the following command has to be executed.

cat elevator.txt | ./classExtractor -a noClassFor.txt

After transforming model.java into a PNG file, the final Figure 2 is created.

**Figure 2:** The automatically created analysis model without the class user, elevator_system, building.

About this document ...

Dowser Class Extractor Usage Manual

This document was generated using the LaTeX2HTML translator Version 2K.1beta (1.49)

The command line arguments were:
latex2html manual.tex -split 0 -dir biblio -no_navigation

The translation was initiated by Daniel Michael Popescu on 2005-12-15

Daniel Michael Popescu 2005-12-15