essence in ibm rational system architect user’s guide · essence in ibm rational system architect...

25
Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM Netherlands

Upload: nguyencong

Post on 26-Jul-2018

224 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

Essence in IBM Rational System ArchitectUser’s guide IBM Remco Havermans, IBM NetherlandsArjen van de Wetering, IBM Netherlands

Page 2: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

Acknowledgment

The Essence language is a new modelling language designed by the consortium, consisting of several branches of the Dutch government, companies and research institutions. The language allows for the modelling, visualization and managing of the definition of data. It was based on the work done by Pieter Wisse in his book Metapattern: Context and time in information models (2000). Operating on a semantic level, Essence allowed for the combining of the powers for the classical paradigms, such as object and rule oriented approaches. Additionally, the context of the data is put inside the model, something which is not done in other languages.

The graphical notation used in many Essence products is an adaptation of examples by Wisse. Without Wisse’s brain child, contextual specialization, Essence would not have been possible.

The Essence language and corresponding documentation is managed by Novay, and is publically accessible on the Essence website1.

This document is part of the Essence implementation for IBM Rational System Architect.

1 Http://www.essence-project.nl

Essence in IBM Rational System Architect 2

Page 3: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

Table of contents

Acknowledgment..................................................................................................................................2Table of contents..................................................................................................................................31. Introduction......................................................................................................................................4

1.1.Related documents....................................................................................................................42. Installation and configuration...........................................................................................................5

2.1.Essence implementation package.............................................................................................52.2.Installation.................................................................................................................................5

2.2.1.usr_fn.bas...........................................................................................................................52.2.2.EssenceMacro.mac............................................................................................................6

2.3.Configuration.............................................................................................................................92.3.1.Manual import...................................................................................................................92.3.2.Essence template file import...........................................................................................12

3. Essence design and modelling........................................................................................................143.1.Diagram....................................................................................................................................143.2.Horizon.....................................................................................................................................153.3.Concept....................................................................................................................................163.4.Declaration...............................................................................................................................173.5.Composite Declaration............................................................................................................20

4. Functions........................................................................................................................................214.1.Category Redraw......................................................................................................................21

4.1.1.Function Redraw..............................................................................................................214.2.Category Repair........................................................................................................................21

4.2.1.Function Determine.........................................................................................................224.2.2.Function Redefine............................................................................................................22

4.3.Category Review......................................................................................................................234.3.1.Function Conceal..............................................................................................................234.3.2.Function Reveal................................................................................................................234.3.3.Function Collapse.............................................................................................................23

5. Typical questions and answers.......................................................................................................245.1.Straight declaration lines.........................................................................................................245.2.Declaration line runs around concept.....................................................................................245.3.Declaration names shown on diagram....................................................................................245.4.Updating IBM Rational System Architect with Essence...........................................................25

Essence in IBM Rational System Architect 3

Page 4: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

1. Introduction

As part of the development of the Essence language, an experimental version of the Essence implementation for IBM Rational System Architect has been build and delivered in June 2013.

This is guide is a combination of the installation and user guide, and describes the typical actions of the user using the Essence implementation.

The code and this document are provided on an as-is basis without any warranty or responsibility for IBM corporation.

1.1. Related documents

This guide is part of several documents from the Essence project. The guide will not describe how Essence works in detail, and a formal explanation of this language can be found in one of the documents listed in the table below.

title version Date author remarks location

The Essence language, version 2

1.1 19 June 2013

Paul Oude Luttinghuis, Lianne Bodenstaff

Definition of the Essence language.

https://doc.novay.nl/dsweb/Get/Document-139806/

Essence in IBM Rational System Architect 4

Page 5: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

2. Installation and configuration

The Essence implementation is in an experimental phase, this means that the implementation needs to be installed and configured by the user when used.

The installation only has to be done once, in which concurrent usage of Essence only the Encyclopedia's need some configuration.

