Chapter 7. Writing UML Profiles

Basic Concept of UML Profile

UML Extension Mechanisms

UML is a universal software modeling language that provides an abundance of well-defined modeling concepts and notations to meet all the requirements of general software modeling. Nevertheless, the software modeling/development environment today can take many different forms, and there may be requirements for elements or semantics that do not exist in the UML standard. By default, UML provides concepts for supporting such requirements, and they are called the UML Extension Mechanisms.

UML Extension Mechanisms use Stereotypes, Constraints, Tag Definitions, and Tagged Values to extend the semantics of UML modeling elements or define the UML modeling elements with new semantics.

Stereotype

A stereotype is a modeling element that has definitions for adding new properties and constraints to the standard UML modeling elements. A stereotype can also have definitions to provide new notations for modeling elements. The illustration below is the stereotype selection dialog that appears when clicking on the stereotype selection button in the StarUML™ application. The stereotype selection dialog displays a list of the selectable stereotypes defined in the UML profile that is included in the current project. Stereotypes can also be configured or modified through external API. Details on this will be described later.

Note: Although the UML standard allows each extensible modeling element to have multiple stereotypes, StarUML™ limits each modeling element to only one stereotype.

Tag Definitions

Tag definition is an element that defines new properties that can be added to certain modeling elements. And definitions of the values of the properties added to elements by tag definitions are called Tagged Values. A tagged value can be a basic datatype value, a reference to other modeling elements, or a collection. The following illustration is the extension property editor screen in the StarUML™ application. The extension property editor displays a list of the tag definition items that belong to the selected modeling element as defined by the UML profile. Tagged values of modeling elements can also be configured or modified through external API. Details on this will be described later.

Constraints

A constraint adds a specific constraint to a certain modeling element to allow redefinition of the semantics for the selected modeling element. For descriptions of constraints, please refer to the section "ExtCore Elements" in "Chapter 4. Using Open API".

Note: StarUML™ UML profile excludes definitions of constraints.

UML Profile

UML profile is a package of UML extension mechanisms. In other words, it is a collection of stereotypes, constraints, tag definitions, and data types that are required for a certain software domain or development platform.

A UML profile consists of Stereotype, Constraint, Tag Definition, and Data Type elements. Although the UML standard requires a profile to be defined as a package element with the "<<profile>>" stereotype, StarUML™ allows it to be defined as an XML formatted file for easier use.

Additional Extension Mechanism in the StarUML

StarUML profile supports a few of additional extension mechanism with predefined in UML. They are the Diagram Type, Element Prototype, Model Prototype, Palette Extension. These extension mechanism extend semantics of the existing elements or provide regular methods for creating the element and apply it to user interface.

Diagram Type

Diagram Type is extension element to define new diagram that has additional semantics based on UML standard diagram. It is useful to define specialized diagram in each phase of design that is data model diagram, robustness analysis diagram, and so on or to apply many kind of diagrams used in various domains to StarUML. Diagram type name is assigned as the "DiagramType" property of the diagram. "DiagramType" property can't be changed as opposed to stereotype. When profile is included in project, it is added in the [Add Diagram] menu and let user be able to create a diagram as the diagram type.

Element Prototype

Element prototype defines a sample for element creating which properties are preset. User can create an element with copy of sample by registering element prototype in the palette or using external API.

Model Prototype

Model prototype only can be applied to model even if it is similar to element prototype. It is inserted in the [Add Model] as submenu on element prototype in palette. A model element that is copy of the sample can be created by the menu.

Palette Extension

Palette extension allows to insert additional palette that appears in the left of main form. Added palette can designate element prototypes or UML standard elements defined in the profile as palette items.

Profile Includes and Excludes

If a UML profile is required for the current project in the StarUML™ application, the profile must be added to the project. This is because no profiles other than "UML Standard Profile" are added automatically. To add profiles in the StarUML™ application, use the profile dialog (illustrated below) that can be executed by clicking the [Model] -> [Profiles…] menu. The "Available Profiles" list on the left shows the list of the profiles currently registered in the user system, and the "Included Profiles" list on the right shows the list of the profiles included in the current project. Adding a profile can be done simply by selecting a profile from the "Available Profiles" list, and clicking the "Include" button in the center. Once a profile is added, the stereotypes and tag definitions defined in the new profile are added to the stereotype selection dialog and extension property editor as shown above. If a profile is no longer required in the current project, simply click the "Exclude" button to remove it from the project. Care should be taken, since excluding a profile results in the removal of all information referenced by the profile in the project. Profiles can also be included or excluded through external API. Details on this will be described later.

Creating UML Profile

Basic Structure of Profile Document File

A profile document file is defined in the XML format, and the extension name is .prf (PLASTIC Profile File). The contents of the profile are enclosed by the PROFILE tag. There must not be any errors in syntax or contents.

The basic profile document structure is as follows.

<?xml version=”1.0” encoding=”...” ?>
<PROFILE version="..."> 
    <HEADER>
        ...
    </HEADER>
    <BODY>
        ...
    </BODY>
</PROFILE>

encoding property: Defines value for encoding the property of the XML document (e.g. UTF-8, EUC-KR). For details on this value, see XML reference resources.
version property (PROFILE element): This is the version of the PRF document (e.g. 1.0).
HEADER element: See the Header Contents section.
BODY element: See the Body Contents section.

Header Contents

The HEADER section of a profile document contains general information for the profile, such as the profile name and description.

<HEADER>
    <NAME>...</NAME>
    <DISPLAYNAME>...</DISPLAYNAME>
    <DESCRIPTION>...</DESCRIPTION>
    <AUTOINCLUDE>...</AUTOINCLUDE>
</HEADER>

NAME element: Contains the profile name. This acts as the profile ID.
DISPLAYNAME element: This is the caption name used in the profile dialog and other user interfaces.
DESCRIPTION element: Contains the description of the profile.
AUTOINCLUDE element: Specifies whether includes the profile automatically when creates new project.

Body Contents

The BODY section of a profile document contains the actual contents of the profile. This section can contain information for Stereotypes, Datatypes, TagDefinitionSets, and addtional extension elements.

<BODY>
    <STEREOTYPELIST>
        ...
    </STEREOTYPELIST>
    <TAGDEFINITIONSETLIST>
        ...
    </TAGDEFINITIONSETLIST>
    <DATATYPELIST>
        ...
    </DATATYPELIST>
    <ELEMENTPROTOTYPELIST>
        ...
    </ELEMENTPROTOTYPELIST>
    <MODELPROTOTYPELIST>
        ...
    </MODELPROTOTYPELIST>
    <PALETTELIST>
        ...
    </PALETTELIST>
    <DIAGRAMTYPELIST>
        ...
    </DIAGRAMTYPELIST>
</BODY>

STEREOTYPELIST element: Defines multiple stereotypes (STEREOTYPE elements). For definition of stereotypes, see the Stereotype section.
TAGDEFINITIONSETLIST element: Defines multiple tag definition sets (TAGDEFINITIONSET elements). For definition of tag definition sets, see the TagDefinitionSet section.
DATATYPELIST element: Defines multiple data types (DATATYPE elements). For definition of data types, see the DataType section.
ELEMENTPROTOTYPELIST element: Defines multiple element prototypes (ELEMENTPROTOTYPE elements). For definition of element prototypes, see the ElementPrototype section.
MODELPROTOTYPELIST element: Defines multiple model prototypes (MODELPROTOTYPE elements). For definition of model prototypes, see the ModelPrototype section.
PALETTELIST element: Defines multiple palette extensions (PALETTE elements). For definition of palette extension, see Palette section.
DIAGRAMTYPELIST element: Defines multiple diagram types (DIAGRAMTYPE elements). For definition of diagram type, see DiagramType section.

Stereotype

The STEREOTYPE element defines information for stereotype and the inheritance structure.

<STEREOTYPE>
    <NAME>...</NAME>
    <DESCRIPTION>...</DESCRIPTION>
    <BASECLASSES>
        <BASECLASS>...</BASECLASS>
        ...
    </BASECLASSES>
    <PARENT>...</PARENT>
    <RELATEDTAGDEFINITIONSET>...</RELATEDTAGDEFINITIONSET>
    <ICON minWidth=”...” minHeight=”...”>...</ICON>
    <NOTATION>...</NOTATION>
</STEREOTYPE>

NAME element: Contains the name of the stereotype. This has to be a unique value within the profile.
DESCRIPTION element: Contains the description for the stereotype.
BASECLASSES element: May contain names of multiple UML modeling elements that can be applied with the stereotype. The names of the elements used here are the names of the UML elements (e.g., UMLClass, UMLClassifier, UMLAttribute, UMLPackage, ...).
Note: If the name of an abstract class like UMLClassifier is used, all the elements inherited from it are applied. If the upper-level stereotype (PARENT element) is defined, this section is not defined; any definition in this section is ignored and the BASECLASSES value of the upper-level stereotype is applied.
PARENT element: Stereotypes can have inheritance relationships. The PARENT element contains the name of the upper-level stereotype. Stereotypes in an inheritance relationship must be defined within the same profile. This can be left undefined or omitted if there is no upper-level stereotype.
RELATEDTAGDEFINITIONSET element: Contains the name of the TagDefinitionSet related to the stereotype. This can be interpreted as a set of additional properties provided by the stereotype to the elements, may be omitted if there is none. The tag definition set defined here must also be defined within the same profile.
ICON element: A stereotype can also be indicated by an icon, depending on user selection. This element contains the name of the icon file for the stereotype. Stereotype icon files can be .WMF, .EMF or .BMP files. Icon files must be located in the same directory as the profile document. The profile document contains the icon file names without the path names.
minWidth property (ICON element): Defines the minimum width of the stereotype icon.
minHeight property (ICON element): Defines the minimum height of the stereotype icon.
NOTATION element: Stereotype can not be displayed by iconic style but also redefine drawing method by using notation description language. This element contains the name of the notation extension file(.nxt) to define the notation. The element with notation extension will draw as described by notation extension file not to draw as UML standard. Notation extension file must be placed in the directory of profile document. It must be specified only the file name except directory path in this element.

TagDefinitionSet

TAGDEFINITIONSET 요소에는 태그요소집합의 기본 정보를 기술하고, TADDEFINITIONLIST 요소 밑에 여러 개의 TAGDEFINITION 요소를 두어 태그정의집합에 포함된 태그정의들을 나열한다.

The TAGDEFINITIONSET element contains basic information on tag definition set, and includes multiple TAGDEFINITION elements under the TADDEFINITIONLIST element to list tag definitions included in the tag definition set.

<TAGDEFINITIONSET>
    <NAME>...</NAME>
    <BASECLASSES>
        <BASECLASS>...</BASECLASS>
        ...
    </BASECLASSES>
    <TAGDEFINITIONLIST>
        ...
    </TAGDEFINITIONLIST>
</TAGDEFINITIONSET>

NAME element: Contains the name of the tag definition set. If the tag definitions concern a specific stereotype, using the name of the stereotype is recommended (in this case, if a tag definition set of the same name as a stereotype exists, it will be displayed first in the user interface).
BASECLASSES element: Contains the names of the UML elements to apply the tag definition set (applied in the same way as the BASECLASSES element of the STEREOTYPE). If the tag definition set is defined as related to a specific stereotype, this element is not defined; any definition in this element is ignored and is recognized as BASECLASSES of the respective stereotype.
TAGDEFINITIONLIST element: Contains multiple TagDefinitions included in the set. See the TagDefinition section.

TagDefinition

TAGDEFINITIONLIST element: Contains multiple TagDefinitions included in the set. See the TagDefinition section.

<TAGDEFINITION lock=”...”>
    <NAME>...</NAME>
    <TAGTYPE referenceType=”...”>...</TAGTYPE>
    <DEFAULTDATAVALUE>...</DEFAULTDATAVALUE>
    <LITERALS>
        <LITERAL>...</LITERAL>
        ....
    </LITERALS>
</TAGDEFINITION>

lock property (TAGDEFINITION element): Configures whether to allow editing of tagged values from the UI. If set as "True", tagged values can be edited only through an external COM interface and the extension property editor cannot be used. This property may be omitted, in which case the default value is "False".
NAME element: This is the name of the tag. This must be unique within the TagDefinitionSet.
TAGTYPE element: This is the type of the tag. This can be any of the 5 types: Integer, Boolean, Real, String, Enumeration, Reference, or Collection.
referenceType property (TAGTYPE element): Defines what types of object references are allowed when the tag type is Reference or Collection. For example, defining this as "UMLClass" permits connection of Class types only. If omitted, the default value is "UMLModelElement". This property is ignored if the tag type is Integer, Boolean, Real, String, or Enumeration.
DEFAULTVALUE element: Contains the default value of the tag. This element is ignored and the default value is set as null for Reference Type or Collection Type.
LITERALS element: Defines the literals to enumerate if the tag type is Enumeration. This is ignored for other types.

