![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Rational Rose Developer User's Guide Note: Rational Rose Developer is an optional, separately licensed product for Apex C/C++.
OverviewRational Rose Developer provides a convenient way to take advantage of Rose C/C++ and Apex C/C++ and to support a close interaction between them.
Using this product, the user will be able to do the following:
- Using as individual tools
Rose and Apex are fully functional on their own and may be used together or stand-alone.
- Apex subsystem creation
Apex subsystems and views can be created directly from a Rose model.
- Forwarding engineering
The C++ source files generated by Rose/C++ automatically fit into the Apex subsystem architecture.
- Reverse engineering
The Apex C/C++ compiler generates the intermediate data for reverse engineering, so there is no need to analyze the C++ source files in the Rose/C++ Analyzer before exporting them to a Rose model.
- Interactive visualization
Apex C/C++ provides an easy and efficient interface for generating the Rose model from the C++ source files since all the actions on Rose C/C++ Analyzer are automatically executed.
- Two-way navigation
The navigation menu buttons in both tools allow the user to navigate from a C++ source file window in Apex to the corresponding diagrams or specifications in Rose, and vice versa.
- Convenient command access
The essential Apex commands of the Compile and Control groups are accessible from the menus of both Apex and Rose.
Use of this product assumes a familiarity with both Apex C/C++ and Rose/C++. For more information on Apex C/C++, see the extensive online help documentation available under the Help > Manuals command. For more information on Rose/C++, online help is provided under the Help menu. In addition, hard-copy User's Guides are available with both products.
The following main sections are provided in this manual:
- Rose and Apex: Classes and Subsystems
- Simple Designs Are Simple
- Complex Designs Require Complete Specifications
- How to get Apex Paths and Rose Virtual Paths to Work Correctly
- How To Generate Apex Subsystems & Views From Rose
- How To Generate Code From Rose
- Multi-user Support
- Other Integration Between Rose and Apex
- Rose and Ada Code
- Summary
- How to do Round-Trip Engineering
- How to do Apex-To-Rose Navigation
Rose and Apex: Classes and SubsystemsIn Rose, a package represents the logical side of a collection of objects, and a subsystem represents its physical side. Similarly, a class represents the logical side of an object and a module represents its physical side.
A major difference between Rose and Apex is in their subsystem structure. A subsystem in Rose can be contained in another subsystem while a subsystem in Apex CANNOT be contained in another subsystem (notice that a subsystem in Apex can still have subdirectories). Due to this structural difference, the mapping between Rose and Apex can be complicated. To make the use of the Rose and Apex integration easier, a set of Rose design guidelines is provided in the next sections and should be used. These guidelines are general enough to cover most cases in the Rose design, so it is strongly recommended that they be followed.
Simple Designs Are SimpleWhen a Rose design does not use export sets or include any package which contains both packages AND classes, it is called a simple design. In this case, the terms "package" and "subsystem" can be used interchangeably. The more complex designs will be discussed later.
A simple design is the easiest way to use this integration because it is straightforward to map from a simple design to an Apex subsystem structure. In this case, only the second-level Rose subsystems (the ones whose parent is the top-level subsystem) map to Apex subsystems. The subsystems they contain map to the subdirectories inside the respective Apex subsystems. The "uses" relationships between Rose subsystems map to the imports between Apex subsystems. An example for simple design and its mapping into Apex is shown in Figure 1.
The top half of this figure illustrates a Rose design where package T is the top level package, and packages A and B are the second level packages. Category A further contains 2 packages, AA and BB. Going through the forward engineering, this design is mapped to the Apex subsystems as the bottom half of the figure. Package T is mapped to a directory specified by the user, and the second level packages A and B are mapped to the Apex subsystems/views in that directory. The packages enclosed by a second level package are mapped to the subdirectories within the Apex views.
Figure 1 Simple Design
![]()
Forward Engineering from a Simple Design to Apex
In Rational Rose Developer, code generation involves two major steps:
- 1 . Generate proper Apex subsystems, views and subdirectories (if any) for the packages in the Rose diagram.
- 2 . Generate C++ source files in the views and subdirectories for the corresponding classes.
These two steps can be done using a single command in Rational Rose Developer. The Tools > C++ > Subsystems, Views and Code Generation command first checks for any packages whose corresponding directories do not exist in the Apex structure and creates them automatically. Once the structure is completely generated, Rational Rose Developer produces source files in the appropriate directories in the created Apex structure. If the Apex structure has been created previously, the command does proper checking to confirm that, and only generates the source files for the selected classes.
Before starting the code generation, you need to decide where the entire Apex structure will be placed and enter this information into Rational Rose Developer This can be set by editing the 'Directory' property for the design model. Once the design properties are set, select Tools > C++ > Subsystems, Views and Code Generation to produce the Apex subsystems, views, and the source files for the selected items.
You can also use other properties to guide the code generation, such as the Apex view-relative names, storage area, etc. This will be explained later in this guide.
Complex Designs Require Complete SpecificationsIf your design requires a more complex structure or the use of export sets, the Rose packages may not be a direct one-to-one mapping to the Apex subsystems. In the case, the class and module diagrams need to be created separately, and the mappings need to be explicitly made from classes and packages (the logical structure) to modules and subsystems (the physical structure).
A Simple, But General Set Of Guidelines
This section describes a set of scenarios that map from a Rose design to a set of Apex subsystems. They include:
- Mapping all Rose packages to Apex subsystems under a common directory.
- Mapping a Rose package to a special directory.
- Mapping classes to subdirectories of Apex subsystems.
Rational Rose Developer achieves the above goals with two Rose facilities:
- 1 . Modification of the Directory Properties on the design or item level.
- a .
To modify a design level property, select nothing in Rose and select (click on) Tools > Properties > Edit Properties. Change the Type combo list to "Project".- b .
To modify an item level property, select the item (a subsystem) and select (click on) Tools > Properties > Edit Properties. Change the Type combo list to the appropriate type- 2 . Making a link from one or more Rose categories to a subsystem.
- a .
Create the subsystem if it does not exist.- b .
Select the package.- c .
Select (click on) Browse > Specification- d .
Select the proper value in the "Subsystem" fieldRooting Subsystems Under a Common Directory
Apex forbids nesting of subsystems, but imposes no restriction on where in a common directory structure a subsystem can be placed. For example, to root all the subsystems under ~/demo/subsystems:
- 1 . Set the design property "Directory" to ~/demo/subsystems.
- 2 . Create the Rose subsystems in the Rose Component View.
Note: If you select a subsystem and display its properties, its Directory Property is APEX GENERATE.
- 3 . Link the package(s) to the subsystems by selecting a category and selecting (clicking on) Browse > Specification. Select the proper value in the "Subsystem" field.
- 4 . Draw arrows from one subsystem to any subsystem to create the dependency relationships between Rose subsystems.
Repeat these steps for, at least, all category trees that are not "simple." See Simple Designs Are Simple for a definition of a "simple design."
Select Tools > C++ > Subsystems, Views and Code Generation to create the Apex subsystems.
Mapping all Rose Packages to Apex Subsystems Under a Common Directory
This can be simply done by setting the design property "Directory" to the pathname of the common directory.
- 1 . Use facility 1(a) to bring up the design property window.
- 2 . Select property Directory and fill in the pathname of the common directory.
- 3 . Click on OK.
This will make the subsequent forward-engineering operations to place all the Apex subsystems to be generated under this directory if all the packages use the default properties.
Mapping a Rose Package to a Special Directory
In some special circumstances, the user might want to map a Rose package to a special directory different from the common directory specified in the design property.
Before we get to how it can be done, let us revisit how a Rose design is mapped to Apex structure mentioned in the section "Simple Designs are Simple". A top-level package/subsystem is mapped to a common directory and a second-level package/subsystem is then mapped to an Apex subsystem under this directory.
Following the principle just described, when a special directory is needed in the forward-engineering, (a) a new top-level subsystem (not a package because the current package already belongs to another package) needs to be created and mapped to the new directory, and (b) a new second-level subsystem (enclosed in the subsystem created in (a)) also needs to be created and mapped to an Apex subsystem in the special directory. The rest of the work is to making a link from the specified package to the subsystem created in (b).
The following is the series of steps to make this happen:
- 1 . Create a Rose subsystem, call it S1 for convenience, in the top-level module diagram.
- 2 . Use facility 1(b) to bring up the item properties of S1. Set the item property "Directory" to be pathname of the special directory.
- 3 . Create (or relocate if it exists) a Rose subsystem, call it S2, inside the subsystem S1. (Use facility 1(b) to bring up the item properties of S2 and verify whether the property "Directory" is APEX GENERATE.)
- 4 . Use facility 2 to link the specified category to subsystem S2.
This will, during the forward-engineering, map the package to an Apex subsystem in the special directory.
Mapping Classes to Subdirectories of Apex Subsystems
As described in the previous sections, any Rose packages/subsystems beyond the second level will be mapped to subdirectories of an Apex subsystem. That means, if a class is enclosed by a package of the n-th. level, where n > 2, it will be mapped to the subdirectory of an Apex subsystem during forward engineering.
Issues of Complex Mappings
There are a number of issues to be aware of when doing complex mappings.
Specifying an Export Set
To specify an export set, select a uses arrow in the module diagram and type the name of the export set. There is no dialog box. The next time Tools > C++ > Subsystems, Views and Code Generation is run, it will create the export set. Use the links to Apex from Rose in the Tools menu or Apex itself to populate it with .h files.
Imports between Packages or Subsystems that contain Classes
Rational Rose Developer supports imports between packages or subsystems that contain classes. Imports between other types of classes or subsystems help to explain your systems abstraction, but the "Imports Diagram" command does not guarantee creation of these higher level relationships and Tools > C++ > Subsystems, Views and Code Generation may produce no Apex imports for such a specification
Imports between Leaf Packages in Different Systems
<New> in Browse > Class Diagram allows imports between two leaf packages in different systems. To do this, follow these steps:
- 1 . Create a view with those categories using <New> in Browse > Class Diagram.
- 2 . Name the new view.
- 3 . Use Edit > Copy to copy and paste each of the packages requiring import relations into the new view.
- 4 . Draw the relation between the two packages.
- 5 . Select Tools > C++ > Subsystems, Views and Code Generation to create the new imports.
Imports between Subsystems in Different Enclosing Subsystems
<New> in Browse > Module Diagram also allows imports between two subsystems in different enclosing subsystems. Generally, the same steps should be followed as in the previous item.
Has Relations between Packages
Has relations between packages do not affect imports for complex diagrams. Only the subsystem inheritance rules apply.
Subsystem/Subdirectory Levels
You may have n levels of subsystems with Directory Properties with UNIX paths set either relative or absolute to the enclosing subsystem. The system will create n levels of subdirectories.
Mapping of Simple Trees of the Class Diagram
Simple trees of the Class Diagram view can be left unmapped to the Module Diagram view. Consider a simple tree to be one that follows the simple criteria from its root to its leaves, not a sub-tree of another tree.
Mapping of APEX GENERATE Modules
Modules can be created in any subsystem with the "Directory" Property set to APEX GENERATE. One or more classes can be mapped to a module. Rational Rose Developer does not restrict this mapping.
Undesirable Mappings
Strictly speaking many of the mappings below create semantically correct results but obscure mappings between Rose and Apex.
- 1 . Subsystems with their Directory Properties set to APEX GENERATE may not contain other subsystems with APEX GENERATE. If they do, Rose will flatten the subsystems. Do not do this.
- 2 . Complicated logical designs with unmapped packages will create a subsystem for each package containing classes. This includes the case mapping a parent package and forgetting to map its class containing children. Do not do this.
How to get Apex Paths and Rose Virtual Paths to Work CorrectlyA Rose model file usually has .mdl (for model) or .red (for reverse-engineered model) as its suffix. For simplicity of explanation, we refer to a Rose model file as a .mdl file.
Rose maintains paths to the categories and generated code in its .mdl file, and in memory. Using Rose with Apex presents a set of problems centering around this effective "caching" of addresses. First, it is desired that moving a .mdl file from one view to another with accept changes, for example, moves the internal .mdl addresses also. Second, you want the addresses contained in the model to point to valid locations.
Rose provides an extended virtual path mechanism. Rose users normally use these relative to a user's login. In Apex paths are regarded as relative to a particular context rather than a directory structure.
Solution
Creating and storing the .mdl file
Rose contains a type of relative path map prefixed with &. & means to look in the location where the .mdl file exists and resolve the virtual relative path from there. The * in virtual path maps allows substitution into the path pattern.
This means that for any model one should have one root subsystem and view containing at least the design level .mdl file.
Since the .mdl file will move through its set of views as the code progresses from development to release, be sure that the root subsystem contains a corresponding view for each accept changes.
The solution below works for most systems:
- 1 . Create one root subsystem and view with at least the .mdl file.
- 2 . Maintain one such root view for each view your system uses as a release mechanism.
See A word about property settings for more complex cases.
Maintaining the Paths in Rose
Since Rose specifies and then creates the subsystems, views, and files for a project, it's impossible to set the paths to specified but as yet uncreated items relative to the .mdl file. Furthermore, if no .mdl file exists yet in the file system it's impossible to make anything relative to it.
To effectively create the first system and its additions, Rational Rose Developer contains a fix paths menu item. After creating a new import, subsystem, view or .mdl file one should run this command. If navigation does not seem to work, run this command. Without it, paths will be some combination of relative and absolute paths.
A brief example
Suppose you are creating a new project. You specify some categories with imports and classes according to this document. Then you use Tools > C++ > Subsystems, Views and Code Generation to create the subsystems and views. The .mdl file in memory now uses complete paths to the subsystems and views you created. If you save this .mdl file, it will also have these canonical pathnames. After running Tools > Fix Paths, the paths will be relative to the root view containing the .mdl file.
If you then generate code, Rose will contain the canonical paths. After running Tools > Fix Paths, Rose will contain the relative paths.
If you add a new subsystem or category and run Tools > C++ > Subsystems, Views and Code Generation, the paths to that new view and subsystem will be canonical. After running Tools > Fix Paths, they will be relative.
A word about property settings
The Rational Rose Developer properties include Apex View and Apex Configuration.
Typically leave Apex View null. Null means navigation from Rose to Apex objects maps to the object in a view with the same name as the view with the .mdl file. Rose will use your user name to name the initial views. Use Apex's copy view, or move object to create different sets of views.
You may set the value of Apex View to a different value, but after creating the set of views with APEX GENERATE, be sure to change the value back to null. That way, navigation will always work correctly.
The Apex Configuration property allows the user to create a file with path substitution strings. The intention is for this property to name an Apex configuration file. We recommend naming this property to &/root.cfg. Root.cfg must be a file or preferably a link to a configuration file in the same location as the .mdl file. One may choose to use a relative or absolute path, but the relative path mechanism works best for most situations. You should change the file that root.cfg points to as it migrates thought the views.
How To Generate Apex Subsystems & Views From RoseTo generate Apex subsystems and views from Rose, first design your Rose model with either a class diagram only view or as a combined class/module type view. See the previous sections for how to decide which type your application requires. Then choose Tools > C++ > Subsystems, Views and Code Generation from Rose. After Rose finishes computing the export sets, imports, views, and subsystems, select OK from the initial dialog. You might want to look at the log before proceeding and having Rose build the subsystems and views. If everything looks OK, then select YES to generate the directories, views, and subsystems.
How To Generate Code From RoseGenerating code from Rose works like the standard versions of Rose. Select the categories or subsystems containing classes or modules and then select Tools > C++ > Code Generation.
If you are version controlling the .mdl file and hope to move it from view to view, always run Tools > C++ > Subsystems, Views and Code Generation after the first one finishes.
In the future there will be a update paths, or a similarly named command to change absolute paths to virtual relative paths after creation of subsystems and views. That will be more intuitive and avoid telling Apex to update imports but effectively it will be the same.
Multi-user SupportPlease see the Rose documentation for information on multi-user support.
Other Integration Between Rose and ApexSome of the frequently used Apex commands are also available from the Rose Window. The commands in Tools > Compile and Tools > Control of the Rose window contain some of the commands in Compile and Code of an Apex window, respectively. For instance, you can select several classes and click on Tools > Control > Check In to check in the header/body files for the classes from an Apex Control > Check In dialog. In a similar way, you can also compile classes by clicking on Compile > Code.
Try out the other tools:* menus and have fun!
Rose and Ada CodeWe do not support a close Rose Apex Mixed integration at this time. A Rose Ada and Rose C++ menu item could be provided and separate .mdl files could be maintained. Use Rose C++ for Apex to create the subsystems and views. You must be sure to open the Ada .mdl files with Rose Ada and the C++ .mdl files with Rose C++.
SummaryRational Rose Developer can be summarized simply:
- 1 . Do all modeling on the logical side.
- 2 . The model that creates the Apex subsystems and views should have all the classes or modules in the leaf (inner most) packages or subsystems.
- 3 . Each model should have one root subsystem or category.
- 4 . The root subsystem or category should import, directly or indirectly via the closure, all the other subsystems or views.
- 5 . Subsystems or packages may exist individually in their respective subsystem and view.
Following these guidelines will make migration of projects from one release to the next of Apex easier. It also uses Apex and Rose to the fullest extent possible, while minimizing confusion.
How to do Round-Trip EngineeringThis tutorial teaches you how to start using Rational Rose Developer. It follows a hands-on approach in which you perform a series of exercises. This tutorial illustrates Round-Trip Engineering using Rose by introducing the following Rose components:
- A model definition application
- A code generator
- An analyzer that reverse engineers an implementation's model from the implementation source code
- A design update mechanism
The process of creating or modifying a model, generating or updating C++ code from the model, possibly modifying and then analyzing the modified code, following by updating the model is called Round-Trip Engineering.
Apex runs under the X Window System and is compliant with OSF/Motif style guidelines. Rose runs under the Wind/U system which translates Windows/NT to Motif.
This tutorial contains the following sections:
- Starting Rose
- Creating a Model
- How to do Forward Engineering
- How to do Reverse Engineering by Running the Rose C++ Analyzer
- How to do Visualization
Note: This section assumes the user is familiar with the basic operation of Apex and Rose. To complete the activities in this section, the Rational Rose Developer product must have been installed and Apex must be running to proceed with this tutorial. In addition, a directory viewer window must be open. Any user directory can be used.
Note: For simplification of the tutorial, this section uses UML notations in the example Rose design model.
Note: If you have both the Rational Rose Developer and Rose/Ada products installed, you will see C++ and Ada submenus in the Rose menu and from an Apex window. If you have only one of them installed, the submenu level is eliminated. This tutorial assumes the former case.
Starting Rose
This section gives you instructions on starting Rose and the use of Rose.
Starting Rose
The Rational Rose method recommends the use of static and dynamic views of a logical model and a physical model to capture the in-process products of object-oriented analysis and design. Using a graphic or the Rose notation, Rational Rose enables you to create and refine these views within an overall model representing your problem domain and software system. This overall model contains classes, class categories, objects, operations, states, subsystems, modules, processors, devices, and the relationships between these components. Each of these model components possesses properties that identify and characterize it. The Rational Rose notation uses graphical icons to represent each kind of model component and relationship.
- 1 . To bring up Rose, from the Apex directory viewer, select the Rose > C++ > Start Rose command.
The Application window with an empty diagram entitled Class Diagram: <Top Level> /Main is displayed.
![]()
The Apex Message window displays a message indicating connection to Rose.
![]()
- 2 . Execute the File > Close command in the Apex Message window.
Rose Windows
The graphical user interface of Rose provides a simple way to design a model. It allows you to create, modify, and manipulate the items of a model. With a typical setting, a Rose window consists of several subwindows: application window, browser window, and documentation window. In this tutorial, we will only look at the application window. For details on Rose/C++, please consult the Rational Rose/4.0 C++ User's Guide or the on-line manuals by clicking on Help > On Context.
Application Window
The application window, also known as diagram window, has a diagram toolbar, the opened diagrams/specifications, and a log window. As shown in the previous Rose window display, when Rose is started, the application window shows class diagram with its associated diagram toolbar for the Logical View; meanwhile, the log window is iconified. If no model file is specified, the application window shows a default class diagram which contains no items. You can start your design in this diagram.
The Class Diagram
The class diagram is intended for the user to make the design from the logical side. You can select one of the tools in the class diagram toolbar as shown below, and draw it in the class diagram.
![]()
Creating a Model
Overview
This section gives you instructions on using Rose to create a model. The topics in this section are:
Creating a Simple Package Diagram
- 1 . Select the package creation tool from the palette:
![]()
- 2 . Click in the middle of the diagram to create a package.
- 3 . Select the package by clicking on the box and click again to name the class. Type the name "c1" the text box.
- 4 . Select the package creation tool again.
- 5 . Click a little below the object created above to create a new package.
- 6 . Select the new class and type the name "c2".
Your diagram should contain the following:
![]()
- 7 . Define the relationship between these two classes as "c1 uses c2":
Defining Level 1 Class Diagrams
- 1 . Double-click on category c1.
An empty Class Diagram: c1/Main is displayed.
- 2 . Select the class creation tool:
![]()
- 3 . Click in the middle of the diagram to create a class.
- 4 . Select the class by clicking on the object and click again to name the class. Type the name "c1t1".
- 5 . Select the generalization creation tool and click a little below the object created above to create a new class.
- 6 . Select the new class and type the name "c1t2".
- 7 . Define the relationship between these two classes as "c1t1 uses c1t2":
- Select the uses relationship creation tool.
- Move the cursor to c1t1.
- Press the mouse button and hold down the mouse button while you drag the cursor to c1t2.
- Release the button.
Your diagram should look like the following illustration.
![]()
You have now defined your c1 Class Diagram.
Now define the c2 class diagram by repeating the steps above substituting c2 for c1.
You now have the c2 Class Diagram as show in the following illustration.
![]()
By resizing and moving the class diagrams in the application window, your Rose window should be similar to the one below.
![]()
You can also examine the hierarchical view of the components in these class diagrams from the browser window. Click on the box with a "+" sign in front of "Logical View" to expand the top level diagram and then click on the similar boxes in front of "c1" and "c2". You will see in the browser window that
- The logical view has two packages "c1" and "c2".
- The "c1" package has two classes "c1t1" and "c1t2".
- The "c2" package has two classes "c2t1" and "c2t2".
How to do Forward Engineering
Overview
This section gives you instructions on using Rose to generate corresponding C++ code, i.e., forward engineering. The topics in this section are:
- Updating Rose Properties
- Creating Apex Subsystems, Views, and Source Files
- Displaying a Generated Header File
- How to Modify and Compile Source Files
Updating Rose Properties
We are going to change the default settings for a few of the Rose properties for this example model.
- 1 . Execute the Windows > Class Diagram > <Top Level> / Main command to raise the <Top Level> / Main diagram.
- 2 . Make sure nothing is selected by clicking in an empty spot on the diagram.
- 3 . Execute the Tools > Properties > Edit Properties command.
An Options dialog box is displayed. Pull down the Type combobox and select Project.
- 4 . Scroll in the Property scroll list to the Directory property.
- 5 . Click on the line contains the Directory property. The current default is AUTO GENERATE.
![]()
- 6 . Change the property's Value field to the full pathname of a directory intended to contain the Rose-generated code files.
In this tutorial, the pathname used is /apex/power/b/lin/tutor.
- 7 . Click OK in the Edit Model Properties dialog box.
Creating Apex Subsystems, Views, and Source Files
Apex supports the dividing of a software-development effort into high-level components called subsystems, each containing a group of logically related objects. Subsystems let you group related filestogether.
Every subsystem contains a set of views. Working views provide areas for the development and integration of software. Release views contain the saved versions of the products developed within a subsystem during the development process.
Note: Because subsystems and views are directories in UNIX, their names are case-sensitive. A subsystem has a .ss filename extension and a view has a .wrk or .rel extension. Views are subdirectories within subsystems.
To find out more about subsystems, views, and source, please see the Using and Customizing Summit/CM and Programmer's Guides.
To create the Apex subsystems and views for this example model:
- 1 . In the <Top Level> class diagram, open the Rose Log window by executing the Window > Log command.
- 2 . Resize the windows so you can see both the Rose Log and the class diagram window. The Rational Rose application window will look like the figure on the next page.
![]()
- 3 . In the <Top Level>/ Main diagram, select the Edit > Select All command.
Both packages are now selected.
- 4 . Execute the Tools > C++ > Subsystems, Views and Code Generation command to create Apex subsystems and views.
The Code Generation Status dialog box is displayed. This display is updated as generation progresses.
The Rose Log displays messages about directories, subsystems and views to be created.
The system prints out status messages to the Rose Log. Before creating the subsystems, the following dialog box is displayed:
![]()
- 5 . Click Yes to proceed.
Since the Apex views do not exist yet, an Apex New View dialog will be brought up for each new view.
![]()
- 6 . Click OK in each of the New View dialog.
The /apex/power/b/lin/tutor/c1.ss/lin.wrk and /apex/power/b/lin/tutor/c2.ss/lin.wrk views will be created. The imports between those views will reflect the dependencies among the packages in the model.
Once the Apex subsystems and views are generated, the commands will also generate source files for the classes in the class diagrams. An Apex Check Out dialog will be brought up for you to control and check out all the newly generated source files. Click OK in the Check Out dialog.
![]()
- 7 . The Code Generation Status box will then show "Success" as its status.
![]()
Click on the Close button. This completes the generation command. You can browse through the Rose Log window and Apex Message window for the execution log of the command.
- 8 . Now you are ready to save your design model. Click on File > Save As to bring up the "Save Model to" dialog. Use the Directories scroll box to find the directory for saving and enter "tutor.mdl" in the "File name" field. Click OK to save the model.
Displaying a Generated Header File
- 1 . In the <Top Level> diagram, double-click on the c1 object.
The c1 class diagram is displayed.
- 2 . In the c1 class diagram, select the c1t1 class object.
- 3 . Execute the Browse > Browse Header command.
An Apex editor containing the c1t1.h file is displayed.
![]()
How to Modify and Compile Source Files
Let us add data attribute and operation to the source files and compile the source files as preparing for reverse-engineering. If the source files are not compiled, you will not be able to perform any reverse-engineering or visualization commands.
- 1 . Bring up the source file c1t1.h in an Apex text editor window.
If you completed the previous section, you should already have one displayed on your screen. If not, you must complete Displaying a Generated Header File.
- 2 . Click on Edit toggle switch. Scroll the text down to the line //## end c1t1.public. Add the following two lines after this line:
- 3 . Click the Save button to save the file.
- 4 . Click on File > Close to close the text editor window.
- 5 . Go back to the Rose window.
- 6 . Click on Browse > Top Level to get back to the top-level class diagram. (If the menu item is grayed out, you might already be in the top level.) You should find the two packages "c1" and "c2" in the diagram.
- 7 . Click on Edit > Select All to select the two packages.
- 8 . Click on Tools > Compile > Code to bring up the compilation dialog.
![]()
Click OK to proceed with the compilation in the two Apex views which contain all the source files related to this model.
- 9 . Once the files are compiled, you will probably see a window summarizing the compilation errors. Click on the "Remove Warnings" button, and all the warnings will disappear. Click File > Close to close the summary.
You have now built the intermediate information for all the source files. You are ready to do reverse-engineering.
How to do Reverse Engineering by Running the Rose C++ Analyzer
Overview
This section shows how to use the Rose C++ Analyzer to create a model from C++ code and then to update the original Rose model by using the Rose C++ Analyzer. The topics in this section are:
- Starting the Rose C++ Analyzer
- Adding to a Project
- Saving the Project File
- Exporting to Rose
- Updating the Original Model
Starting the Rose C++ Analyzer
To run Rose C++ Analyzer on the code you just created in the previous module:
- 1 . Visit the directory that contains the Apex subsystem c1.ss that we created. This can be done by selecting package "c1" in the class diagram of the Rose window, and clicking on Browse > Browse > Header.
![]()
- 2 . In this directory viewer, click on Rose > C++ > Advanced Commands > Reverse Engineer. This will bring up the Rose C++ Analyzer window. An analyzer project with window title "__reverse_engineered" is also set up to include the source files in the current view. Some fields in the project still need to be filled out.
The Rational Rose C++ Analyzer application window is displayed.
![]()
The Apex Message Window now contains a message indicating connection to the Analyzer.
![]()
- 3 . Click on the Caption button.
The Caption dialog box is displayed.
- 4 . Enter "Tutorial" as the project name in the Caption dialog box and click OK.
![]()
Adding to a Project
The following steps can be easily completed by selecting Rose > C++ > Advanced Commands > Reverse Engineer (Closure) from the Apex directory viewer. This section shows how to construct an analyzer project.
- 1 . Click on the Directories button.
- 2 . The Project Directory List dialog box is displayed.
- 3 . Using the Directory Structure scroll area, select the directory containing the Rose code files (the value of $DIRECTORY--where you put your Rose-generated code files in Updating Rose Properties). Double-click on the c2.ss directory. Select the username.wrk directory, where username is your username. For this example, username is "lin". Click on the Add Current button.
The working view directory will be displayed in the Source Directory area.
![]()
- 4 . Check the Default Data Directory Pattern field. Its value should be */.Rational/Compilation/cna. If it is not, edit the field.
- 5 . Click OK in the Project Directory List dialog box.
- 6 . Click on the Files button in the Project window.
The Project Files dialog box is displayed.
![]()
- 7 . In the Project Directory Structure scroll list, double-click on c2.ss (the second line).
Four files will be listed in the Files Not In List scroll box.
- 8 . Click the Add All button.
The four files will now be listed in the Files In List scroll box.
- 9 . Click OK in the Projects Files dialog box.
The Project window has all eight files listed in the Files scroll list.
![]()
Saving the Project File
- 1 . Save your project by executing the File > Save command.
The Save As dialog box is displayed.
- 2 . Change the Selection field to specify the project tutorial.pjt and click OK.
The title of the project window changes from Project 1 to Tutorial.
Exporting to Rose
Note: Before exporting to Rose, the C++ source files of this project must be compiled using the Apex C++ compiler. In Apex, visit the Apex views which enclose these files and select Compile > Code. Please refer to the Compile > Code online help for details on using this command.
- 1 . Execute the Edit > Select All command.
All the files in the Files scroll list are highlighted.
- 2 . With all entries in the Files scroll list highlighted, execute the Action > Export to Rose command.
The Export to Rose dialog box is displayed.
![]()
- 3 . Click OK in the Export to Rose dialog box. The status bar at the bottom of the Analyzer window shows the execution status for exporting.
When Exporting is done, the message line at the bottom of the Rational Rose C++ Analyzer application window will again say:
For Help, press F1
Updating the Original Model
- 1 . In the Rational Rose application window, click on the Class Diagram:<Top Level>/Main diagram.
- 2 . Execute the File > Update command.
The Update Model From dialog box is displayed.
- 3 . Enter tutorial.red in the Selection field and click OK.
The Merge Status dialog box is displayed.
- 4 . When the button in the Merge Status dialog box says Close, click it.
How to do Visualization
Rational Rose Developer provides a convenient way to reverse-engineer the existing C++ source files into a Rose model. It provides a set of Apex commands which automate a series of actions involving the use of Rose/C++ Analyzer. As a result, all the users need to do for reverse-engineering is one click on a command in an Apex window, and it will automatically start a Rose/C++ Analyzer server if necessary, build a project file with a list of selected source files, export the files to a Rose model, and even bring up a Rose server to show the diagrams in the model.
The following menu commands are available from the Rose entry in the main Apex Menu bar. These commands provide the reverse-engineering interface from Apex.
![]()
In this section we will complete the following activities
- Visualizing C++ Source Files
- Inserting Annotations to C++ Source Files
- Cleaning up Existing Rose Models
Visualizing C++ Source Files
The Rose > C++ > Visualize command shows the Rose diagrams for the selected C++ source files. This command requires that the source files for the operation be coded first.
- 1 . Visit the directory for visualization. In the Apex Main Panel window, place the pathname of the view containing c1t1.h in the placeholder, and click Visit.
The directory viewer window for the specified view is displayed.
- 2 . Select the view name or any filenames in this directory viewer.
- 3 . If the selected files are not yet coded (compiled) or have been modified since the last Compile > Code command, then click Compile > Code.
This produces the necessary intermediate data for reverse-engineering.
4. Click Rose > C++ > Visualize.
This command (1) brings up the Rose/C++ Analyzer server if it is not already running, (2) builds a project file with all the specified source files, (3) exports the files to a Rose model file, (4) shows the model in the window of a Rose server. If there is already a Rose model file that contains the specified files, it will skip over the first three steps and display the model directly.
The following is an example of visualizing the c1.ss/lin.wrk view.
![]()
The Apex Message window displays the following message.
![]()
The Rose > C++ > Visualize (Closure) command is similar to the Rose > C++ > Visualize command except that it applies to all the source files in the import closure of the current view. In our example, this means all the source files generated by the Rose/C++ code generation in the previous sections.
Note: If the Rose/C++ Analyzer puts out a warning dialog in the process, just click OK to resume the process.
Inserting Annotations to C++ Source Files
The Rose > C++ > Annotate command is used when the first time an existing C++ source file which is NOT generated by Rose/C++ is to be reverse-engineered.
To preserve design specifications of the model in the source file, Rose produces special design annotations in source files in the code generation. These annotations help record the design documentations, keep different kinds of specifications in separate regions, and protect them through reverse engineering. See the Code Cycle command in the Rational Rose/C++ User's Guide for more details.
The source files WITHOUT these annotations can still be reverse-engineered for viewing the object structure. However, the generated Rose model may lose some information in the source file.
To use the Rose > C++ > Annotate command to insert annotations into the source files, use the following procedure.
- 1 . In the directory viewer that contains c1t1.h, select the view name or filenames for this command.
- 2 . Click Rose > C++ > Annotate.
This command (1) brings up the Rose/C++ Analyzer server if it is not already running, (2) builds a project file with all the specified source files, (3) inserts the design annotations into the files.
The Rose > C++ > Annotate (Closure) command is similar to the Rose > C++ > Annotate command except that it applies to all the source files in the import closure of the current view.
The following is an example of annotating a source file.
![]()
The result after annotating is as follows:
![]()
Cleaning up Existing Rose Models
In the Rose > C++ > Clean Up submenu, there are three different commands for cleaning up the Rose model files associated with an Apex view.
The Rose > C++ > Clean Up > Delete Visualization Model command removes the current model file, the Rose > C++ > Clean Up > Delete Closure Model command removes the closure model file, and the Rose > C++ > Clean Up > Delete All Models command removes all the model files.
How to do Apex-To-Rose NavigationThe navigation from Apex subsystems to Rose models serves as a convenient way for cross-referencing the design and implementation of a software project. This class of commands require that the Apex source files be reverse-engineered first, i.e., Rose model file(s) must have already been built for the associated Apex views. Please refer to the section Visualizing C++ Source Files for details on reverse-engineering.
Apex-to-Rose navigation takes place from two different types of Apex windows:
From an Apex Directory Viewer
The Navigate > Visit Rose C++ command is used to navigate from a C++ source file in an Apex window to the corresponding object in the Rose model in Rose window.
- 1 . In the directory viewer containing c1t1.h, select c1t1.h.
- 2 . Click Navigate > Visit Rose C++.
A Rose window displays the Rose model associated with this view, and highlights the class c1t1 in the class diagram Class Diagram: c1/Reverse Engineered.
![]()
Note: If there is not an existing model file associated with this Apex view, an error message is displayed in the Apex Message window. If the model file exists but the Rose server is not already running, it will bring up a Rose server.
From an Apex text editor window
There are two navigation commands are available from an Apex text editor window, Navigate > Visit Rose Specification and Navigate > Visit Rose Diagram.
The Navigate > Visit Rose Specification command is used to navigate from the name of a C++ class or function in an Apex text editor window to the corresponding Rose specification in the Rose model in the Rose window.
- 1 . In the directory viewer containing c1t1.h, double-click on c1t1.h.
An Apex text editor window containing the source of c1t1.h is displayed.
![]()
- 2 . In the text editor window, scroll down and highlight c1t1_func of the line "int c1t1_func (int in_data = 0);".
- 3 . Click Navigate > Visit Rose Specification.
The Rose window is brought to the top of the screen, and the specification of c1t1_func is displayed in the Rose window.
![]()
The Navigate > Visit Rose Diagram command can be used to navigate from the name of a C++ class or function in an Apex text editor window to the corresponding Rose diagram in the Rose model in the Rose window.
- 1 . Click Navigate > Visit Rose Diagram.
The Rose window is brought up to the top of the screen, and the class diagram Class Diagram: c1/Reverse Engineered is displayed with the class c1t1 highlighted.
![]()
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |