Tutorial: The Object Oriented Tools

This tutorial takes you from a textual requirement via class diagrams to the design phase in SDL. The intention is to the make you familiar with the Link and Paste As concepts and the main features of the OM Editor and the Text Editor.

This tutorial assumes some knowledge of Object Oriented Analysis, the basic OMT/UML concepts, how to work with documents in the Organizer, and how to draw diagrams using the SDL Editor.

Please see Tutorial: The Editors and the Analyzer, if you are not familiar with the basic SDT tools. It is also a good idea to have practiced on the SDL-92 example in Tutorial: Applying SDL-92 to the DemonGame.

Table of Contents 

• Purpose of This Tutorial
• Working with the Text Editor
• What You Will Learn
• Starting the Text Editor
• Collecting Requirements
• Creating Endpoints
• Using OM Classes
• Working with the OM Editor
• What You Will Learn
• Starting the OM Editor
• Using the Paste As Concept
• Automatic Creation of Endpoints
• Traceability of Links
• Textual Syntax Check
• Line Handling
• Line Details
• Attributes and Operations
• The OM Class Diagram Symbols
• Class Entity vs. Class Symbol
• The Browse&Edit Class Dialog
• Using the OM and SDL Editors
• What You Will Learn
• Paste As into SDL Editor
• Conclusion

Purpose of This Tutorial

This tutorial will introduce the basic functions in the OM Editor by simulating a small development process where you will:

1. Start with a textual requirement.
2. Create some Object Model diagrams in the OM Editor, highlighting the main features of the OM Editor.
3. Enter the design phase using SDL and the SDL Editor.

The example used in this tutorial is the well-known Demongame, which you have practiced on in earlier tutorials. This time, however, we will start by doing a simple object-oriented analysis from the textual requirement of the system.

Note:  Platform differences This tutorial, and the others that are possible to run on both the UNIX and Windows platform, are described in a way common to both platforms. In case there are differences between the platforms, this is indicated by texts like "on UNIX", "Windows only", etc. When such platform indicators are found, please pay attention only to the instructions for the platform you are running on. Normally, screen shots will only be shown for one of the platforms, provided they contain the same information for both platforms. This means that the layout and appearance of screen shots may differ slightly from what you see when running Telelogic Tau on your computer screen. Only if a screen shot differ in an important aspect between the platforms will two separate screen shots be shown.

Working with the Text Editor

The Text Editor supports the same generic functions for the management of files, clipboard, diagrams and windows as the graphical editors (the SDL and MSC editors). It is specially designed for the management of text documents in the context of a development process using Telelogic Tau.

What You Will Learn

• To add text documents to the Organizer
• To define endpoints

Starting the Text Editor

1. Make a new empty directory omelink of your own (under ~/demongame on UNIX, or under C:\tau35\work in Windows).
2. Start Telelogic Tau from this directory (or set the Source Directory in the Organizer to this directory).

The Organizer window will be opened.

3. Select the Analysis Model chapter in the Organizer and Add a New document.
• Specify New document type as Text Plain
• Specify New document name as Textual_requirements
• Make sure the Copy existing file and Show in editor options are on and specify the file: $telelogic/sdt/examples/demongame/omelink/start/
demonreq.txt (on UNIX), or C:\tau35\sdt\examples\demongame\omelink\start\
demonreq.txt (in Windows)

Note:  There is also a subdirectory solution under the omelink directory in the installation, which contains the finished diagrams in this tutorial. You should however create the diagrams as described to learn how to use the OM and Text Editors.

Note:  Installation directory On UNIX, the Telelogic Tau installation directory is pointed out by the environment variable $telelogic. If this variable is not set in your UNIX environment, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for instructions on how to set this variable correctly. In Windows, the Telelogic Tau installation directory is assumed to be C:\tau35 throughout this tutorial. If you cannot find this directory on your PC, you should ask your system manager or the person responsible for the Telelogic Tau environment at your site for the correct path to the installation directory.

4. Click OK.

The resulting Organizer view should now look like this:

Figure 193 : Having added a textual requirement

The Text Editor window is displayed and shows the original textual requirements of the Demongame system.