DataType

DATATYPE element defines one data type. This element has a sub-element called NAME.

<DATATYPE>
    <NAME>...</NAME>
</DATATYPE>

NAME element: Contains the name of the data type.

ElementPrototype

ELEMENTPROTOTYPE element describes information of element prototype that defines the pattern of element creating.

<ELEMENTPROTOTYPE>
    <NAME>....</NAME>
    <DISPLAYNAME>....</DISPLAYNAME>
    <ICON>....</ICON>
    <DRAGTYPE>....</DRAGTYPE>
    <BASEELEMENT argument=”...”>....</BASEELEMENT>
    <STEREOTYPENAME>....</STEREOTYPENAME>
    <STEREOTYPEDISPLAY>....</STEREOTYPEDISPLAY>
    <SHOWEXTENDEDNOTATION>....</SHOWEXTENDEDNOTATION>
    <MODELPROPERTYLIST>
        <MODELPROPERTY name=”...”>....</MODELPROPERTY>
        ....
    </MODELPROPERTYLIST>
    <VIEWPROPERTYLIST>
        <VIEWPROPERTY name=”...”>....</VIEWPROPERTY>
        ....
    </VIEWPROPERTYLIST>
    <TAGGEDVALUELIST>
        <TAGGEDVALUE profile=”...” tagDefinitionSet=”...” tagDefinition=”...”> </TAGGEDVALUE>
        ....
    </TAGGEDVALUELIST>
</ELEMENTPROTOTYPE>

NAME element: This is the name of the element prototype. This must be unique within the profile.
DISPLAYNAME element: Contains the display name used in the user interface like a palette.
ICON element: This element contains the name of the icon file for the element prototype using in the user interface like a palette. The icon file of the element prototype must be .BMP formatted image file 16 X 16 sized. The icon file must be placed in the directory of profile document. It must be specified only the file name except directory path in this element.
DRAGTYPE element: In order to create the relative element for the element prototype, the user specifies how to show when specifying location and size as the user dragging mouse on diagram. It's value must be one of: Rect or Line.

BASEELEMENT element: Specifies the name of UML standard element based to create copy of element prototype. This element can not be omitted. If this element is not specified, the element prototype can't be recognized.
The names of available UML standard elements are as follows.
　

Element names
Text Note NoteLink Model Subsystem Package Class Interface Enumeration Signal Exception Component ComponentInstance Node NodeInstance Actor UseCase StateMachine ActivityGraph Collaboration	CollaborationInstanceSet Interaction InteractionInstanceSet CompositeState State ActionState Activity SubactivityState Pseudostate FinalState Partition Swimlane SubmachineState Attribute Operation Parameter TemplateParameter EnumerationLiteral UninterpretedAction SignalEvent	CallEvent TimeEvent ChangeEvent ClassifierRole Object Transition Dependency Association AssociationClass Generalization Link AssociationRole Stimulus Message Include Extend Realization ObjectFlowState FlowFinalState SystemBoundary	SignalAcceptState SignalSendState Artifact AttributeLink Port Part Connector CombinedFragment InteractionOperand Frame ExtensionPoint Rectangle Ellipse RoundRect Line Image

argument property: For some kind of elements which base element is one of Association, Pseudostate, and so on, it needs an argument to create. Specific property values of these elements are preset as argument of them. Default value of this property is 0. In most of case, it doesn't need to specify.
Argument values used in StarUML are as follows.
　

Element name	Meaning and Value
Pseudostate	Decision = 0, InitialState = 1, Synchronization = 2, Junction Point = 3, Choice Point = 4, Deep History = 5, Shallow History = 6
UninterpretedAction	Entry Action = 0, Do Activity = 1, Exit Action = 2
Stimulus	Stimulus with Call Action = 0, Stimulus with Send Action = 1, Stimulus with Return Action = 2, Stimulus with Create Action = 3, Stimulus with Destroy Action = 4, Reverse Stimulus with Call Action = 5, Reverse Stimulus with Send Action = 6, Reverse Stimulus with Return Action = 7, Reverse Stimulus with Create Action = 8, Reverse Stimulus with Destroy Action = 9
Message	Message with Call Action = 0, Message with Send Action = 1, Message with Return Action = 2, Message with Create Action = 3, Message with Destroy Action = 4, Reverse Message with Call Action = 5, Reverse Message with Send Action = 6, Reverse Message with Return Action = 7, Reverse Message with Create Action = 8, Reverse Message with Destroy Action = 9
Association	Assocation = 0, Directed Association = 1, Aggregation = 2, Composition = 3;
Swimlane	Vertical Swimlane = 0, Horizontal Swimlane = 1;

STEREOTYPENAME element: Specifies the Stereotype name of the element prototype. If specifies the value of this element, it is inputted as value of "Stereotype" property when create the model element. This element may be omitted.
STEREOTYPEDISPLAY element: Specifies how to display the stereotype when create element the model element. Value of this element must be one of: sdkText(display as text), sdkIcon(display as icon), sdkNone(does not display), sdkDecoration(display as decoration). This element may be omitted. Default value is sdkText.
SHOWEXTENDEDNOTATION element: Specifies whether to draw the element as notation extension in case of existing notation extension file(.nxt) specified in the STEREOTYPENAME element. If value is True, StarUML draws view of the element that created by element prototype as described in notation extension file. This element may be omitted. Default value is False.
MODELPROPERTYLIST element: Contains list of MODELPROPERTY elements.
MODELPROPERTY element: Specifies the value of model property in creating element. The name property that defines name of model property must be specified certainly. If value of name is not property name of base element or is invalid, the element would not be created properly.
See "Chapter 4. Using Open API" for available property names and range of the each property value.
VIEWPROPERTYLIST element: Contains list of VIEWPROPERTY elements.
VIEWPROPERTY element: Specifies the value of view property in creating element. The name property that defines name of view property must be specified certainly. If value of name is not property name of base element or is invalid, the element would not be created properly.
See "Chapter 4. Using Open API" for available property names and range of the each property value.
TAGGEDVALUELIST element: Contains list of TAGGEDVALUE elements.
TAGGEDVALUE element: Specifies the tagged value of model element in creating element. To assign tagged value, you must specify the tagDefinition defining it.
profile property (TAGGEDVALUE element) : Specifies the profile name that contains the tag definition. This element may be omitted. If omitted, the profile that ELEMENENTPROTOTYPE element belongs to is applied.
tagDefinitionSet property (TAGGEDVALUE element): Specifies the tagDefinitionSet name containing the tagDefinition.
tagDefinition property (TAGGEDVALUE element): Specifies the name of the tagDefinition.

ModelPrototype

MODELPROTOTYPE element describes information of model prototype that defines the pattern of model creating.

<MODELPROTOTYPE>
    <NAME>....</NAME>
    <DISPLAYNAME>....</DISPLAYNAME>
    <ICON>....</ICON>
    <BASEMODEL argument=”...”>....</BASEMODEL>
    <STEREOTYPENAME>....</STEREOTYPENAME>
    <PROPERTYLIST>
        <PROPERTY name=”...”>....</PROPERTY>
        ....
    </PROPERTYLIST>
    <TAGGEDVALUELIST>
        <TAGGEDVALUE profile=”...” tagDefinitionSet=”...” tagDefinition=”...”> </TAGGEDVALUE>
        ....
    </TAGGEDVALUELIST>
    <CONTAINERMODELLIST>
        <CONTAINERMODEL type="...." stereotype="...."/>
        ....
    </CONTAINERMODELLIST>
</MODELPROTOTYPE>

NAME element: This is the name of the model prototype. This must be unique within the profile.
DISPLAYNAME element: Contains the display name used in the user interface like the [Add Model] menu.
ICON element: This element contains the name of the icon file for the model prototype using in the user interface like the [Add Model] menu. The icon file of the model prototype must be .BMP formatted image file 16 X 16 sized. The icon file must be placed in the directory of profile document. It must be specified only the file name except directory path in this element.
BASEMODEL element: Specifies the name of UML standard element based to create copy of model prototype. This element can not be omitted. If this element is not specified, the element prototype can't be recognized.
Available names of UML standard elements are the same of what is enumerated in the BASEELEMENT part of the ElementPrototype section. Elements that own only view can't be used.
argument property: For some kind of elements which base model element is one of Association, Pseudostate, and so on, it needs an argument to create. Specific property values of these model elements are preset as argument of them. Default value of this property is 0. In most of case, it doesn't need to specify.
Available argument values are the same of what is enumerated in the argument part of the ElementPrototype section.
STEREOTYPENAME element: Specifies the Stereotype name of the model prototype. If specifies the value of this element, it is inputted as value of "Stereotype" property when create the model element. This element may be omitted.
PROPERTYLIST element: Contains list of PROPERTY elements.
PROPERTY element: Specifies the value of model property in creating model element. The name property that defines name of model property must be specified certainly. If value of name is not property name of base model or is invalid, the model element would not be created properly.
See "Chapter 4. Using Open API" for available property names and range of the each property value.
TAGGEDVALUELIST element: Contains list of TAGGEDVALUE elements.
TAGGEDVALUE element: Specifies the tagged value of model element in creating element. To assign tagged value, you must specify the tagDefinition defining it.
profile property (TAGGEDVALUE element) : Specifies the profile name that contains the tag definition. This element may be omitted. If omitted, the profile that MODELPROTOTYPE element belongs to is applied.
tagDefinitionSet property (TAGGEDVALUE element): Specifies the tagDefinitionSet name containing the tagDefinition.
tagDefinition property (TAGGEDVALUE element): Specifies the name of the tagDefinition.
CONTAINERMODELLIST element: Contains list of CONTAINERMODEL elements.
CONTAINERMODEL element: Constrains the parent model element that can own model element defined by the model prototype. If the value specified, creation submenu of [Add Model] menu will be activated just only when model element specified in this element is selected.

Palette

PALETTE element describes additional palette and it's items.

<PALETTE>
    <NAME>....</NAME>
    <DISPLAYNAME>....</DISPLAYNAME>
    <PALETTEITEMLIST>
        <PALETTEITEM>....</PALETTEITEM>
        ....
    </PALETTEITEMLIST>
</PALETTE>

NAME element: This is the name of the palette. This must be unique within the profile.
DISPLAYNAME element: This is the name being displayed.
PALETTEITEMLIST element: Lists palette items contained in the palette.
PALETTEITEM element: Specifies an element name for palette item. The value of this element must be the name of element prototype defined in the profile or the name of UML standard element. Available names of UML standard elements are the same of what is enumerated in the BASEELEMENT part of the ElementPrototype section.

DiagramType

DIAGRAMTYPE element describes overall information of diagram type.

<DIAGRAMTYPELIST>
    <DIAGRAMTYPE>
        <NAME>....</NAME>
        <DISPLAYNAME>....</DISPLAYNAME>
        <BASEDIAGRAM>....</BASEDIAGRAM>
        <ICON>....</ICON>
        <AVAILABLEPALETTELIST>
            <AVAILABLEPALETTE>....</AVAILABLEPALETTE>
            ....
        </AVAILABLEPALETTELIST>
    </DIAGRAMTYPE>
</DIAGRAMTYPELIST>

NAME element: This is the name of the palette. This must be unique within the profile.
DISPLAYNAME element: This is the display name used in the user interface like the [Add Diagram] menu.
ICON element: This element contains the name of the icon file for the diagram type using in the user interface like the [Add Diagram] menu. The icon file of the diagram type must be .BMP formatted image file 16 X 16 sized. The icon file must be placed in the directory of profile document. It must be specified only the file name except directory path in this element.

BASEDIAGRAM element: Specifies the name of UML standard diagram based to create a diagram of the diagram type. The names of available UML standard diagrams are as following.
　

Diagram names
ClassDiagram UseCaseDiagram SequenceDiagram SequenceRoleDiagram CollaborationDiagram CollaborationRoleDiagram StatechartDiagram ActivityDiagram ComponentDiagram DeploymentDiagram CompositeStructureDiagram

AVAILABLEPALETTELIST element: Specifies the list of activating palettes when a diagram of the diagram type is created.

AVAILABLEPATTE element: Specifies activating palette when a diagram of the diagram type is created. The value of this element must be the name of palette defined in the profile or built-in palette name included in StarUML basically.
Built-in palettes of StarUMLare as following.
　

Built-in palette names
UseCase Class SequenceRole Sequence CollaborationRole Collaboration Statechart Activity Component Deployment CompositeStructure Annotation

Registering UML Profile

To make a profile to be recognized automatically by StarUML, must place it in the subdirectory of StarUML module directory(<install-dir>\modules). StarUML searches and reads all profiles in the module directory and registers them at the program automatically when StarUML is initializing. If profile file is invalid or it's extension file name is not .prf, StarUML will not read the profile and ignore it. It is recommended that make a subdirectory in the StarUML module directory and place the profile in there to avoid modules being out of order.

Note: To register profile icon, Make icon file for the profile and place it in the directory of the profile. Icon of the profile is displayed with the name at profiles list in the [Profiles] dialog. If there is no icon file which name is same of the profile's, default icon is registered as icon of the profile.

Note: Delete files of the profile from the StarUML module directory(<install-dir>\modules) not to use the profile any more.

Extension Element Object Management

Description of Extension Elements

The extension elements defined in the profile can be accessed through StarUML™'s external API. The COM interface related to extension in StarUML™ is organized in the same way as the actual UML extension structure, and is managed through IExtensionManager. It is rare for the developer to directly manage extension element objects. On the contrary, it is much more usual for the developer to obtain stereotypes or tagged values from the actual model elements extended. In this case, the methods provided by the IExtensionModel can be used. For details on the IExtensibleModel interface and modeling elements, see "Chapter 4. Using Open API".

As mentioned earlier, extension elements are not created during the actual modeling process but are definitions of extension structures. Since they should not be modified during the initial loading of a program or a project, most of the properties defined in these interfaces are read-only.

The following interfaces are available for managing extension element objects.

IExtensionManager: Manages profiles registered in a program, and provides a method for searching extension elements. IExtensionManager is the first interface that accesses the profile or the extension elements defined in the profile.
IProfile: Manages the extension elements defined in the profile, and provides methods for accessing and searching them. It also contains information for the profile. IProfile maintains the extension elements defined in the profile as collections of IStereotype, ITagDefinition, and IDataType.
IStereotype: Provides information for stereotypes.
ITagDefinitionSet: Provides information for TagDefinitionSets, and manages tag definitions defined in TagDefinitionSets as a collection of ITagDefintion.
ITagDefintion: Provides information for TagDefinition.
IDataType: Provides information for DataType.

The diagram below illustrates the organization of the COM interface for StarUML's extension elements.

Accessing IExtensionManager

In order to manage profiles and extension elements, reference to the IExtensionManager interface must be acquired first. IStarUMLApplication provides properties for accessing the ExtensionManager object. The following code is a Jscript example of obtaining reference to IExtensionManager.

var app = new ActiveXObject("StarUML.StarUMLApplication");
var ext = app.ExtensionManager;

Including/Excluding Profile

IExtensionManager provides methods for including or excluding profiles in/from projects. IncludeProfile() includes the profile entered in the current project, and ExcludeProfile() excludes the profile entered from the current project. The profile entered as the parameter for the methods must be registered in the system. An error occurs if the profile entered is not present or registered in the system. The method usage is as follows.

IExtensionManager.IncludeProfile(Profile: String)
IEXtensionManager.ExcludeProfile(Profile: String)

The following is a JScript example of excluding a profile named "StandardProfile" from the current project.

var app = new ActiveXObject("StarUML.StarUMLApplication");
var ext = app.ExtensionManager;
ext.ExcludeProfile("UMLStandard");

Acquiring Extension Elements Defined in Profile

The extension objects that constitute a profile can be accessed through the IProfile interface. IProfile provides the following collection access methods for accessing the interfaces of extension objects (IStereotype, ITagDefinitionSet, and IDataType). The Index argument used in GetStereotypeAt(), GetTagDefinitionSetAt(), GetDataType(), etc. must be equal to or less than Count - 1 of the collection.