This chapter is divided into 2 parts, the first will describe how Essence is installed on top of IBM Rational System Architect. The second part of the chapter will explain how an encyclopedia is configured to use Essence.

Note that, this guide will not describe the installation of IBM Rational System Architect. In order to follow the Essence installation guide, an installed and working version of IBM Rational System Architect is required.

2.1. Essence implementation package

This document is written for the Essence v0.4 implementation. A ZIP file can be found on IBM DeveloperWorks2. Updates to the Essence implementation can be expected to be posted here, or a redirection to the correct location of these files.

All files of the implementation can be found in the “Essence implementation v0.5.zip” file. This file can be expanded or unpacked to any location on the computer. It is suggested to keep the ZIP file itself as a backup of all unedited files.

The ZIP file contains the following files:

• “usr_fn.bas”• “EssenceMacro.bas”• “Essence.txt”• “USRPROPS.TXT”• “AUTOEXEC.STY”• “ess_horizon_ab.wmf”• “ess_horizon_ab.bmp”

2.2. Installation

To install the Essence implementation for IBM Rational System Architect, the following files are needed:

• usr_fn.bas• EssenceMacro.mac

2 https://www.ibm.com/developerworks/community/groups/community/Essence

Essence in IBM Rational System Architect 5

Page 6: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

2.2.1. usr_fn.basThe usr_fn.bas is a supporting file that corrects behavior linked to the display of declaration arrows. If this file is not installed correctly, frequent errors can be expected in IBM Rational System Architect.

The following steps describe how the installation should be done:

1. Locate the installation folder of IBM Rational System Architect. This folder will be called installdir in the remainder of this section.By default the folder can be found typically at the following locatons:

◦ “C:\Program Files (x86)\IBM\Rational\System Architect Suite\System Architect”

◦ “C:\Program Files\IBM\Rational\System Architect Suite\System Architect”

2. Locate the usr_fn.bas file inside the installdir. If the directory does not contain this file, continue with step 3.

A) Create a backup of the “usr_fn.bas” file.

B) Rename the “usr_fn.bas” file to “essence_usr_fn.bas”.

C) Copy the file “essence_usr_fn.bas” to the installdir .

D) Locate the file 'fmtscrpt.bas' and open with a text-editor (such as Notepad).

E) Add the following line (marked in yellow) to the end of the file (with quotes): #includex "essence_usr_fn.bas"

F) Save and close the file, and go to step 4.

3. Copy the file “usr_fn.bas” to the installdir .

4. Done.

2.2.2. EssenceMacro.mac

The EssenceMacro.mac file contains the supporting macro code for the Essence implementation, as well as the code behind the various menu functions of Essence.

To install this macro in IBM Rational System Architect the following steps need to be taken:

1. Open IBM Rational System Architect

2. Navigate to: Tools > Macros > Maco Projects...

Essence in IBM Rational System Architect 6

Page 7: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

3. Click on the button to add a new macro ( ).

4. Navigate to the location of the EssenceMacro.mac file and select it.Note: for developers be sure to select 'Open for write' if you want to adjust the macro.

5. Press OK

6. A prompt will pop up, asking if you want to enable or disable the macros. Select the option Enable Macros. This prompt will also show up the next time IBM Rational System Architect is started, be sure to select Enable Macros, if working with Essence to use the features build into this macro.

Essence in IBM Rational System Architect

Illustration 1: Selecting the Macro Project option

Illustration 2: Selection of the EssenceMacro.mac

7

Page 8: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

7. Done.

Additional note for developers:

The code itself is written in Visual Basic for Applications, and can be accessed with the build-in code editor of IBM Rational System Architect. It is allowed to re-use the code written in this macro, as written in the license, the full license can be found in the 'autoexec' module of the macro.

Essence in IBM Rational System Architect

Illustration 3: Prompt asking to enable or disable loaded macros

8

Page 9: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

2.3. Configuration

Each encyclopedia that wants to use Essence needs to be configured separately. Some files of the Essence implementation need to be imported into the encyclopedia to allow IBM Rational System Architect to work with Essence.

This section describes how the Essence template encyclopedia can be used and how the files can be imported manually. When Essence needs to be imported into a pre-exiting encyclopedia, a manual import will be required.

2.3.1. Manual import

The manual importation of Essence works with both new as existing encyclopedia's. It has to be remarked that the Essence implementation can come in conflict when combined with other extensions to the meta-model.

The Essence implementation has no requirements for other modelling languages that are supported by IBM Rational System Architect. Therefore, it will have no problem to function accordingly in a new encyclopedia with all configuration options disabled. However, it is suggested to enable UML when working with Essence.

In total there are 5 files that need to be imported into the encyclopedia:

• Essence.txt• USRPROPS.TXT• AUTOEXEC.STY• ess_horizon_ab.wmf• ess_horizon_ab.bmp

The following steps the describe the process for importing these files in the encyclopedia. If the encyclopedia uses a previous version of Essence, the following process can be repeated to update these files.

1. Startup IBM Rational System Architect.2. Open the encyclopedia in which Essence needs to be configured.3. Select the option “Tools” > “Encyclopedia File Manager”

Essence in IBM Rational System Architect

Illustration 4: Selecting Encyclopedia File Manager option

9

Page 10: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

4. This will bring up a list of files which are included in the encyclopedia, with the option to add new files or remove existing files. Click on the top-left icon, and then select “Import Files...”.

5. There are two scenario's for the importation of these files. A describes the process with an encyclopedia without an other custom implementation, whereas B describes when the an additional implementation is included.A) If there are no other custom implementation included into this encyclopedia, the

following files can be imported:▪ Essence.txt▪ USRPROPS.TXT▪ AUTOEXEC.STY

B) To include Essence in an encyclopedia which also imports a different implementation the following extra steps need to be taken.Note: it is possible the other implementation is not compatible with Essence! Which could invalidate your encyclopedia.1. Locate the file “USRPROPS.TXT” in the list and select it.2. Export the file by clicking the second button.3. Open the file using a text-editor, such as Notepad on Window.4. Append the following line (with quotes) to file: #include "Essence.txt"5. Save the file, and import it into the encyclopedia.6. Locate the following files, and import these as well:

• Essence.txt• AUTOEXEC.STY

6. For the following file, an additional action needs to be taken. In the encyclopedia file manager, shown in step 4, click on the top-left icon, and then select “Import Files As...”.

7. Select the file “ess_horizon_ab.bmf”, this will cause a pop-up box to open which asks how the file should be imported. Change the name to “images\ess_horizon_ab.bmp”.

8. Repeat the process for the file “ess_horizon_ab.wmf”. The name of this file should be changed

Essence in IBM Rational System Architect

Illustration 5: "Import Files..." option

10

Page 11: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

to “images\ess_horizon_ab.wmf”.

9. Close the file manager.10. Go to the option “File” > “Open Encyclopedia”, and select the current encyclopedia. This will

cause the encyclopedia to reload, and allow the usage of Esssence.11. If a warning is shown regarding the composite declarations, they can be removed by clicking

the 'X' in the top right corner, this message should not reappear.12. Done.

Additional note for working with multiple implementationsThe Essence implementation has been designed to avoid conflicts between other frequently used implementations. The items in Essence are located on the following locations within the IBM Rational System Architect meta-model, this information can be used to check other implementations for conflicts:

• Diagram: 'User 25'• Symbol: 'User 25' to 'User 29'• Definition: 'User 25' to 'User 28'

Essence in IBM Rational System Architect

Illustration 6: importing files on a specific location

11

Page 12: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

2.3.2. Essence template file import

Included with the files of the Essence implementation is a backup file, in which a pre-configured encyclopedia can be found. This encyclopedia has the Essence files already imported on the correct locations, and includes an example Essence diagram.

