User documentation of the SOFA 2 UML

Lukas Hermann

July 30, 2011

Contents

1 Introduction 3

2 Installation 42.1 Installing the SOFA 2 component system . . . . . . . . . . . . 42.2 Installing SOFA 2 IDE . . . . . . . . . . . . . . . . . . . . . . 52.3 Installing a UML model editor . . . . . . . . . . . . . . . . . . 62.4 Installing SOFA 2 UML . . . . . . . . . . . . . . . . . . . . . 6

3 Getting started 83.1 Creating a UML component model . . . . . . . . . . . . . . . 8

3.1.1 Creating an empty Topcased project . . . . . . . . . . 83.1.2 Creating an empty Topcased UML model . . . . . . . . 93.1.3 Creating top-level components . . . . . . . . . . . . . . 103.1.4 Specifying a subcomponent architecture . . . . . . . . 13

3.2 Generating a SOFA 2 project . . . . . . . . . . . . . . . . . . 163.2.1 Creating a SOFA 2 project with a mapping . . . . . . . 163.2.2 Generating SOFA 2 entities . . . . . . . . . . . . . . . 17

3.3 Deploying and running a SOFA 2 application . . . . . . . . . . 193.3.1 Adding code . . . . . . . . . . . . . . . . . . . . . . . . 193.3.2 Deploy an application . . . . . . . . . . . . . . . . . . 193.3.3 Run an application . . . . . . . . . . . . . . . . . . . . 20

4 UML component model definition 214.1 Model structure . . . . . . . . . . . . . . . . . . . . . . . . . . 214.2 Model constraints . . . . . . . . . . . . . . . . . . . . . . . . . 224.3 Model transformation . . . . . . . . . . . . . . . . . . . . . . . 234.4 Generation of SOFA 2 entities . . . . . . . . . . . . . . . . . . 24

5 Mapping form editor description 265.1 Overview page . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2 Interfaces page . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1

5.3 Components page . . . . . . . . . . . . . . . . . . . . . . . . . 295.4 Assemblies page . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6 Common issues 33

2

Chapter 1

Introduction

SOFA 2 UML is a compound of Eclipse plug-ins which extends SOFA 2 IDEwith an ability of generation SOFA 2 entities [1] from the UML componentmodel [3]. It introduces a mapping model, that connects a source UML modelwith a SOFA 2 project, and its editor where a mapping between UML andSOFA 2 entities can be easily specified.

3

Chapter 2

Installation

SOFA 2 UML feature has several prerequisites to run properly. First, theSOFA 2 component system must be installed to the operating system alongwith the Java SE 6 JDK. Then, the Eclipse Modeling Tools (Helios version)must be installed along with the SOFA 2 IDE feature. Finally, some editorfor UML models, such as Topcased UML2 editor [2], must be installed to theEclipse. In this chapter, the installation of these prerequisites is describedas well as the installation of the SOFA 2 UML feature itself.

2.1 Installing the SOFA 2 component systemFirst, we install the Java SE 6 JDK which is necessary to run the SOFA 2component system:

1. Download the latest version of the Java SE 6 JDK for your oper-ating system from the http://www.oracle.com/technetwork/java/javase/downloads/index.html website or from the Prerequisites fol-der on the CD (Windows x86 platform only, Update 26).

2. Run the installation file and follow the installation instructions.

Then, we install the SOFA 2 component system itself:

1. Download the SOFA 2 component system and the Cushion tool fromhttp://sofa.ow2.org/download.html website or from the Prerequi-sites folder on the CD (version 0.8.0).

2. Unpack both downloaded archives to some folder on harddisk (e.g.C:\Sofa2). Do not merge contents of directories in archives.

4

3. Set the environment variable SOFA_HOME to the directory with theunpacked SOFA 2 archive (e.g. C:\Sofa2\sofa) and set the environ-ment variable CUSHION_HOME to the directory with the unpackedCushion archive (e.g. C:\Sofa2\cushion).

4. Each time you want to use this tool, the SOFA 2 system must berunning. To achieve this, run the sofa-node.bat (for Windows) orsofa-node.sh (for UNIX) file in the bin subdirectory of the unpackedSOFA 2 archive (e.g. C:\Sofa2\sofa\bin\sofa-node.bat).

