Using the REI to Work with Rational Rose

---

Contents

This chapter is organized as follows:

• Introduction
• Getting the Rose Application Object
• Associating Files and URLs with Classes
• Managing Default Properties
• Adding a Property to a Set
• Creating a New Property
• Deleting Model Properties
• Getting Model Properties
• Setting Model Properties
• Creating a New Property Set
• Cloning a Property Set
• Deleting a Property Set
• Getting and Setting the Current Property Set
• Creating a User-Defined Property Type
• Creating a New Tool
• Placing Classes in Categories
• Using Type Libraries for Rose Automation
• Working with Controllable Units
• Working with Rose Diagrams
• Getting an Element from a Collection

---

Introduction

This chapter explains how to use the Rational Rose Extensibility Interface (REI) to accomplish many tasks that you would otherwise perform manually in the Rose user interface.

This information is meant to orient you and to provide examples that you can use as starting points in your work with the REI.

The information in this chapter is not exhaustive. You should refer to the Extensibility online Help for complete descriptions of all of the REI classes, properties, and methods. As you familiarize yourself with these, you will be able to realize the full capabilities that the REI makes available to you.

---

Getting the Rose Application Object

Whether you are using Rose Script or Rose Automation, you must get the Rose Application object in order to control the Rose application.

Using Rose Script

All Rose Script programs have a global object called RoseApp, which has a property called CurrentModel. You must use RoseApp.CurrentModel to initialize the global Rose object and subsequently open, control, save, or close a Rose model from within a script.

The following sample code shows how to get the Rose Application object in a Rose Scripting context:

Sub GenerateCode (theModel As Model)

 ` This generates code

End Sub

Sub Main

 GenerateCode RoseApp.CurrentModel

End Sub

Using Rose Automation

To use Rose as an automation server, you must initialize an instance of a Rose application object. You do this by calling either CreateObject or GetObject (or their equivalents) from within the application you are using as the OLE controller. These calls return the OLE Object which implements Rose API's application object.

Refer to the documentation for the application you are using as OLE controller for details on calling OLE automation objects.

The following sample code shows how to get the Rose application object in a Rose Automation context:

Sub GenerateCode (theModel As Object)

` This generates code

End Sub

Sub Main

Dim RoseApp As Object

Set RoseApp = CreateObject ("Rose.Application")

GenerateCode RoseApp.CurrentModel

End Sub

---

Associating Files and URLs with Classes

Because Class objects inherit properties from RoseItem, you can define a set of external documents for any class. Each external document has either a Path property or a URL property.

• The Path property specifies a path to the file that contains the external document.
• The URL property specifies a Universal Resource Locator (URL) of a corresponding internet document.

Note: See the Extensibility online Help for syntax and other information.

---

Managing Default Properties

In the Rose user interface environment, you manage a model's properties by using the specification editor.

To access the specification editor, click Tools > Model Properties > Edit.

You then select the appropriate tool tab, element type, and property set to edit. For example, in Figure 6, the tool is Java, the model element type is Class, and the property set is Set1.

Figure 6 Property Specification Editor

From this point on, you can use the specification editor to edit individual properties, as well as clone (copy) and edit property sets. However, you cannot create new tools (tabs), new default property sets, or property types. For these capabilities, you must use the Rose Extensibility Interface.

For more information on editing default properties and sets in the Rose user interface, see the online Help for information on specifications, or refer to the Using Rose manual.

The next sections of this chapter explain how to work with properties and property sets in the extensibility environment.

In the Extensibility Interface, the DefaultModelProperties object manages the default model properties for the current model, and is itself a property of the model (expressed as RoseApp.CurrentModel.DefaultProperties). For this reason, default properties are applied to the current model only. When you create default properties they are applied to and saved for the current model, but are not available to any new models you create.

To apply new properties to another model, re-run the script that creates the properties, specifying the new model as the current model.

---

Adding a Property to a Set

How To

To add a property to a property set, define a subroutine that uses the DefaultModelProperties.AddDefaultProperty method. You will notice that this method requires you to pass 6 parameters:

• Class Name
• Tool Name
• Set Name
• Name of the New Property
• Property Type
• Value of the New Property

Example

Sub AddDefaultProperties (theModel As Model)

Dim DefaultProps As DefaultModelProperties

Set DefaultProps = theModel.DefaultProperties

myClass$ = theModel.RootCategory.GetPropertyClassName ()

b = DefaultProps.AddDefaultProperty (myClass$, 

"ThisTool", "Set1", "StringProperty", "String", "")

b = DefaultProps.AddDefaultProperty (myClass$, 

myTool$, "Set1", "IntegerProperty", "Integer", "0")

b = DefaultProps.AddDefaultProperty (myClass$, 

myTool$, "Set1", "FloatProperty", "Float", "0")

b = DefaultProps.AddDefaultProperty (myClass$, 

myTool$, "Set1", "CharProperty", "Char", " ")

b = DefaultProps.AddDefaultProperty (myClass$, 

myTool$, "Set1", "BooleanProperty", "Boolean", "True")

End Sub

Notes on the Example

1 When you specify the Class Name parameter, you must specify the internal name of the model element. There are two ways to obtain this information:

• If properties are already defined for this element, the internal name appears in the specification dialog box in the Rose user interface. Simply check the specification editor and use the Type drop-down list to find the appropriate class name.
• Use the Element.GetPropertyClassName method. This is the method used in the sample script. This example retrieves the internal name and returns it in myClass$, which is then passed as the class name parameter.

2 If the tool you specify does not exist, a new tool will be created. This is actually the only way to add a new tool to a model.

3 This example adds a property of each of the predefined property types (string, integer, float, char, boolean), with the exception of the enumeration type. You use the enumerated type to create your own property types and add enumerated properties to a set. See Creating a User-Defined Property Type for instructions and an example.

---

Creating a New Property

How To

To create a new property that is not based on an existing property, use the Element.CreateProperty method. However, if you simply want to set an existing property to a different current value, you should use Element.InheritProperty or Element.OverrideProperty instead.

Example

' Property creation:

b = theModel.RootCategory.CreateProperty (myTool, 

"Saved", "True", "Boolean")

b = theModel.RootCategory.InheritProperty (myTool, "Saved")

Notes on the Example

1 The CreateProperty call in the example creates a new property called Saved. It applies to the tool MyTool, its value is TRUE, and its type is Boolean.

2 The InheritProperty call in the example deletes the property just created. Because there is no default value to which such a property can return, InheritProperty effectively deletes it from the model.

3 For more information, see Setting Model Properties Using InheritProperty, Setting Model Properties Using OverrideProperty, and Deleting Model Properties.

---

Deleting Model Properties

If you are deleting a property that belongs to a property set, you can use the DefaultModelProperties.DeleteDefaultProperty method to delete the property from a model.

However, if you created a property using the Element.CreateProperty method, that property is not part of a property set. To delete such a property, use the Element.InheritProperty method.

---

Getting Model Properties

The Element class provides two methods for retrieving information about model properties:

• To get the current value for a model property, whether inherited or overridden, use the Element.GetPropertyValue method. This method returns the value as a string.
• To retrieve the property object itself, use the Element.FindProperty method.

---

Setting Model Properties

There are several ways to set model properties using the Extensibility Interface:

• Use the Element.OverrideProperty method to change only the value of a property, and keep all other aspects of the property definition intact.
• Use the Element.InheritProperty method to return a previously overridden property to its original value.
• Use the Element.CreateProperty or the DefaultModelProperties.AddDefaultProperty method to define a new property that is not based on an existing property.

For more information, see Creating a New Property. For more information on creating new properties that are based on an existing property set, see Cloning a Property Set.

Setting Model Properties Using OverrideProperty

How To

The Element.OverrideProperty method allows you to use the default property definition and simply change its current value. Alternately, you could create a brand new property by calling the Element.CreateProperty method, but that would require you to specify the complete property definition, not just the new value.

If the property you specify does not exist in the model's default set, a new property is created for the specified object only. This new property is created as a string property.

Example

Sub OverrideRadioProps (theCategory As Category)

b = theCategory.OverrideProperty (myTool$, "StringProperty", "This 
string is overridden")

b = theCategory.OverrideProperty (myTool$, "IntegerProperty", "1")

b = theCategory.OverrideProperty (myTool$, "FloatProperty", 
"111.1")

b = theCategory.OverrideProperty (myTool$, "EnumeratedProperty", 
"Value2")

End Sub

Notes on the Example

1 Each of the 4 lines of the sample subroutine changes the current value of a specific property as follows:

• The property called StringProperty now has a value of "This string is overridden".
• The property called IntegerProperty now has a value of 1.
• The property called FloatProperty now has a value of 111.1.
• The property called EnumeratedProperty now has a value of "Value2".

2 Everything except for current value (tool name, class name, set, property name, and property type) remains the same for the properties.

Setting Model Properties Using InheritProperty

How To

Use the Element.InheritProperty method to reset an overridden property to its original value.

You can also use this method to delete a property that you created using the Element.CreateProperty method. Because there is no default value to which such a property can return, InheritProperty effectively deletes it from the model.

Example

Sub InheritRadioProps (theCategory As Category)

b = theCategory.InheritProperty (myTool$, "StringProperty")

b = theCategory.InheritProperty (myTool$, "IntegerProperty")

b = theCategory.InheritProperty (myTool$, "FloatProperty")

b = theCategory.InheritProperty (myTool$, 

"EnumeratedProperty")

End Sub

Notes on the Example

Each of the 4 lines of the sample subroutine returns the current value of the specified property to its original value.

---

Creating a New Property Set

To create a new property set that is not based on an existing property set, use the DefaultModelProperties.CreateDefaultPropertySet method.

---

Cloning a Property Set

How To

Cloning allows you to create a copy of an existing property set for the purpose of creating another property set. This is the easiest way to create a new property set, and is particularly useful for creating multiple sets of the same properties, but with different values specified for some or all of the properties.

To clone a property set in a model, use the DefaultModelProperties.CloneDefaultPropertySet method.

Example

Sub CloneDefaultProperties (theModel As Model)

Dim DefaultProps As DefaultModelProperties

Set DefaultProps = theModel.DefaultProperties

AddDefaultProperties theModel

myClass$ = theModel.RootCategory.GetPropertyClassName ()

b = DefaultProps.CloneDefaultPropertySet (myClass$, myTool$, 
"default", "SecondSet")

b = DefaultProps.CloneDefaultPropertySet (myClass$, myTool$, 
"default", "ThirdSet")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, 
"SecondSet", "StringProperty", "String", "Unique to SecondSet")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, 
"SecondSet", "IntegerProperty", "Integer", "11")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, 
"SecondSet", "FloatProperty", "Float", "89.9000")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, 
"SecondSet", "EnumeratedProperty", "EnumerationDefinition", 
"Value2")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, "ThirdSet", 
"StringProperty", "String", "Unique to ThirdSet")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, "ThirdSet", 
"IntegerProperty", "Integer", "20")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, "ThirdSet", 
"FloatProperty", "Float", "90.9000")

b = DefaultProps.AddDefaultProperty (myClass$, myTool$, "ThirdSet", 
"EnumeratedProperty", "EnumerationDefinition", "Value3")

End Sub

Notes on the Example

1 This example clones an existing property set twice in order to define a total of three sets for the class and tool to which the sets apply.

2 All three sets have the same properties as those defined in the original set. In addition, several new properties are added to the second set and several other new properties are added to the third set.

---

Deleting a Property Set

How To

To delete an entire property set from a model, use the DefaultModelProperties.DeleteDefaultPropertySet method.

Example

Sub DeleteDefaultProperties (theModel As Model)

Dim DefaultProps As DefaultModelProperties

Set DefaultProps = theModel.DefaultProperties

myClass$ = theModel.RootCategory.GetPropertyClassName ()

b = DefaultProps.DeleteDefaultPropertySet (myClass$, 

myTool$, "SecondSet")

b = DefaultProps.DeleteDefaultPropertySet (myClass$, 

myTool$, "ThirdSet")

b = theModel.RootCategory.SetCurrentPropertySetName 

(myTool$, "default")

End Sub

Notes on the Example

1 The Element.GetPropertyClassName retrieves the valid internal class name to pass as a parameter on the delete calls.

2 Each DefaultModelProperties.DeleteDefaultPropertySet call deletes a property set from the model.

3 The Element.SetCurrentPropertySetName call sets the tool's current property set to its original set, which happens to be called default.

---

Getting and Setting the Current Property Set

How To

To find out which property set is the current set for a tool, use the Element.GetCurrentPropertySetName method.

To set the current property set to a particular set name, use the Element.SetCurrentPropertySetName and specify the set of your choice.

Note: When setting the current property set, you must supply a set name that is valid for the specified tool. To retrieve a list of valid set names for a tool, use Element.GetDefaultSetNames.

Example

Sub RetrieveElementProperties (theElement As Element)

Dim AllTools As StringCollection

Dim theProperties As PropertyCollection

Dim theProperty As Property

Set AllTools = theElement.GetToolNames ()

For ToolID = 1 To AllTools.Count

ThisTool$ = AllTools.GetAt (ToolID)

theSet$ = theElement.GetCurrentPropertySetName (ThisTool$)

Set theProperties = theElement.GetToolProperties (ThisTool$)

For PropID = 1 To theProperties.Count

Set theProperty = theProperties.GetAt (PropID)

Next PropID

Next ToolID

End Sub

Notes on the Example

1 GetToolNames retrieves the tool names that apply to the model element type called Element and returns them as a string collection called AllTools.

2 The current property set is retrieved for each tool name.

3 GetToolProperties retrieves the property collection that belongs to the current tool.

4 Each property that belongs to the tool's property collection is retrieved.

---

Creating a User-Defined Property Type

How To

Rose Extensibility predefines the following set of property types:

• String
• Integer
• Float
• Char
• Boolean
• Enumeration

When you add properties to a set, you specify one of these types.

In addition, you can define your own property types and add properties of that type to a property set.

To create a user-defined property type, add a property whose type is enumeration and whose value is a string that defines the possible values for the enumeration.

Once you have defined the new type, adding a property of this new type is like adding any other type of property.

Example

Sub AddDefaultProperties (theModel As Model)

Dim DefaultProps As DefaultModelProperties

Set DefaultProps = theModel.DefaultProperties

myClass$ = theModel.RootCategory.GetPropertyClassName ()

b = DefaultProps.AddDefaultProperty (myClass$, "myTool", 

"Set1", "MyNewEnumeration", "Enumeration", 

"Value1,Value2,Value3")

b = DefaultProps.AddDefaultProperty (myClass$, "myTool", 

"Set1", "MyEnumeratedProperty", "MyNewEnumeration", 

"Value1")

b = DefaultProps.AddDefaultProperty (myClass$, "myTool", 

"Set1", "isAppropriate", "Boolean", "True")

b = DefaultProps.AddDefaultProperty (myClass$, "myTool", 

"Set1", "mySpace", "Integer", "5")

End Sub

Sub Main

AddDefaultProperties (RoseApp.CurrentModel)

End Sub

Notes on the Example

1 This example uses Element.GetPropertyClassName to retrieve the internal name of the class to which the property type will apply.

2 The first AddDefaultProperty call adds the enumeration and defines its possible values in the string "Value1, Value2, Value3".

3 The second AddDefaultProperty call adds a new property of the new enumerated type; the property value is set to "Value1".

4 If you want a new type to appear in the specification dialog box in the Rose user interface, you must actually add a property of that type to the set. Using the above example, if you simply created the type MyNewEnumeration, but did not add the property MyEnumeratedProperty, MyNewEnumeration would not appear in the Type drop-down list. Once you add the actual property, MyNewEnumeration would appear in the list of types.

---

Creating a New Tool

There is no explicit way to add a new tool (tab) to a model. However, when you create a new property set or add a new property to a model, you must specify the tool to which the property or set applies. If the tool you specify does not already exist, it will be added during the create or add process.

---

Placing Classes in Categories

• To create a new class and place it in a category, use the Category.AddClass method.
• To relocate an existing class from one category to another, use the Category.RelocateClass method.

---

Using Type Libraries for Rose Automation

How To

When you specify an REI class in an automation environment, you must add the prefix Rose to the class name, unless the word Rose is already part of the REI class name.

For more information on using Type Libraries with Rose, see Rose Extensibility Type Libraries.

Example

• In Rose Script, the syntax for retrieving the Root Category of a model (that is, its logical view) is:

  Model.RootCategory
  

• In Rose Automation, the syntax for retrieving the Root Category of a model is:

  RoseModel.RootCategory
  

• In both Rose Script and Rose Automation, the syntax for retrieving the documentation belonging to a RoseItem is:

  RoseItem.Documentation
  

---

Working with Controllable Units

Working with controllable units allows you to divide a model into smaller units. This is particularly useful for multi-user development, as well as for placing a model under configuration management.

The methods that apply to working with controllable units are:

• ControllableUnit.Control method, which associates a controllable unit with a file name, so that it can be passed to a configuration management application.
• ControllableUnit.Uncontrol method, which removes the file association from the unit.
• ControllableUnit.Load and Unload methods, which load or unload parts of a model (for example, the units for which a person is responsible).
• ControllableUnit.Save or ControllableUnit.SaveAs methods, which actually write the specified controllable unit to a file.

Note: When you save a model, that will also save its controllable units.

---

Working with Rose Diagrams

Each kind of Rose diagram (class, component, scenario, and so on) inherits from the Diagram class.

A diagram is made up of RoseItem and RoseItemView objects. A RoseItemview object is the visual representation of the actual RoseItem object. As such, it is an object with properties and methods that define its appearance in the diagram window (position, color, size, and so on). You can define multiple RoseItemView objects for any given RoseItem object.

• Use the Diagram.ItemViews method to iterate through the collection of RoseItemView objects belonging to a diagram.
• Use the Diagram.Items method to iterate through the RoseItem objects that exist in the diagram.
• Use the Diagram.GetViewFrom method to find the first RoseItemView object of a given RoseItem object.

  Note: You can only use the GetViewFrom method to retrieve the first RoseItemView object defined for the RoseItem object. Even if you have more than one RoseItemView object, you always only get the first.

• To find out which RoseItemView objects are currently selected in a diagram, iterate through the diagram's RoseItemView collection. As you retrieve each RoseItemView object, use the ItemView.IsSelected method to find out whether the RoseItemView object is currently selected in the diagram. You can then retrieve the selected RoseItemView object, or do any other processing you wish to do based on whether the RoseItemView object is selected.
• A short way to retrieve all selected RoseItemView objects from a diagram is to use the Diagram.GetSelectedItems method. Instead of iterating through the diagram and checking each RoseItemView object, this method simply returns everything that is selected.

---

Getting an Element from a Collection

There are three ways to get an individual model element from a collection:

• Use the GetwithUniqueID method to directly access the element.
• Iterate through the collection using the element's name using FindFirst, FindNext, and GetAt.
• Iterate through the collection using Count followed by GetAt.

For more information, check the online Help for Collection Properties and Methods.

Accessing Collection Elements by Count

How To

To access collection elements by count:

1 Iterate through the collection using the Count property.

2 Retrieve the specific element using the GetAt method when the specific element is found.

Example

Dim AllClasses As ClassCollection

Dim theClass As Class

For ClsID = 1 To AllClasses.Count

Set theClass = AllClasses.GetAt (ClsID)

' ToDo: Add your code here...

Next ClsID 

Accessing Collection Elements by Unique ID

How To

The most direct and easiest way to get an element from within a collection is by unique ID. To access collection elements by unique ID:

1 Use the GetUniqueID method to obtain the element's unique ID.

2 Use the GetwithUniqueID method, specifying the ID you obtained in step 1.

Example

Dim theClasses As ElementCollection

Dim theClass As Element

theID =theClasses.theClass.GetUniqueID ()

theClass = theClass.GetwithUniqueID (theID)

Accessing Collection Elements by Name

How To

To access an operation belonging to a class:

1 Use FindFirst to find the first occurrence of the specified operation in the collection.

2 Use FindNext to iterate through subsequent occurrences of the operation.

3 Retrieve the specific operation using the GetAt method when the specific operation is found.

Example

Sub PrintOperations (theClass As Class, OperationName As

 String)

Dim theOperation As Operation

OperID = theClass.Operations.FindFirst (OperationName$)

Do

Set theOperation = theClass.Operations.GetAt (OperID)

' ToDo:  Add your code here...

OperID = theClass.Operations.FindNext (OperID,

  OperationName$)

Loop Until OperID = 0

End Sub