Reverse Engineering from Apex

---

Contents

This chapter is organized as follows:

• Basic Operations
• Dialog Box Options
• How Ada Is Represented in a Class Diagram

Rose can analyze Ada 83/Ada 95 code compiled with Rational Apex and generate a Rose model containing class and component diagrams that present a high-level view of the code.

Note that this capability is only available for Ada units that have been compiled with the Apex compiler, and that all units must be in the installed (analyzed) or coded states.

---

Basic Operations

The reverse engineering tool can create both class diagrams and component diagrams. Class diagrams show the high-level relationships between Ada units and types, and the operations and data structures associated with each type. Component diagrams come in two forms:

• An Ada unit diagram, which displays the "with" structure of the Ada units in a program, independent of subsystem structure.
• A subsystem diagram, which displays the import structure of the views you specify.

Within each view is a display of the "with" structure of the Ada units in that view.

Creating the Model File

No matter which type of diagram you want, the reverse engineering tool always generates a model file, called rose_ada.mdl by default. This file can be opened within Rose for layout and display.

Select the Ada unit or view you wish to diagram, and choose Reverse Engineer... from the Rose > Ada Apex submenu. You will see the Reverse Engineer dialog box, where you can modify various options. Choose OK or Apply to create the model file. See Dialog Box Options .

Displaying the Model

Once you have created the model file, you can load it into Rose. Select the file in the directory viewer (you may need to do File > Redisplay first). Then choose Start Rose from the Rose > Ada submenu. This will invoke Rose and display the model.

Note: For traversal to work, you must invoke Rose from the Apex menu. If Rose is already running before you started Apex, exit Rose and restart from the Apex menu command.

Once Rose is invoked, your next action depends on whether you created a class diagram or a component diagram. If you created a class diagram, choose Format > Layout Diagram to format the diagram. If you created a component diagram, choose Browse > Component Diagram. Select the <Top Level>/Main component diagram and choose OK. When the module is displayed, you will see the UML packages or units displayed in a straight diagonal line. Layout the diagram by choosing Format > Layout Diagram.

If you created a component diagram, you can double-click on a UML package box to see the units within that view. You will need to run Format > Layout Diagram on each UML package individually.

If you created a class diagram based on Apex views, you will see UML packages in the top-level class diagram. Double-click on the UML package to see the classes and utilities in that view. You will need to run Format > Layout Diagram on each UML package individually.

Use File > Save to save the model with the diagrams laid out.

To traverse from an unit in a Rose diagram to the actual Ada source code, select the unit and choose Browse > Browse Spec. This will invoke the Apex editor for that unit.

---

Dialog Box Options

Here is a brief description of each option in the Reverse Engineer dialog box:

Include Closure of Views/Units

With this button selected, reverse engineering processes all selected views or units, plus the import closure or Ada closure. This option is the default.

Exclude Views/Units with Prefix

Use this option to exclude views or units starting with a given prefix. For instance, you might want to exclude the rational_dir/base/ada area.

Include Views/Units with Prefix

Use this option to include only views or units starting with the given prefix. This option would let you limit your diagram to a particular project, for example.

Include only Views/Units Selected

When this option is selected, only the views or units on the right side of the Objects or Views area are included in the petal file.

Petal File Name

By default, reverse engineering creates a file called rose_ada.mdl. Use this box to have it create a different file.

Include Classes

If you select this button, reverse engineer creates a class diagram of the units or views selected.

Include Modules

If you select this button, reverse engineering creates a component diagram of the units or views selected.

If neither Include Classes nor Include Modules is selected, a component diagram showing just the import structure of the subsystems is created.

---

How Ada Is Represented in a Class Diagram

The reverse engineering tool uses various algorithms to map Ada constructs to the UML notation, based primarily on the mapping described in Chapter 1.

Mapping Package Specifications (Ada 95)

An Ada package becomes a utility if contains subprograms which are not operations of some class-like type declared in the same package (see below). Each of these subprograms becomes an operation of the utility.

Packages that contain only subprograms associated with some class-like type do not correspond directly to an entity of the class diagram (although the class-like types that they contain do). Their name can still be used to generate the prefix of entity names that use the colon notation.

All package specifications result in the creation of a package specification module in the proper component diagram. The "with" relationships between packages result in the creation of dependency relationships between the corresponding modules.

Mapping Package Specifications (Ada 83)

An Ada package will become either a utility or a class. To become a class, the package must meet the following criteria:

• It must define at least one private record type
• All visible subprograms must include a parameter with a private record type

Mapping Type Declarations (Ada 95)

Only those types which are class-like result in the creation of a class in the model. The distinction between class-like types and other types is important, because it avoids cluttering the model with classes that would correspond to minor type declarations, introduced for low-level implementation reasons.

The definition of class-like types is as follows:

• A private or limited type is class-like (regardless of the nature of its full type declaration.
• A record or tagged type is class-like (even if it is not private).
• A task or protected type is class-like (note that the existence of a task or protected object doesn't cause the creation of a class).

All other types are not class-like. Such types do not cause the creation of a class, although they may be used to fill some other information of the model (e.g., code generation properties). Note in particular that (non-private) access and array types, which are produced by the code generator to implement by-reference relationships and multiplicities larger than 1, are not class-like

For record and tagged types, the components become either attributes or "has" relationships. A "has" relationship is created if the type of the component is a class-like type, or an access type designating a class-like type, or an array type whose component is class-like, or access to class-like. The containment and multiplicity of the relationship is set accordingly, as well as the code generation properties that describe the container and access types. In all other cases an attribute is created.

The subprograms that include a class-like type as a parameter become operations of the class.

Mapping Type Declarations (Ada 83)

All types declared in the specification of a package become classes in the class diagram.

Most types become "implementation types," where the ImplementationType property is set to the definition of the type, and where no operations or attributes are assigned to the class. These classes are not visible in the initial class diagram displayed by Rose, but can be made visible using Query > Add Classes.

If a type is a record type, defined in the private part of a package specification, it becomes a class. The components of the record become attributes, or "has" relationships, of the class. The subprograms that include the record type as a parameter become operations of the class.

If a type is an access type to a private record type, no class is created, but the Handle Name property of the referenced class is set based on the name of type.

Normally every class has an associated utility, which is the parent package where the type is declared. If, however, all subprogram declarations map to a class, then the first class that is not an implementation type becomes the representation of the entire package.

To associate each type with its enclosing package, Reverse Engineer creates a dependency relationship with the type as the supplier and the enclosing utility, or class if the utility is not needed, as the client. The relationship is named decl, a keyword that the code generator uses to determine whether a class is declared within the context of a utility or other class.

Details of a Has Relationship (Ada 83)

The multiplicity and access of a "has" relationship are determined by the type of each component of the record. If the type is a simple type, the multiplicity is set to 1. If it's an array, the multiplicity is set to the size of the array, or to * if the array is unbounded. If the type is defined by a generic, and the generic is declared in the same package, the multiplicity is set to *.

If the component of the record is an access type, the access is set to "by-reference," and otherwise is set to "by-value."

Mapping Subprogram Declarations

All subprograms declared in an package specification, visible or private, become operations. If there is a class-like type declaration, and the subprogram includes a parameter of that type, or is a function that returns that type, then the operation is assigned to that class. Otherwise, the operation is assigned to the utility that corresponds to the package.

Mapping Object Declarations

An object declaration is a variable, constant, or named number declared in a package specification. Each object declaration becomes a static attribute or "has" relationship. If the object is a constant, the IsConstant property is set to True.

If the package where the object is declared contains at least one class-like type, and all subprograms are associated to classes, then the objects become static attributes of the first class found in the package. Otherwise, the objects become static attributes of the utility.

An exception declaration, while not technically an object, maps to an attribute using the same algorithms described above for variables and constants.

Mapping "With" Clauses

Reverse engineering tracks the With clauses that would be generated by the "has" relationships between the various classes in the package specifications. The remaining "with" clauses, those that are used for parameter types and return types, become dependency relationships in the model.

Special Handling for Subsystems in the $APEX_BASE Directory

Since the subsystems in the $APEX_BASE directory are defined by Apex, doing a complete analysis only wastes space in the model. However, some analysis of the types defined in these subsystems is required to guarantee that "has" relationships in other subsystems have classes as their suppliers. Thus, reverse engineering examines only the type declarations in these subsystems, and does not evaluate attributes or operations.