2.2 Installing SOFA 2 IDEFirst, we install the Eclipse Modeling Tools:

1. Download Eclipse Modeling Tools (Helios version, 3.6.x) for your oper-ating system from the http://www.eclipse.org/downloads/packages/eclipse-modeling-tools-includes-incubating-components/heliossr2website or from the Prerequisites folder on the CD (Windows 32-bitplatform only).

2. Unpack the archive to some folder on harddisk.

Then, we install the SOFA 2 IDE feature:

1. Run the installed Eclipse.

2. Choose Help → Install New Software. . . from the main menu.

3. Type http://sofa.ow2.org/update-site in the Work with fieldand press Enter.

4. Check the SOFA 2 IDE item in the list and click on the Next button.

5. Click again on the Next button, read the license, choose the I acceptthe terms of the license agreement option and click on the Finishbutton.

6. Once the installation is complete, click on the Restart Now button.

5

2.3 Installing a UML model editorFor creating of UML models, the Topcased UML2 editor [2] is used in thisdocument. To install it, follow these instructions:

1. Run the installed Eclipse.

2. Choose Help → Install New Software. . . from the main menu.

3. Click on the Available Software Sites link and then click on theImport. . . button.

4. Type http://gforge.enseeiht.fr/scm/viewvc.php/*checkout*/releng/org.topcased.releng/topcasedBookmarks.xml?root=topcased-mm,or select the topcasedBookmarks.xml file from the Prerequisites folderon the CD and click Ok twice.

5. Select the Topcased 4.3.0 item in the Work with list.

6. Expand the TOPCASED Toolkit Features item in the list, check theTopcased UML2 Editors subitem and click on the Next button.

7. Click again on the Next button, read the license, choose the I acceptthe terms of the license agreement and click on the Finish button.

8. Once the installation is complete, click on the Restart Now button.

Alternatively, open the http://www.topcased.org website and followtheir installation guide for the version 4.3.0.

2.4 Installing SOFA 2 UMLWhen all prerequisites are installed, we can install the SOFA 2 UML featureto the Eclipse platform. We have two possibilities. The first one is to installthis feature from SOFA 2 update site, which is the same procedure as in-stalling SOFA 2 IDE, it differs only in checking the SOFA UML item insteadof the SOFA 2 IDE one. The second one is to install it from CD:

1. Run the installed Eclipse.

2. Choose Help → Install New Software. . . from the main menu.

3. Click on the Add. . . button, then click on the Local. . . button.

6

4. Select the Tool/org.objectweb.dsrg.sofa.uml.site folder on the CD andclick Ok.

5. Check the SOFA 2 item in the list and click on the Next button.

6. Click again on the Next button, read the license, choose the I acceptthe terms of the license agreement and click on the Finish button.

7. Once the installation is complete, click on the Restart Now button.

7

Chapter 3

Getting started

This tutorial provides step-by-step creation of a SOFA 2 application from aUML component model.

3.1 Creating a UML component modelFirst, it is necessary to create a UML component model in some of yourfavorite editors. This model must keep a specification widely described inchapter 4. In this section, we will create a sample UML component model inthe Topcased UML2 editor [2], so it is necessary to install this plug-in beforecontinuation in this tutorial.

The sample UML model will represent a library with a store and a userregistry which is connected to user and administrator terminals. From theuser terminal, it will be possible to get information about stored books andto borrow some if the user is registered. From the administrator terminal,it will be possible to change information about stored books and to registernew users or unregister the old ones.

3.1.1 Creating an empty Topcased project1. Run the Eclipse Platform with the Topcased Modeling, SOFA 2 UML

and SOFA 2 IDE plug-ins activated.

2. Open the Topcased Modeling perspective.

3. Select the menu item File → New → Project... to open the NewProject wizard.

4. Select the Topcased Project subitem and then click Next. On this pagetype LibraryModel in the Project name field and click Finish.

8

3.1.2 Creating an empty Topcased UML model1. Open the Topcased Navigator view.

2. Right click on the Models folder in the LibraryModel project and selectNew → UML Model with TOPCASED.

3. Type Library in the Model name field and select the ComponentDiagram option in the Diagram field as in figure 3.1.

4. Click on the Finish button.

Figure 3.1: Creating a new UML model with Topcased

9

The Library.uml and Library.umldi files were created in the Models folder.The second one was opened with the UML editor (see figure 3.2). In the UMLfile there is the model LibraryModel that contains the package LibraryPack-age that contains the component LibraryComponent which represents theopened diagram (see figure 3.3).

Figure 3.2: An empty UML component model diagram

3.1.3 Creating top-level componentsWe build the model from the top-level components. First, we create a com-ponent that represents the whole application and will serve as a SOFA 2Assembly. Its subcomponents will be the library system and the user andadministrator terminals.

Creating the assembly component

1. Click on the Component item in the Objects folder in the UMLeditor.

2. Click somewhere in the component diagram and type LibraryAssembly.

3. Click on the Advanced menu item in the Properties view.

10

Figure 3.3: An empty UML component model structure

4. Set the Is Active property to true (see figure 3.4). This option willcause generation of a SOFA 2 assembly from this component.

5. Enlarge the component in the diagram so it can contain subcompo-nents.

Figure 3.4: Setting the Is Active property of a component, which will causegeneration of an assembly

Creating subcomponents

1. Click on the Component item in the Objects folder in the UMLeditor.

11

2. Click somewhere inside the LibraryAssembly component and type Li-brarySystem.

3. Repeat these two steps with typing UserTerminal and AdminTerminal.

Creating interfaces

1. Click on the Interface item in the Objects folder in the UML editor.

2. Click somewhere between the UserTerminal and LibrarySystem com-ponents and type GetInfo.

3. Repeat these two steps with typing Borrow.

4. Click on the Interface item in the Objects folder in the UML editor.

5. Click somewhere between the AdminTerminal and LibrarySystem com-ponents and type SetInfo.

6. Repeat these two steps with typing ManageUsers.

Creating connections

1. Click on the Interface Realization item in the Connections folderin the UML editor.

2. Click on the LibrarySystem component and then click on the GetInfointerface.

3. Click on the created edge, click on the Model menu item in the Prop-erties view.

4. Type getinfo into the Name field. This means that the LibrarySys-tem component provides the getinfo interface which is of the GetInfointerface type.

5. Repeat these four steps with the Borrow interface (type borrow), theSetInfo interface (type setinfo) and the ManageUsers interface (typemanageusers). Now a SOFA 2 Frame of the LibrarySystem componentis defined.

6. Click on theUsage item in theConnections folder in the UML editor.

7. Click on the UserTerminal component and then click on the GetInfointerface.

12

8. Click on the created edge, click on the Model menu item in the Prop-erties view.

9. Type getinfo into the Name field. This means that the UserTermi-nal component requires the getinfo interface which is of the GetInfointerface type.

10. Repeat these four steps with the Borrow interface (type borrow). Dothe same for the AdminTerminal component with the SetInfo inter-face (type setinfo) and the ManageUsers interface (type manageusers).Now SOFA 2 Frames of the UserTerminal and the AdminTerminalcomponents are defined.

After all steps in this subsection a SOFA 2 Architecture of the Library-Assembly component is defined (see figure 3.5). All of its subcomponentshave primitive architectures now. But the LibrarySystem component can becomposed by additional components.

Figure 3.5: The UML component diagram representing the LibraryAssemblycomponent.

3.1.4 Specifying a subcomponent architectureThe LibrarySystem component should contain Store and UserRegistry sub-components which will really realize all provided interfaces. There are threeoptions how an architecture of an internal component can be defined:

13

1. Subcomponents are added to the same diagram into the LibrarySystemcomponent as in the previous subsection. This is the easiest way butthe diagram will become less transparent.

2. Another top-level diagram is created in the same package (right click onthe package in Outline view, then choose Add diagram → Compo-nent Diagram, create a new component with the same name and ex-ternal connections to interfaces and define its architecture as describedbelow).

3. Another diagram is created inside this component.

We choose the third option and there is a step-by-step description:

1. Double-click on the LibrarySystem component in the UML diagram.

2. Select the Component diagram option and click Ok.

3. Create Store and UserRegistry components within this diagram.

4. Create GetInfo and SetInfo interfaces near the Store component andconnect them by interface realizations with it (name them getinfo andsetinfo).

5. Create Borrow and ManageUsers interfaces near the UserRegistry com-ponent and connect them by interface realizations with it (name themborrowexternal and manageusers.

6. Create a Borrow interface between the Store and UserRegistry com-ponents and connect it by a usage with the UserRegistry component(name it borrowinternal) and by an interface realization with the Storecomponent (name it borrow).

To define, to which subcomponent is calling of some method of a par-ticular LibrarySystem interface delegated, we must connect those four un-connected interfaces by usages with the parent component. They cannot beconnected directly but via Port objects created within the parent compo-nent:

1. Click on the Port item in the Objects folder in the UML editor.

2. Click on a margin of the component diagram near the GetInfo interfaceand click on the created port.

14

3. Click on the . . . button next to the Type property in the Propertiesview.

4. Select the <Component> LibrarySystem item from the list and clickOk.

5. Connect the created port and the GetInfo interface by a usage (nameit getinfo). It is important that the name of the usage is the samethat the name of the interface realization between the LibrarySystemcomponent and the GetInfo interface in the first diagram.

6. Repeat these five steps with the SetInfo interface (name it setinfo), theunconnected Borrow interface (name it borrow) and the ManageUsersinterface (name it manageusers).

Now an architecture of the LibrarySystem component is defined (see figure3.6). Other components in the model will have a primitive architecture sothe UML model is now complete. Save the UML model by selecting the File→ Save All item from the main menu.

Figure 3.6: The UML component diagram representing an architecture ofthe LibrarySystem component

15

3.2 Generating a SOFA 2 projectWhen the UML component model is ready, it is possible to generate a SOFA 2project from it with SOFA 2 entities corresponding to the model. This pro-cess is divided into two phases. First, we generate a mapping model whichholds a list of all unique interfaces, components and assemblies contained inthe UML model. It maps each interface to a SOFA 2 Interface type, eachcomponent to a SOFA 2 Frame and SOFA 2 Architecture and each assemblyto a SOFA 2 Assembly. In the second phase, it is possible to define a map-ping to some existing SOFA 2 entities (i.e. downloaded from the repository)or to generate new ones according to the UML model.

3.2.1 Creating a SOFA 2 project with a mappingIt is possible to create a new SOFA 2 project with a mapping or to bind amapping to an existing SOFA 2 project. We described the first option, thesecond one is similar.

Important: Your SOFA 2 component system must run during the furthersteps! If you have your SOFA 2 distribution properly installed, just runsofa-node file in the bin subdirectory of the directory with unpacked SOFA 2archive.

1. Open the SOFA 2 perspective.

2. Right click on the Library.uml file in the Models folder in the Library-Model project in SOFA 2 Navigator view.

3. Select the SOFA 2 UML → Create a new SOFA 2 Project fromthis UML model menu item.

4. Type LibrarySofa in the Project Name field and click Next.

5. Select the http://localhost:8173/SofaServlet option in the Hostfield and click Finish.

Wait a moment until the UML model is processed. When it is done, theLibrary.mapping file from the created project will be opened in the mappingform editor on the Overview page (see figure 3.7). If some errors occur inthe UML model, a message will be written to the SOFA Console View andcorresponding markers will be created on the UML model file. In this case,repair the UML model and click on the Refresh button in the Overviewpage.

16

Figure 3.7: The Overview page of the mapping form editor

3.2.2 Generating SOFA 2 entitiesThere are three ways how to generate SOFA 2 entities from a UML modelto a SOFA 2 project:

1. Fully automatic: It generates all necessary entities with default names.For example for the component UserTerminal in the package Library-Package, it generates a SOFA 2 Frame LibraryPackage.FUserTerminaland a SOFA 2 Architecture LibraryPackage.AUserTerminal.

2. Semi automatic: You can specify your own unique name for each entity.Since all entities, that the currently generated entity is depended on,are automatically generated with default names, start with interfaces,continue with components (from the primitive to the top-level ones)and finish with assemblies.

3. Manual: Create your own SOFA 2 entities by the SOFA 2 IDE ordownload them from the repository and bind them to the UML entities.

For this tutorial, we choose the easiest fully automatic way. Just clickon the Generate button in the Overview page. Wait a moment until all

17

entities are generated, then check the LibrarySofa project in the SOFA 2Navigator view for new entities (see figure 3.8). Now you can edit theiradl.xml files for specifying details that the model does not contain (i.e. com-munication style of frame interfaces) and add code for interfaces and primitivearchitectures.

Figure 3.8: The SOFA 2 Navigator with the opened SOFA 2 Project

If you then add or change something in the UML model, just click to theRefresh button and then to the Generate button in the Overview page.New entities will be generated and the old ones will be repaired accordingto changes in the UML model. In this process, the application tries to keeputmost details that you filled manually.

For other ways for generating SOFA 2 entities, see chapter 5 where themapping form editor is fully described.

18

3.3 Deploying and running a SOFA 2 appli-cation

This section does not contain any new information about the SOFA 2 UMLtool, it only describes how to deploy and run the tutorial application with theCushion tool. For further steps, the Cushion tool must be properly installedand %CUSHION_HOME%\bin and %SOFA_HOME%\bin entries must be added tothe PATH environment variable.

3.3.1 Adding codeFirst, code for interfaces and primitive architectures must be added, compiledand uploaded:

1. Copy all LibraryPackage subdirectories from SOFA 2 entity directoriesin the Examples/LibrarySofa folder on the CD to corresponding direc-tories in your created SOFA 2 project. These directories contain a Javaclass or interface implementing a primitive SOFA 2 Architecture or aSOFA 2 Interface type.

2. Open the command line of your operating system and get to the direc-tory of your created SOFA 2 project.

3. Type cushion commit. This command commits all SOFA 2 entities tothe repository. Several messages about successful commitment shouldappear.

4. Type cushion compile. This command compiles code of all entities.Several messages about successful compilation should appear.

5. Type cushion upload. This command uploads code of all entities tothe repository.

3.3.2 Deploy an applicationThen, a deployment plan for the application must be created and the appli-cation must be deployed:

1. Type cushion deplplan initial LibraryPackage.ThreeNodesLibraryPackage.LibraryAssembly. This command creates a new de-ployment plan from the LibraryPackage.LibraryAssembly assemblyboth in the workspace and the repository.

19

2. Open the adl.xml file in the LibraryPackage.ThreeNodes directory inthe text editor.

3. Type nodeA to first four node fields, type nodeB to the fifth one andtype nodeC to the last one. Save the file and return to the commandline.

4. Type cushion deploy LibraryPackage.ThreeNodes. This commanddeploys the application according to the deployment plan. Severalpages of information should appear. If not, your Cushion is not prop-erly installed, see chapter 6.

5. Type cushion tag current LibraryPackage.ThreeNodes. This com-mand tags the current deployed application, so it can be easily launched.A message about successful tagging should appear.

3.3.3 Run an applicationFinally, the application can be launched according to the deployment plan:

1. Run sofa-dock nodeA, sofa-dock nodeB and sofa-dock nodeC inthree new command lines. This commands will create three nodeswhere the application will run.

2. Type sofa-launch LibraryPackage.ThreeNodes current. This com-mand launches the application. Wait until windows with administratorand user terminals appear.

3. Try to create an user and some books in the administrator terminaland try to borrow some in the user terminal. See a log in the commandline with nodeA.

4. Type sofa-shut nodeA@1. This command shuts down the application.

20

Chapter 4

UML component modeldefinition

In this chapter, we define a valid input UML component model for generationSOFA 2 entities. First, we list elements which the model should be consist ofand their possible location in the model hierarchy. Then, we introduce someconstraints which these elements must fulfill. Finally, we describe a processof a transformation to the mapping model and generation of SOFA 2 entities.

4.1 Model structureAll elements in a valid model file must be from the org.eclipse.uml2 name-space from the Unified Modeling Language 2.x OMG meta-model forthe Eclipse platform [3].

The top-level element must be an instance of the Model class. It canown any amount of diagrams represented by the Component class directlyor indirectly through instances of the Package class. The top-level diagrammust own exactly one ordinary component (the Component class) and anyamount of interfaces (the Interface class), interface realizations (the Inter-faceRealization class) and usages (the Usage class). Ordinary component canown the same as the top-level diagram and in addition any amount of sub-components (the Component class). Every element can also own instancesof other subclasses of the Element class (i.e. ports, notes, comments. . . ) butthey are ignored by the application. In figure 4.1, there is a class diagram ofa valid input UML component model.

21

Figure 4.1: The structure of a valid input UML component model (the UMLmeta-model)

4.2 Model constraintsIn addition to the described structure, a valid model must satisfy some con-strains resulting from its future transformation to the mapping model andgeneration of SOFA 2 entities. There is a list of them:

Note: Each element in the model is uniquely identified with its full namewhich is defined as element’s name prefixed by the full name of its nearestpackage plus .(dot). The model has an empty name so for example the fullname of the component named Component in the sub-package Subpackagein the package Package is Package.Subpackage.Component. Elements withthe same full name are considered same for the further transformation.

• Each interface realization and usage must be connected to exactly onecomponent (the client property) and one interface (the supplier prop-erty).

• Each interface must be connected by at most one interface realizationand/or some usages. This means that many components can call themethod of the interface but only one can handle it.

• Each component does not own itself directly or indirectly and it is

22

unique within its owner component. On the other hand, an instance ofthe same component can be in other places in the model.

• For each usage (except from that owned directly by a top-level diagramcomponent) exists an interface realization on the supplier interface.This means that every interface inside some component that has ausage connection must also have an interface realization connection, soevery call is properly handled.

• Each usage/interface realization is either frame usage/interface realiza-tion, or delegation usage/interface realization of its client component.This means that its supplier interface is a neighbor of the client com-ponent, or it is directly owned by it. Therefore it is not possible tohave a connection from an outside interface directly to an inner sub-component, you must use a delegation instead.

• Two components with the same full name must have the same frameusages and interface realizations (same full names and same full namesof supplier interfaces). This means that every instance of a componentin the model must have same outer connections.

• Each component must not have any subcomponents, or must haveproperly connected each frame usage/interface realization with a cor-responding (same names and same supplier interfaces) delegation in-terface realization/usage. This means that component’s architecturemust be either primitive, or fully compatible with component’s frame.

• Each component marked as an assembly (the isActive property is true)must not have any frame usages or interface realizations. This meansthat an assembly is a top-level component that does not communicateoutside.

• All instances of the same component must be either ordinary compo-nents, or assemblies.

4.3 Model transformationA valid UML component model can be transformed to a mapping modelwhich represents a connection between a UML model and a SOFA 2 project.The mapping model contains a list of unique interfaces, components and as-semblies found in the UML model (see figure 4.2). For each unique interfaceit stores a mapping to a SOFA 2 Interface type, for each unique component

23

and assembly it stores a mapping to a SOFA 2 Frame and a SOFA 2 Archi-tecture, and for each unique assembly it stores in addition a mapping to aSOFA 2 Assembly.

Figure 4.2: The meta-model of the mapping model

After the first transformation of a UML model, all mappings are empty.In the next transformations, the previously set mappings in still existingelements are preserved, new elements are added with an empty mapping andno longer existing elements are deleted.

4.4 Generation of SOFA 2 entitiesWhen a mapping model is created, we can assign existing SOFA 2 entitiesto its elements or generate new ones according to its source UML model.

SOFA 2 Interface type: The generator just creates a SOFA 2 Interfacetype of a specified name and the identical signature.

SOFA 2 Frame: The generator creates a SOFA 2 Frame of a specifiedname. Its provided interface list is filled by a name and a supplier of all in-terface realizations that are connected to the source component from outside.The same is done for its required interface list and similar usages.

24

SOFA 2 Architecture: The generator creates a SOFA 2 Architecture ofa specified name. Its frame is set according to the mapping model, or gen-erated if the mapping is empty. If all instances of the source componentin the UML model do not have any subcomponents, its implementation isset to the specified name. Otherwise, its subcomponent list is filled by alldirectly owned subcomponents of the source component. Their frames andarchitectures should be already defined, otherwise they are generated recur-sively. In addition, its connection list is filled by all connections between twoof its subcomponents and between some of its subcomponent and the sourcecomponent itself.

SOFA 2 Assembly: The generator creates a SOFA 2 Assembly of a spec-ified name. Its top-level architecture is set according to the mapping model,or it is generated if the mapping is empty. Its collection of assembly sub-components is recursively filled by both direct and indirect subcomponentsof its top-level architecture.

25

Chapter 5

Mapping form editordescription

For easy editing of a mapping model that connects a UML model and aSOFA 2 project, the mapping form editor was developed. In this chapter, wedescribe each page the editor contains.

The Overview page offers information about the connected UML modeland the SOFA 2 project. It is also possible to change them here and tosynchronize the mapping with the UML model and to generate or repair allentities in the SOFA 2 project. Next three pages help defining the mappingfor a particular interface, component or assembly to SOFA 2 entities as wellas generating or repairing them individually according to the UML model.In the last page Source, it is possible to view and edit the mapping modeldirectly in the XML editor, but this is not recommended.

5.1 Overview pageThere is only one section in the Overview page, where general informationabout mapping is provided. There are four fields in this section (see figure5.1).

Source filename: This field shows the workspace relative path to the filewith the UML model connected with the current mapping. Click on theBrowse button to change the source model. Then, choose a UML file inthe current workspace and click Ok. The current mapping model will beimmediately refreshed with the selected UML model. In case of an error, amessage dialog will be shown and markers on the selected file will be created.

26

Figure 5.1: The Overview page of the mapping form editor

SOFA 2 project: This field shows a name of the SOFA 2 project whereSOFA 2 entities are searched and generated. Click on the Browse button,then select a new project with a SOFA 2 nature from the list and click Okto change it.

Refresh: Click on this button to apply changes in the source UML modelto the mapping model. In case of an error, a message dialog will be shownand markers on the source UML file will be created.

Generate: Click on this button to generate SOFA 2 entities with defaultnames (see the following sections for their definition) for all interfaces, com-ponents and assemblies in the current mapping model, that do not have themapping set, to the current SOFA 2 project. This action also repairs allSOFA 2 entities, that are set to a mapping entity, according to the UMLmodel.

27

5.2 Interfaces pageThe Interfaces page is divided to two sections (see figure 5.2). On the leftthere is the Source Interfaces section where is a list of all uniquely namedinterfaces from the UML model and a check-box that can fill the list onlywith interfaces with an empty or erroneous mapping.

Definition: Two UML interfaces are considered identical for the mappingmodel, if and only if they have the same owner package and the same name,or the first interface is in a sub-package of the second interface package, thesecond interface has the name of this sub-package plus .(dot) as a prefixin its name and their names without prefix are the same. For example,the interface Subpackage.Interface in the package Package is identical to theinterface Interface in the package Subpackage, if the Subpackage is a directsub-package of the package Package.

Figure 5.2: The Interfaces page of the mapping form editor

Select an interface from the list and its details will be shown on the right.There is the SOFA 2 Interface type name field for viewing and editingthe current interface mapping with the Edit button, the list of AvailableSOFA 2 Interface types and optionally the Generate button.

28

SOFA 2 Interface type name: This field shows a name of the currentSOFA 2 Interface type to which is mapped the selected interface. It is possibleto change it to another available one or to another unique name for latergeneration. If there is a name of the existing one, click on the Edit buttonto open its editor.

Available SOFA 2 Interface types: This list shows all SOFA 2 Interfacetypes in the current SOFA 2 project. Double-click on some of them to set itto the selected interface.

Generate: If the SOFA 2 Interface type name field contains a nameof an interface that does not exist, the Generate button is shown. Click onit to generate a SOFA 2 Interface type of this name to the current SOFA 2project. If an empty name is set, the default name with the I prefix is used(i.e. from LibraryPackage.GetInfo to LibraryPackage.IGetInfo).

5.3 Components pageThe Components page is divided to two sections (see figure 5.3). On theleft there is the Source Components section where is a list of all uniquelynamed components and assemblies (the same definition as for interfaces) fromthe UML model and a check-box that can fill the list only with componentsand assemblies with an empty or erroneous mapping.

Select a component or assembly from the list and its details will be shownon the right. There is the SOFA 2 Frame name field for viewing and edit-ing the current frame mapping with the Edit button, the list of AvailableSOFA 2 Frames, optionally the Generate or the Repair button and allmentioned fields also for the SOFA 2 Architecture.

SOFA 2 Frame/Architecture name: These fields show a name of thecurrent SOFA 2 Frame/Architecture to which is mapped the selected com-ponent or assembly. It is possible to change them to other available ones orto other unique names for later generation. If there are names of the existingones, click on the Edit button to open their editor.

Available SOFA 2 Frames/Architectures: These lists show all SOFA 2Frames/Architectures in the current SOFA 2 project compatible with theselected component or assembly. Double-click on some of them to set it tothe selected component or assembly.

29

Figure 5.3: The Components page of the mapping form editor

Definition: A component or an assembly is compatible with a SOFA 2Frame, if and only if they have the same provided and required interfaces(same names and target interface types). It is compatible with a SOFA 2Architecture, if and only if they have the same subcomponents (same framesand architectures), the same connections (same source subcomponents andtarget interfaces) and the frame of the architecture is also compatible.

Generate or Repair: If the SOFA 2 Frame/Architecture name fieldcontains a name of a/an frame/architecture that does not exist, the Gener-ate button is shown. Click on it to generate a SOFA 2 Frame/Architectureof this name from the current UML model to the current SOFA 2 project. Ifan empty name is set, the default name with the F/A prefix is used (i.e. fromLibraryPackage.Store to LibraryPackage.FStore/LibraryPackage.AStore). Ifa/an frame/architecture of this name exists but it is not compatible to theselected component or assembly, the Repair button is shown. Click on it torepair the SOFA 2 Frame/Architecture of this name from the current UMLmodel. After the generation or repair action, the selected SOFA 2 Frame/Ar-chitecture is compatible with the selected component or assembly.

30

5.4 Assemblies pageThe Assemblies page is divided to two sections (see figure 5.4). On theleft there is the Source Assemblies section where is a list of all uniquelynamed assemblies (the same definition as for interfaces) from the UML modeland a check-box that can fill the list only with assemblies with an empty orerroneous mapping.

Figure 5.4: The Assemblies page of the mapping form editor

Select an assembly from the list and its details will be shown on theright. There is the SOFA 2 Assembly name field for viewing and editingthe current assembly mapping with the Edit button, the list of AvailableSOFA 2 Assemblies and optionally the Generate or the Repair button.

SOFA 2 Assembly name: This field shows a name of the current SOFA 2Assembly to which is mapped the selected assembly. It is possible to changeit to another available one or to another unique name for later generation.If there is a name of the existing one, click on the Edit button to open itseditor.

31

Available SOFA 2 Assemblies: This list shows all SOFA 2 Assemblies inthe current SOFA 2 project compatible with the selected assembly. Double-click on some of them to set it to the selected assembly.

Definition: An assembly is compatible with a SOFA 2 Assembly, if andonly if the top-level architecture of the assembly is also compatible and theircollections of direct and indirect subcomponents are compatible (the samehierarchy, the same architectures).

Generate or Repair: If the SOFA 2 Assembly name field contains aname of an assembly that does not exist, the Generate button is shown.Click on it to generate a SOFA 2 Assembly of this name from the currentUML model to the current SOFA 2 project. If an empty name is set, the de-fault name with no prefix is used (i.e. from LibraryPackage.LibraryAssemblyto LibraryPackage.LibraryAssembly). If an assembly of this name exists butit is not compatible to the selected assembly, the Repair button is shown.Click on it to repair the SOFA 2 Assembly of this name from the currentUML model. After the generation or repair action, the selected SOFA 2Assembly is compatible with the selected assembly.

32

Chapter 6

Common issues

In this chapter, common issues with the SOFA 2 UML are described:

• NullPointerException occurs when exiting the Eclipse workbench. Thisexception raises due to an error in the SOFA 2 IDE tool. It should besolved in the next version of this tool.

• Nothing happens when deploying the tutorial application. You usethe Cushion distribution from the website. Use the distribution fromthe CD, or search for org.objectweb.dsrg-sofa-j-repository in thesofa-launch file and add the whole entry to the CUSHIONCLASSPATHvariable in the cushion file.

33

Bibliography

[1] SOFA 2 component system – http://sofa.ow2.org

[2] Topcased UML2 Editors – http://www.topcased.org

[3] Unified Modeling Language 2.x – http://www.eclipse.org/uml2

34