To avoid having to manually import the Essence files, a copy can be made from this file to provide a base encyclopedia for modelling.

The following steps describe how this back file can be imported back into a new encyclopedia.

1. Close down IBM Rational System Architect.

2. Open the System Architect Encyclopedia Manager or SAEM. This guide will use the SAEM for SQL Server.

3. When the SAEM is opened, it will locate the known database locations. Select the location that is used, locally the default would be “<Computer Name>\SYSARCH”. The IBM Rational System Architect guide describes in further detail how to connect to other databases.

4. Select the function “Database” > “Restore From File...”

5. Enter the name to which encyclopedia the data should be stored, in the example below the name “Essence_Example” is used, which does not exist yet. In the second box enter the location of the “EssenceTemplate.bak” file (you can look for it using the '…' button).

Essence in IBM Rational System Architect

Illustration 7: List of database connections

Illustration 8: Function Restore From File..

12

Page 13: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

6. Press OK, and a bar should appear on the bottom of the screen which shows the importing process.

7. Close SAEM en start IBM Rational System Architect.

8. The new encyclopedia can now be found under the 'Existing' tab of the encyclopedia selection screen. Be sure to enter to same connection string as used in SAEM.

9. Done.

Essence in IBM Rational System Architect

Illustration 10: The import process bar, showing the status of the import.

Illustration 9: Using the template to create a new encyclopedia

13

Page 14: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

3. Essence design and modelling

This chapter describes how an Essence model is created in the Essence implementation for IBM Rational System Architect. The document will show how a model can be created but will not go into detail about the Essence language itself. More information for this subject can be found in the Essence language description, which can be found on the Essence website3.

3.1. Diagram

The Essence diagram is the locate where the data of Essence is visualized. The diagram itself can be created by right clicking the 'diagrams' section in the explorer, choosing new and then selecting the Essence diagram.

If the Essence macro is loaded, each Essence diagram will be checked for the existance of a horizon on the diagram. If the horizon is missing a new hoirzon will be created and be placed instead.

A new Essence diagram will have the default formatting of IBM Rational System Architect. This means that the diagram has certain visual options, such as a grid, enabled. These options can be adjusted by right clicking and then selecting “Diagram Format” > “Display Options”.

Display options can be selected according to your personal preference, recommended is to disable all options here.

Options

The Essence diagram has some additional options separate from IBM Rational System Architect. These options allow to adjust the behavior of the diagram.

3 http://www.essence-project.nl

Essence in IBM Rational System Architect

Illustration 11: The display options for a diagram

Illustration 12: options in an Essence diagram

14

Page 15: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

The following options can be set in an Essence diagram:

• Allow new concept setsIf this option is disabled, the program will check any existing concepts that are added to the diagram, to see if their concept set is also set to one of the concepts that are already on the diagram. For example, a diagram only has 'concept1' visible on the diagram. This concept belongs to the 'Set1' concept set. This means that only concepts that belong to 'Set1' can be added to the diagram. However, it will not do this check on newly created concepts.

• Format new relationsEnabled by default, this function will use the 'redraw' function when a new declaration is added to the diagram. This will make sure that new lines are properly formatted.

• Format dropped conceptsSimilar to the 'Format new relations' function, this function will use the 'redraw' function an every pre-existing concept added to the diagram. This will only influence the declaration lines that are directly connected to the added concept.

3.2. Horizon

In Essence the horizon is used to show the limit of the view. This allows for views to excluded information that is not important for the context of the view.

However, the horizon is in IBM Ration System Architect also defined as a definition. This means that the same horizon is shown across different views. Therefore, it is recommended to not create additional horizon definitions.

Each Essence diagram that gets opened will automatically get the Horizon added to the diagram. If no horizon exists in the definition list, a new definition will be created with the name “Horizon”. When there are multiple horizon definitions in the encyclopedia, the first definition (alphabetically) will be added to the diagram if no other horizon is present on the diagram.

The horizon has the following properties.

Property Description

Name Identified of the horizon, will be set to “Horizon” by default.

Description A description about the horizon.

Behavior List of declarations in which the current concept is the object, this can only on the diagram by removing or adding the declarations.

Essence in IBM Rational System Architect 15

Page 16: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

3.3. Concept

The concept is the main part of an Essence diagram. The concept visualizes the information inside an Essence diagram.

To add a concept to an Essence diagram press the concept button in the toolbox, shown on illustration 13. Next click in the diagram to create the new concept. Which will make IBM Rational System Architect request a name for the concept.

If there is an existing concept definition, this concept can be added to a diagram in two ways:• Create a new concept with the exact same name.• Drag the concept from the explorer into the diagram.

A Concept has the following properties:

Property Description

Name The label that is attached to the concept. Unlike the Essence language, this is required by the tooling, and needs to be unique within the project.

Concept Set Optional set to categorize several related concepts to each other. This can be, for instance, the originating domain, department, or organization.

Description A description about the concept.

Definition List of the declarations in which the current concept is the subject, this can only on the diagram by removing or adding the declarations.

Behavior List of declarations in which the current concept is the object, this can only on the diagram by removing or adding the declarations.

Additional notesIn the current version of the Essence implementation, a concept is forced to have an unique name. However, as Essence allows for the de-coupling of the names and the physical concept, this has been scheduled to change in a future release of the implementation.

Essence in IBM Rational System Architect

Illustration 13: Concept button in the toolbox

16

Page 17: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

3.4. Declaration

The meaning of each concepts is displayed by the use of declarations. These declarations have, same as concepts, a definition on the background in which the information is stored.

A declaration is displayed as an arrow in the toolbar. When this symbol is clicked a declaration can be drawn on the diagram. Each diagram must start with a concept, in Essence the object, and end with either a concept or the horizon, in Essence the subject.

For example, “A student is a human enrolled in a school”. Below is described how this is added with declarations.

In illustration 15 a diagram is shown with the symbols matching the above statement.

Selecting the declaration option from the toolbar we start by selecting the concept that is defined, student in the example. When the mouse button is pressed and hold an '+' will appear, this shows where the line will connect to the concept.

Essence in IBM Rational System Architect

Illustration 14: Declaration symbol in toolbar

Illustration 16: line connection point

Illustration 15: Diagram with 3 concepts

17

Page 18: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

When the button is released, an example of the line will be shown. Next go to the concept which defines 'student'. For instance 'Human', it will show an example how the line connects between the two concepts, to accept click with the mouse.

This will open a box, which allows for the user to enter a name to the new declaration. Note that this is fully optional and IBM Rational System Architect will do an incremental count of the declarations.

If the name is set, press 'OK' to accept. This will cause a second window to open, which contains the details of the declaration. This will allow the user to switch between an activity and a passivity. The declaration will change according to the choice made between these types.

• An activity will allow the user to enter a constraint. The declaration will be displayed as a line with the arrow head at the end.

• A passivity always has the same constraint, “TRUE, Deterministic”. By selecting this type the option to enter a constraint will disappear. The declaration will be displayed as a normal line with two cross lines, instead of an arrow head.

Essence in IBM Rational System Architect

Illustration 17: Example declaration between concepts

Illustration 18: Pop-up screen for entering the name of a declaration

Illustration 19: Passivity (L) and activity (R) in an Essence diagram

18

Page 19: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

In IBM Rational System Architect the following properties are given to the declaration definition:

Property Description

Name The identifier for the declaration.

Description A description about the declaration.

Object The object is the concept that is defined by the given subject.

Subject The subject defines the object of the declaration.

Type Lists the declaration as an activity or passivity

Constraint* A logic expression that guides the behavior of it's subject. This is currently a free-text form, however this can change in the future.

Motivation* An optional motivation for the given constraint or portions from the constraint.* These properties can only be changed when type is set to activity

Essence in IBM Rational System Architect 19

Page 20: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

3.5. Composite Declaration

In Essence it is possible to hide or omit concepts from a view. This can be done without invalidating the model itself. When a concept is hidden, the context of said context will be connected to its behavior.

Illustration 20 shows the Essence construction between mammal, human and student. A human defines a student, and a mammal defines a human, this means that indirectly a mammal defines a student. Would the human concept be removed from the view, the dashed line take its place to show the indirect definition of a concept.

The visual difference with the normal declaration emphasizes that it is different from other declarations. The composite declaration shows that, on it's location, one of more concepts are defined within the solution but not shown in the view.

The composite declaration has, similar to the normal declaration, a different notation for activity and passivity. When a concept is concealed from the view, the Essence implementation will check the declarations for their constraints. If all of these constraints are set to “TRUE, Deterministic”, as passivity, then it will create a composite passivity. All other cases will create a composite activity.

There is no definition behind a composite declaration, and they are purely for the visual representation. Unlike the other items from the Essence construction, the composite declarations are specific to only 1 diagram and its concepts. The removal or the change of its values will not reflect back into the declarations It has hidden.

The composite declaration has the following properties:

Property Description

Name The identifier for the composite declaration. By default this will be composed from the name of the object and subject.

Description A description about the composite declaration.

Essence in IBM Rational System Architect

Illustration 20: Example of Concealing

Illustration 21: Composite passivity (L) and composite activity (R) in an Essence diagram

20

Page 21: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

4. Functions

The implementation of Essence offers several features that can help the modeller. This chapter will describe this features, and give an example how and when they should be used, as well as a detailed description what it the function will do.

The functions have been sorted into three categories, redraw, repair and review, each category will be discussed in its own section within this chapter.

The Essence functions can be found in System Architect under the 'Symbol Format' for 'Diagram Format' sub- menu's. These menus are both shown in the 'Format' menu that is shown on top of IBM Rational System Architect or by simply right clicking a symbol or diagram respectively.

4.1. Category RedrawThe redraw category contains the functions that are directly related to the layout. Functions in this category will not effect the underlaying model and a purely for layout issues.

4.1.1. Function Redraw

Sharing the name of its category, this functions only functions is to redraw declaration lines according to the Essence specification. While most modelling languages do not give a high value on the connection location of a lines, Essence does put meaning behind this, and is restricted in the locations where this is allowed.

Tools are not able to deal with this properly, supporting code helps to demand this behavior. However, to allow the modellers some freedom in arranging the lines themselves, the function has to be manually started, in contrast to an automated feature.

This functions is a selective version of the 'Straighten all' function that is listed under the diagram. Whereas the diagram function will apply the function to all declaration lines known, the redraw function will only apply it on the symbols selected.

How to use

This function is used by selecting the option in the given menu. It will then redraw the symbols that are selected. The function will accept both concepts as declarations being selection. If a concept is selected it will redraw all of the declaration lines connected, from both its definition as its behavior. Would a declaration be selected, the function will only redraw the declaration that was selected.

4.2. Category RepairThe repair category contains functions to help the modeller with the creation of a valid view. The Essence model is, in IBM Rational System Architect, contained within the definition. This makes it easy to create new views with the existing concepts. The functions that are listed in the repair category help to make the model valid again.

Essence in IBM Rational System Architect 21

Page 22: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

4.2.1. Function Determine

The function Determine allows to quickly add the definition of a concept to the diagram. It will only add the concepts which are not already visible on the diagram.

In the example below, if the function is used on Student, the concepts Human and School will be added to the diagram.

4.2.2. Function Redefine

The function Redefine can be used to add indirect declarations to an above concept. It will not add the concepts themselves, but instead create a composite declaration between the selected concept and bottom concept in it's definition.

To illustrate with the example used previously in this guide. A Student is a Human, whereas a Human is a Mammal. In illustration 24 the concept Human is left outside of the view. This makes the view invalid, as the student's definition is incomplete.

When the function Redefine is used on the concept Student, the program will look in the definition for the first concept in its definition that is visible on the diagram. There is no limit to the range it checks, and should eventually reach the horizon.

Do note that, if the topmost concept does not contain a valid definition, the function will not be able to resolve this properly. For instance, if Mammal has no definition and is not shown on the view of illustration 24, using redefine wont have any influence on the diagram.

Essence in IBM Rational System Architect

Illustration 23: Concept without definition

Illustration 22: Concept with definition

Illustration 24: before using redefine Illustration 25: After using redefine

22

Page 23: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

4.3. Category ReviewThe last of the function categories provides functions which help the users to navigate through the models. This by concealing or revealing the concepts that are within the model. This can be done by concepts individually or for an entire substructure.

4.3.1. Function Conceal

The function conceal allows the modeller to remove a concept from the view. Composite declarations, linking the definition to the removed concept's behavior, will be created to 'replace' the concept that was concealed.

4.3.2. Function Reveal

With a diagram containing composite declaration, it is possible with this function to reveal the concepts that where concealed by the selected composite declaration. The program will automatically sort out other composite declaration and update them to reflect correctly to the new view.

4.3.3. Function Collapse

The last function, Collapse, gives the modeller the option to put a concept directly under the horizon, thereby collapsing the model above it. The program will sort out which of the concepts of its definition are able to be omitted from the view.

Given is illustration 26 to give an example of this behavior. In this example we want to put Student directly under the horizon. When the prompt function is used it will search in its definition for concepts to omit.

Concepts Human and School, marked in green, both can be omitted from the view without changing the definition of other concepts.

However, the concept Mammal cannot be removed, as it is part of the definition of the concept Monkey.

The function will then omit Human and School from the view, and create a composite declaration between Student and Mammal, as well as Student and the horizon.

This allows for Student to be close to be under the horizon, without affecting the definition of other concepts in the model.

Essence in IBM Rational System Architect

Illustration 26: Usage of the prompt function

23

Page 24: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

5. Typical questions and answers

5.1. Straight declaration linesIt is possible that during the drawing of the declaration lines, one or more of the lines will go straight to the context (as shown in illustration 27). This can happen if the two concepts are to close to each other.

To fix this, increase the vertical distance between these concepts and use the redraw function. This will sort out the line correctly.

5.2. Declaration line runs around conceptSimilar to the issue from 5.1, when drawing declaration lines it can happen that the program will draw the line around a concept.

This happens when the concepts are to close to each other. The issue can resolved, in the same way as the described in 5.1, by increasing the vertical distance between the concepts and usage of the redraw function.

The extra space will allow the program to navigate properly to the other concept.

5.3. Declaration names shown on diagramThe examples in this guide do not show the names of the declarations. However, by default IBM Rational System Architect will show these names on the diagrams.

To remove the names of declarations from the diagram, select a declaration line and right click. Next go to “Display mode”, this will give a small pop-up. Check the box next to name, and press OK. The declaration name should now all disappear from the view.

This can also be done on the horizon, composite declarations and concepts if needed.

Essence in IBM Rational System Architect

Illustration 27: A straight declaration line

Illustration 28: Declaration line going around a concept

Illustration 29: Display Mode window, where is set to hide the names of all declarations

24

Page 25: Essence in IBM Rational System Architect User’s guide · Essence in IBM Rational System Architect User’s guide IBM Remco Havermans, IBM Netherlands Arjen van de Wetering, IBM

©2013 IBM Corporation

5.4. Updating IBM Rational System Architect with Essence

The implementation is Essence is made to persist during updates. Therefore, updating IBM Rational System Architect should not influence the Essence implementation setup.

However, it can become possible that the macro is lost or the supporting functions no longer work. To fix this, the steps described in section 2.2. Installation should be repeated to fix this issue.

Essence in IBM Rational System Architect 25