Chapter 6: Generation and Reverse Engineering


About Generation

The term generation refers to the act of automatically producing other artifacts from your models. For example, given a class diagram, you may want to generate code for the classes in the diagram, or generate a document that textually describes the classes, or generate a report that depicts certain facts about the model, etc.

UMLStudio provides a scripting language for writing scripts that perform such generations. This scripting language is called PragScript and is described in detail in Chapter 7. This approach has three important benefits:

A set of Standard Scripts are provided with the product that support popular code and document generation formats.

The following diagram illustrates the generation process. PragScript provides a set of functions that can access the information in a project (e.g., the name of a class, its attributes, its methods). The PragScript Interpreter interprets the script, which in turn accesses the information in the project, to produce the output of generation.

Scripts are run by the first six commands in the Tools Menu. These commands display dialog boxes that allow you to select the script you wish to run, and to set a number of related options.

The output files created by a generation process appear inside the Generated folder in the explorer pane. You can view a generated file in two ways:


About Reverse Engineering

Reverse engineering is the opposite of generation: it analyses and parses program code to produce models that convey the same information visually. For example, reverse engineering a set of C++ classes will result in a class diagram that depicts the classes and their relationships. The following diagram illustrates the reverse engineering process.

As of version 7.0, you can either use a script to perform reverse engineering, or use one of the hard-coded reverse engineering modules. The latter option supports these languages: C++, C#, Java, CORBA IDL, PHP, and Forte. The former option supports Ada 95 and Maxim. Use of scripts is more flexible, as it allows you to customize the behavior of reverse engineering to suit your needs. It also enables you to implement your own reverse engineering script for a language not currently supported by the tool. See Chapter 7 for a description of PragScript functions that you can employ to write reverse engineering scripts.

To reverse engineer program code, use the Tools:Reverse Engineer command. This command displays a dialog for specifying the files you want to be reverse-engineered and a set of related options.

Some points worth noting when you reverse engineer code:


Standard Scripts

A set of predefined scripts are provided with UMLStudio for code and document generation. These scripts are for:

Code Preservation

As of version 4.1, code generation supports the preservation of code manually added by the user. For example, if you generate code and then make manual changes to it (e.g., insert statements inside a function), re-generating the code will not destroy your modifications. Preservation is controlled by a check box in the code generation dialog. You will notice that in the generated code, special comment blocks appear for this purpose. For example, inside a generated Java function, you will see the following:
// PRESERVE:BEGIN
// Insert your code here...
// PRESERVE:END
Code that you place within such comment blocks is preserved. UMLStudio generates these comment blocks automatically, at the appropriate places. You can also manually type them where you need them.

To preserve your code, UMLStudio uses a merge process. For example, suppose that you have generated a file named Foo.java, and then made manual changes to it. If you regenerate the file, UMLStudio will:

The two intermediate files (_old_Foo.java and _new_Foo.java), although no longer needed, are not deleted so that you can view them if you wish. For example, if you are not happy with the outcome of the merge, you can recover the old file.

Handling of places and links

Only those links and places whose Code Gen flag has been enabled are considered during code generation. All other drawables are ignored.

The code generated for a place or link depends on its semantics, as specified by the notation template. Not all semantics result in code generation.

C++ Code Generation

If the selected scope is All Models then all the models are considered (in the order they have been created in the project). Otherwise, only the current model is considered. For each such model, code is generated for each place’s master (in the order they have been created in the model). The name of the generated files will be according to the path specified in the generation dialog, and the name of each master. The code for each master will be generated in a separate pair of files (e.g., Foo.h and Foo.cpp). If the master has a file name specified in its property sheet, then this file name will be used. Otherwise, the file name will default to the master name.

As each master is generated, its file names appear in the log window, e.g., Generating: Foo.h + Foo.cpp.

For each master, the generated header (.h) file will contain the following:

For each master, the generated implementation (.cpp) file will contain the following:

C# Code Generation

This uses rules similar to Java Code Generation.

Java Code Generation

If the selected scope is All Models then all the models are considered (in the order they have been created in the project). Otherwise, only the current model is considered. For each such model, code is generated for each place’s master (in the order they have been created in the model). The name of the generated files will be according to the path specified in the generation dialog, and the name of each master. The code for each master will be generated in a separate file. If the master has a file name specified in its property sheet, then this file name will be used. Otherwise, the file name will default to the master name.

As each master is generated, its file name appears in the log window, e.g., Generating: Foo.java. If a master has the Interface option set in its property sheet, then it will be generated as an interface. Otherwise, it will be generated as a class.

For each master, the generated file will contain the following:

PHP Code Generation

This uses rules similar to Java Code Generation.

IDL Code Generation

If the selected scope is All Models then all the models are considered (in the order they have been created in the project). Otherwise, only the current model is considered. For each such model, code is generated for each place’s master (in the order they have been created in the model). The name of the generated files will be according to the path specified in the generation dialog, and the name of each master. The code for each master will be generated in a separate file. If the master has a file name specified in its property sheet, then this file name will be used. Otherwise, the file name will default to the master name.

As each master is generated, its file name appears in the log window, e.g., Generating: Foo.idl.

For each master, the generated file will contain the following:

Ada 95 Code Generation

This uses rules similar to C++ Code Generation.

HTML Document Generation

This is largely the same as RTF Document Generation, but produces more flexible output in that:

RTF Document Generation

The name of the generated document will be according to the path and name specified in the generation dialog. If no name is specified, then it will default to the project name. The generated document will contain the following:

Running in Batch Mode

The new Batch mode (introduced in version 7.0) allows you to run UMLStudio from command line and, using command line arguments, execute a PragScript (e.g., to generate code or documentation) or perform reverse engineering (for hard-coded as well as script-based languages).

The command line syntax is as follows:

UMLStudio.exe -batch
      [ProjectPath] [-new[=TemplateName]] [-save[=ProjectPath]]
      [-exit] [-script=Script] [-scope=Scope] [-folder=FolderPath] [-file=FilePath]
      [-revLang=Language] [-revModel=ModelName]
      [-add=FileListFile] [-scriptOption=OptionValue]
where: The batch option is essential, as it allows UMLStudio to distinguish a command line run from double-clicking a UMLStudio project in Windows Explorer.

After parsing the command line and error checking, UMLStudio executes the command as follows:

Examples

The following command line opens a project (Test.pro), reverse engineers a set of Java files (listed in JavaFiles.txt) into the project model called "My Model", saves the project, and then exits. Note how one of the reverse engineering options (ShowAllAttributesAndMethods) is set to false.

"C:\Program Files\UMLStudio7\UMLStudio.exe" -batch "C:\Projects\Test.pro"
      -revLang=Java -revModel="My Model" -add="C:\Projects\JavaFiles.txt"
      -ShowAllAttributesAndMethods=false -save -exit
The following command line reverse engineers a set of Ada95 files (listed in AdaFiles.txt) and saves them in a new project.
"C:\Program Files\UMLStudio7\UMLStudio.exe" -batch -new=UML.not -script="RevEng\Ada 95.pgs"
      -add="C:\Projects\AdaFiles.txt" -save="C:\Projects\Test2.pro" -exit
The following command line opens a project (Test.pro), and generates HTML documentation for it.
"C:\Program Files\UMLStudio7\UMLStudio.exe" -batch "C:\Projects\Test.pro"
      -script="DocGen\Html Generation.pgs" -folder="C:\Projects\docs" -file="Mydoc.html"
      -SortByName=true -exit


Table of Contents | Chapter 5 | Chapter 7

Copyright © 1996-2010 PragSoft Corporation (www.pragsoft.com)