IProfile.GetStereotypeCount(): Integer
IProfile.GetStereotypeAt(Index: Integer): IStereotype
IProfile.GetTagDefinitionSetCount(): Integer
IProfile.GetTagDefinitionSetAt(Index: Integer): ITagDefinitionSet
IProfile.GetDataTypeCount(): Integer
IProfile.GetDataTypeAt(Index: Integer): IDataType

The following is a Jscript example of looping the sterotypes defined in the profile.

var app = new ActiveXObject("StarUML.StarUMLApplication");
var ext = app.ExtensionManager;
var prf = ext.FindIncludedProfile("UMLStandard");
if (prf != null) {
    var st;
    for (i = 0; i <= prf.GetStereotypeCount() - 1; i++) {
        st = prf.GetStereotypeAt(i);
        // do something...
    }
}

Finding Extension Elements

The IProfile interface provides methods for searching interfaces of extension elements defined in the profile.

FindTagDefinition(TagDefinitionSet: String, Name: String): ITagDefinition
FindTagDefinitionSet(Name: String): ITagDefinitionSet
FindStereotype(Name: String, BaseClass: String): IStereotype
FindDataType(Name: String): IDataType

Managing Stereotype

The IStereotype interface provides information for stereotypes defined in the profile. Basic stereotype information such as the name, description, and icon file can be obtained through the read-only property of the IStereotype interface. IStereotype includes definitions of methods for recognizing the UML elements that can be applied with stereotypes: GetBaseClassCount(), GetBaseClassAt(), CanApplyTo(), etc. The GetBaseClassCount() and GetBaseClassAt() methods allow names of the UML elements that can be applied with stereotypes to be obtained. The CanApplyTo() method indicates whether the UML element received as an argument can be applied with the current stereotype by returning a Boolean value The BaseClass of a stereotype can specify not only the UML elements expressible in diagrams, but also more of the upper-level elements like UMLClassifier. In this case, the selected stereotype can be applied to all the lower-level elements under the upper-level elements. For example, suppose UMLClassifier is defined as the BaseClass, then it works the same as if all lower-level elements like UMLClass, UMLInterface, UMLUseCase, and UMLActor are defined as the BaseClass. For the inheritance structure between elements, see Plastic Application Model.

GetStereotype() of IExtensibleModel returns IStereotype objects from stereotyped models. If the stereotype of a model is not defined in the profile, a null value is returned. In this case, the StereotypeName property of IExtensibleModel can be used to obtain the name of the stereotype.

The following is a JScript example of displaying in the message box the descriptions of the stereotypes for the currently selected model.

var app = new ActiveXObject("StarUML.StarUMLApplication");
var selMgr = app.SelectionManager;

if (selMgr.GetSelectedModelCount() > 0) {
    var selModel = selMgr.GetSelectedModelAt(0);
    var st = selModel.GetStereotype();
    if (st != null) {
        WScript.Echo(st.Description)
    }
}

Managing TagDefinition

The ITagDefinition interface provides information for tag definitions defined in the profile. ITagDefinition provides the following properties.

Property	Description
Name: String	Name of the tag definition. Tag definition name must be unique within the TagDefinitionSet.
TagType: tagTagTypeKind	Type of tag. The following tag types are available. tkInteger = 0 (integer) tkBoolean = 1 (boolean) tkString = 2 (string) tkReal = 3 (real number) tkEnumeration = 4 (enumeration) tkReference = 5 (reference) tkCollection = 6 (collection) Different methods are used for obtaining tagged values from models depending on the tag type. IExtensibleModel includes definitions of methods for obtaining tagged values according to each tag type.
ReferenceType: String	Indicates the types of object reference available for definition by tagged values when the TagType is tkReference or tkCollection. For example, setting this to "UMLClass" allows connection of Class type only. If the definition for ReferenceType is omitted in the profile document, "UMLModelElement" is taken as the default value. If TagType is not tkReferece or tkCollection, this property has no effect.
DefaultValue: String	Defines the default value of a tag. If the TagType is tkEnumeration, it is a string value for the enumeration order. If the TagType is tkReference or tkCollection, the default value is set as null and this property has no effect.

The following is a JScript example of displaying the default value of a tag in the message box.

var app = new ActiveXObject("StarUML.StarUMLApplication");
var ext = app.ExtensionManager;
var tag = ext.FindTagDefinition("UMLStandard", "Default", "Derived");
WScript.Echo(tag.DefaultValue);