Figure 194 : The Text Editor displaying the requirements text

Collecting Requirements

From the requirements text we will now try to understand the system and identify some important features that we think will be useful in the design and implementation of the system.

By reading the text, we identify the concepts "game", "demon" and "user". These concepts are candidates for becoming Object Model classes at a later stage in the development process.

Creating Endpoints

A way to highlight concepts is to create endpoints on these entities. Endpoints are used for creating links between entities; these links will help us in designing the system in a way that facilitates consistency checks and traceability.

To create an endpoint, you select the entity (in this case the word in the text) and then select Link > Create Endpoint from the Tools menu (or from the pop-up menu).

In text documents, endpoints are visualized by underlined words, as illustrated in Figure 195.

1. Now, create the endpoints on the above mentioned identified important concepts ("game", "demon" and "user"). You can choose any instance of the words in the text. Make sure to only select the word, not any surrounding spaces or characters. Then select Link > Create Endpoint from the Tools menu.

Figure 195  : Endpoints in text document visualized by underlining

2. Save the results on a file, e.g. Textual_requirements.txt

Using OM Classes

We are now ready to go to the next step in the analysis phase as we want to describe the concepts using Object Model class diagrams.

The Paste As functionality is used to automate the steps between the different phases of the development process and to ensure traceability between these phases. In the example we will take the identified concepts in our textual requirement and transform them into classes in an Object Model (OM) diagram.

Working with the OM Editor

What You Will Learn

• To add Object Model class diagrams to the Organizer
• To connect endpoints through links
• To Paste text As OM Class symbols
• To trace and traverse links
• To draw OM diagrams with symbols and lines
• To check the textual syntax of OM diagrams
• To browse through and edit classes.

Starting the OM Editor

To start the OM Editor we first need to create an Object Model diagram from the Organizer.

1. Select Add New from the Edit menu.
• Specify New document type as UML and Object Model
• Name the document DemonGame
• Make sure the option Show in editor is on.
2. Click OK. The OM Editor is started on a new empty OM diagram named DemonGame:

Figure 196 : The OM Editor window

Using the Paste As Concept

We are now prepared to make the transformation from text to classes. To do this, simply go through the following steps:

1. In the Text Editor, select the endpoint "game" (the underlined word).
2. Select Copy from the Edit menu.
3. In the OM Editor, select Paste As from the Edit menu.

The Paste As dialog appears, see below.

• If the Paste As alternative is dimmed in the OM Editor menu, you may have selected more than the underlined word in the Text Editor. Make sure to only copy the underlined characters.

Figure 197 : The Paste As dialog

• The option menu lists what the copied text can be transformed to, when pasted into the Object Model diagram. When pasting into the OM Editor the possible options are Class and Object.
• The option Create link from copied object to pasted object defines whether a link should be created between the copied and pasted objects. The default is on.

4. Click the Paste As button in the dialog.

A class symbol appears in the OM Editor drawing area.

5. Move the symbol to an appropriate position in the diagram and click the mouse to place it. Then de-select the symbol.
• The class symbol will be named in accordance to the textual endpoint we copied in the Text Editor. The endpoint visualization for an OM symbol is a small triangle in the top left corner. The triangle is in this example filled which depicts that the symbol is not only an endpoint but also has a link associated to it.

Note:  The visibility of the endpoint triangle is defined with an Editor Option, Show link endpoints. You may have to turn the option on via the View menu to make the endpoints visible.

6. Repeat this Paste As procedure for the remaining endpoints in the requirements text ("user" and "demon").

The resulting OM class diagram should now look something like this:

Figure 198 : OM Editor showing class symbols with links

Automatic Creation of Endpoints

We can also find specializations of the game in the last sentence of the requirements, a "DoubleGame" and a "JackpotGame". These two properties are also to be defined in our Object Model. This time the concept is more than a single word, i.e "double the stake". This is however not a problem since endpoints are allowed to span over both space characters and newlines.

We will now repeat the above procedure but skip the step where we marked the text as an endpoint in the Text Editor; the creation of the endpoint is performed automatically when the Paste As command is executed in the OM Editor.

1. Select the words "double the stake" in the text.
2. Choose Copy from the Edit menu.
3. Raise the OM Editor window and choose Paste As.

Using the Paste As functionality, the copied entity (in this case the text) will automatically be marked as an endpoint when the command is executed in the OM Editor.

Traceability of Links

To check that the entity in the Text Editor is marked as an endpoint we can use the traceability functionality. When using Paste As, a link is created between the two endpoints and this link can now be traversed.

1. Make sure the newly pasted class symbol is selected.
2. Select Link > Traverse from the Tools menu. The Text Editor is raised and selects the endpoint that the link points to.
3. Traverse the link in the other direction, back to the class symbol in the OM Editor, by selecting Traverse from the pop-up menu of the Text Editor.

We have now seen that the link is bidirectional and can be used to trace concepts between the different phases of the OO analysis. We have also seen that Paste As can help us when taking the steps between the development phases. The Paste As functionality, as we will see later on, can be used not only between text and class symbols, but between all of the notations supported by ORCA¹ and SDT (SDL, MSC, UML, IDL, ASN.1 and C++).

Textual Syntax Check

You may already have noticed that the name of class symbol corresponding to the feature "double the stake" is underlined by a red line. This is the notation that has been adopted for displaying syntax errors in the OM Editor. We realize that the syntax rules do not allow space characters in class names, so we will change the name to "DoubleGame".

1. Raise the OM Editor window, if necessary.
2. Place the mouse pointer directly in the symbol's text in the drawing area where you want the insertion point to be set. Edit the name of the class to DoubleGame.

Note:  You cannot select characters by dragging or double-clicking in this way; you can only place the cursor and insert and delete characters. For more editing features, use the text window of the OM Editor. Before you have started text editing, the text cursor is not flashing. Pressing <Delete> at this stage deletes the whole symbol. Once text editing has started, the text cursor is flashing and pressing <Delete> only deletes a character.

3. Repeat the Copy/Paste As operation for the feature "jackpot" and rename the pasted class symbol to "JackpotGame". The Object Model diagram will now look something like this:

Figure 199 : The classes of DemonGame
The picture does not show the endpoint and link markers on the class symbols.

4. Save the diagram on file, e.g. DemonGame.som

Line Handling

We will now identify the relationships between the different classes of the DemonGame. Relations are expressed as lines between symbols and the lines in the OM Editor are drawn with the help of line handles. The line handles will be visible on a symbol if it is selected:

Figure 200  : Selected class symbol with line handles

In this small example, it is quite obvious that both the JackpotGame and DoubleGame are specializations of the Game (and from the other point of view: Game is a generalization of DoubleGame and JackpotGame). This can be shown by drawing a generalization line between these classes.

To draw a generalization line, perform the following steps:

1. Select the superclass, in this example the Game symbol. The symbol will be marked as selected and three line handles will be visible at the bottom of the symbol as seen in Figure 200. Grab the generalization line handle (the rightmost of the three).
2. Draw the line towards the JackpotGame class symbol and click line breakpoints if needed. If you want to cancel the line creation, simply hit the <Esc> key.
3. Place the mouse pointer on the JackpotGame class symbol and click the left mouse button. The line is now connected to the symbol.
4. Repeat these actions to connect the DoubleGame to the Game symbol as well. We have now created an inheritance tree between these classes.

In a similar way we can create an association between two symbols by using the leftmost line handle.

5. Now create an association between the User class and the Game class (use the leftmost association line handle of the User symbol). If needed, you may have to rearrange some symbols to get a nice looking diagram. The diagram could now look like Figure 201.

Figure 201  : The DemonGame with relations between the classes

The association between the Game and User classes needs a name, normally an action describing the relation. By selecting the association line, the text field for the name will be selected at the same time. Initially, this text field is empty, but is easily located since it is surrounded by a rectangle when selected, as seen in Figure 202.

Figure 202  : Selected association with empty name text field

6. Name the association plays. Move the text field afterwards if it overlaps another symbol.

Line Details

Additional attributes of an association can of course be added. In the OM Editor, a dedicated dialog can be issued to facilitate this. The Line Details dialog is issued either from the Edit menu's Line Details command, or simply by double clicking a line in the drawing area.

1. Double click on the associationplays. The Line Details dialog is displayed.

Figure 203 : Line Details window with association line selected

Note:  This dialog can be left open while editing in the OM Editor drawing area. The dialog will update its contents according to the current selection.

Here we can add all of the attributes associated with an association line.

2. Add an Arrow to the Name and add the Role names player andplayedGame (see Figure 204).
3. In the diagram, you may want to move the association and role names to make the diagram less cluttered.

Figure 204  : Adding arrow and role names

Attributes and Operations

We will now continue our analysis by finding some attributes and operations on our already identified classes. Let us go back to the requirements text and see if we can find some attributes and operations of the Game class. We immediately identify the attribute "count" and the operations "result" and "probe".

1. Add these to the attributes and operations text compartments of the Game class symbol. After this the class symbol will look like:

Figure 205 : Class symbol with attributes and operations

• You can use the <Up> and <Down> arrow keys on your keyboard to navigate between the text compartments of the symbol as a shortcut for placing the insertion point with the mouse.

The attributes/operations text compartments can be hidden, e.g. they are irrelevant in the current context. The Collapse/Expand commands are used for this purpose.

2. Select the class symbol Game.
3. Choose the Collapse command from the Edit menu.
• The symbol is collapsed to only show the name text compartment of the symbol. The attributes and operations texts can be displayed again by selecting the Expand command. The operation can be operated on multiple selected symbols.

The OM Class Diagram Symbols

So far, we have only added symbols by using the Paste As functionality. But you can of course add new symbols in the standard way by selecting a symbol in the symbol menu to the right of the drawing area.

There are in all three kind of symbols in the OM Editor symbol menu: the class symbol, the object symbol and the text symbol.

• 
  The class symbol is the one you have practiced on so far.
• 
  The object symbol is used to describe an instance of a class. This symbol differs from a class symbol in that it does not have an operations text compartment. We are not going to use this symbol in this tutorial.
• 
  The text symbol cannot be connected to any lines and is used for free text, mostly for placing comments around the constructs of your Object Model diagram.

Class Entity vs. Class Symbol

In the next exercise, we will take a closer look on the fact that the class symbol is only a view of a class entity.

So far, we have only talked about class symbols and their attributes and operations. What they really are is a representation of a class with the name of the class symbol. Let us become a bit less abstract: two class symbols with the same class name depicts the same class.

The Browse&Edit Class Dialog

The OM Editor has the functionality for supporting the global browsing and editing of classes.

1. Create a new page using the Add command on the Pages menu.
2. Add a new class symbol on the newly added page, by clicking on the class symbol in the symbol menu and placing the symbol at an appropriate place in the drawing area.
3. Name it game.
4. Select the Class command from the Edit menu. A dialog appears:

Figure 206 : Browse&Edit Class dialog

The Browse&Edit Class dialog contains two parts, and as the name suggests the topmost contains browsing functionality, and the lower contains editing functionality.

The Browsing Functions

• The first item in the dialog tells us what scope we are in. Since the diagram we are editing right now is on the root level in the Organizer, the diagram itself is the scope (diagram DemonGame).
• Next in the dialog is an option menu where all classes in the scope are listed. When choosing from the option menu, the corresponding class symbol will be selected in the diagram. There should be 5 menu choices, one for each of the classes you have created.
• The next option menu lists all occurrences of the class, i.e. all class symbols with the same name. For the Game class we have two occurrences (two symbols) depicting the same class.

5. Select DemonGame/1 from the Show symbol in option menu. The class symbol on the first page is now selected.
• From the browse part of the Browse&Edit Class dialog we have now seen that we can "jump" to any symbol or class within the scope.

Renaming a Class

We will now continue with the second part of the Browse&Edit Class dialog where you can edit the attributes and operations of the class.

Note:  We are talking about the class (and not the class symbol). This means that if you change the name of the class it will be changed in all class symbols (all occurrences) depicting this class.

Let us now rename a class globally:

1. In the Class Name text field, change the name to gameBlock.
• The name of the class has not yet changed in the diagram.
2. Click the OK button in the Browse&Edit Class dialog.
• The class symbols (one on each of the pages in the diagram) have now changed to the name "gameBlock". We have now showed that while working from the Browse&Edit Class dialog, we are working globally on the class and not on a particular class symbol. It would have been the same behavior if attributes or operations were edited using the Browse&Edit Class dialog.
3. Before performing any other operation, select Undo from the Edit menu.
• The class symbols are renamed back to the original name "game". We have shown that changes made by the Browse&Edit Class dialog can be undone.

Editing Attributes and Operations

First we will add a new operation directly in the symbol. As we remember from the requirements text, the demon changed the status of the game at random times, and the Game class will need an operation for completing this work. Let us call it changeStatus.

1. Add an operation changeStatus() in the Game class symbol on page 2.
2. Also add the operations result() and probe() which are the same operations as in the Game class symbol on page 1.
3. Double-click on the class symbol to get the Browse&Edit Class dialog.

The two radio buttons in the Browse&Edit Class dialog are used to change the view between the attributes and the operations in the lower part of the dialog.

4. Click the All operations in diagram DemonGame radio button.

The list box is now updated to show the operations of the Game class:

Figure 207 : The operations of the Game class

5. Select the operation result() in the list box.
6. Add a return type to the operation; name it resultType
• Insert the text into the Returntype text field.
7. Click the OK button.

If no syntax errors were found, the dialog is closed and the return() operation now has a return type and both Game class symbols are updated to indicate this.

8. Open the Browse&Edit Class dialog again.
9. Select the attribute count:int in the list box.
10. Click the Clear button to the right. The attribute is now removed from the class. When pressing the OK button the attribute will be removed from all symbols of this class (in this case only one).
11. Press the OK button. The attribute is removed. You might have to change to the first page to make sure this happened correctly. However, we now change our mind.
12. Select Undo from the Edit menu (this can only be done on the first page). The attribute is restored.
13. Save the OM diagram.

Using the OM and SDL Editors

What You Will Learn

• To Paste an OM Class as a diagram type in SDL.

Paste As into SDL Editor

Our analysis phase is not complete, but in this tutorial we leave it here and take a look at the next steps in our development process.

It is now time to leave the Object Model with relations between classes and move on to the SDL domain.

In the same way that we were helped from the textual requirements to the Object Model, we will now transform our concepts from the Object Model into SDL.

1. Raise the Organizer window.
2. With the Organizer, add a new SDL package with the name BasicFeatures into the SDL System Structure. This package is where we want to add our generic game concept as an SDL process type.

Figure 208 : Having added the package

3. Now return to the OM Editor.
4. Select the Game class symbol. Copy the symbol.
5. Raise the SDL Editor with the package diagram and select Paste As from the Edit menu.

The Paste As dialog appears. The contents of the dialog is similar to the dialog when we Pasted As into the OM Editor, except from the contents of the option menu, where you select which type of object that should be pasted.

6. Make sure Process Type is the selected type in the option menu.

Figure 209 : Selecting to Paste As a process type

7. Press the Paste As button.

Place the process type symbol at an appropriate position in the package diagram.

• A link is also created between the class symbol in the Object Model diagram and the process type symbol in the SDL package diagram. You can traverse the link to go back to the OM diagram.
8. Open the process type diagram (game). As a result of the attributes and operations you have identified in the OM diagram, a variable of type integer (count) and an EXPORTED procedure with the name result have been declared to keep track of the score of the game.
9. Open the procedure diagram (result). Since you have defined a result type for the result operation, that information is present in the additional heading.

If you look in the Organizer, both the process type diagram and the procedure diagram has been created in the package.

10. If you wish, order a global save from the Organizer to save all your work. (You will however not need these diagrams in any other exercise.)

Conclusion

You will have to complete the design yourself by drawing the contents of the SDL diagrams created in the Organizer. This is however outside the scope of this tutorial, which only has shown the basic steps to take for an object-oriented analysis and design.

A much more complete tutorial on how to use the ORCA and SDT tools in the different phases of a development process can be found in SOMT Tutorial. This tutorial will show more complete and advanced examples of Paste As operations in different editors.