Page tree
Skip to end of metadata
Go to start of metadata

This page is being migrated from internal GENIVI wiki (https://collab.genivi.org/wiki/display/genivi/UML+Interface+Standardization+Guideline) and might be incomplete still.


Packages

Mapping UML-model to Franca-IDL files

UML packages may use the «fidl» stereotype to indicate that this package shall be mapped to a Franca IDL file with the name of the UML package node.
Any contents of packages below will be added to the same Franca IDL file, using the relative path names of the package nodes to name these contents uniquely.
If there is an UML package B marked with stereotype «fidl» below another UML package A marked with stereotype «fidl», then any contents of B will not be part of the Franca IDL file A, but contained by a new separate Franca IDL file B.

If any subtrees in UML shall not be processed by Franca import/export tools, use stereotype «nofidl» to mark the root of the UML subtree to be ignored.

Note:
Since Franca 0.9.0 it is disallowed to define interfaces with fqn or any additional path components that extend their namespace. It is also not possible to define additional namespaces by several "package" sections.
In consequence it is not possible any longer to realize several namespaces within one Franca IDL file at all. Mapping of UML package subtrees to one Franca IDL must collapse the namespace therefore, round trip transformation will be difficult that way.
TBD whether UML subtrees with interfaces shall be allowed below UML fidl package.

tagged value overrides

In case the UML model structure is not aligned to the required Franca-IDL file or directory structure, tagged values can be used to override the Franca-IDL file name and location.

  1. FIDL-Name overrides the Franca-IDL file name (UML package name is not used anymore)
  2. FIDL-Namespace-Prefix overrides the Franca-IDL package name prefix (UML model package path is not used anymore); file name will be added as end of the package prefix.
Example UML package tagged value overridesFranca IDL file with name de/bmw/Test.fidl
interface version specification "4.2"
package de.bmw.Test

UML namespaces

Franca IDL package name will be generated using the relative UML package node path from some user specified root node (namespace root) to the UML package node marked with stereotype «fidl».
By default the UML root is used for Franca package name generation.
Any UML package may be defined as namespace root to indicate that all Franca IDL files below shall use package names relative to the marked UML package. The UML namespace root itself is included within the Franca IDL package name.
The namespace root can be defined in two different ways:

EA UML namespace root marker (recommended)

Mark some UML package as "namespace root": in EA project browser right click the UML package -> "Code Engineering" -> "Set as Namespace Root".

stereotype «root»

Mark some UML package with stereotype «root».

Example UML root namespace markers
Example UML root namespace markers

 

Franca requires that package names must not contain certain characters. Spaces will be replaced by "_"; other special characters or numbers at the beginning of package names are forbidden and will cause an error during transformation.
The UML usage guidelines / checker shall recommend/enforce exclusion of such special characters and umlauts in UML packages and define as well whether capital letters shall be allowed. Besides the special character treatment the transformation UML <-> Franca just leaves the names as they are.

interpreting package names

The Franca package name is also used to derive a directory name the Franca-IDL file name.
The Franca-IDL file name is the last part of the package name, i.e. the part behind the last dot.
The Franca-IDL file will be placed in a directory hierarchy, where each level´s directory name consists of the package name parts between the dots.

Datatypes

All data types are placed within UML packages by selecting a package in the EA project browser, right click -> Add -> Add Element and configure the type "Class" and one of the stereotypes «typedef», «struct», «struct polymorphic», «array», «FrancaEnum», «enumeration», «union» or «map» in the dialog box.
Type definitions will be mapped to Franca type collections for each UML package. The name of a type collection is derived from the relative path between (excluding) the nearest UML package with stereotype «fidl» and the package where the type definitions are placed (including).

to be removed after introduction of anonymous type collections with Franca 0.8.9 :
It is forbidden to place data types within an UML package marked with stereotype «fidl» directly and will raise an error during transformation.
UML design guidelines and checker shall enforce this interdiction.

Typedef of Basic Datatype

Add the freshly created class to a diagram and right click -> Advanced -> Parent, enter the origin basic type´s name and press the "Add" button.

Defining Structures

Enter the new elements "Properties Details", click "Attributes..." and add any structure fields you wish with their corresponding types. It is not required to place stereotypes to the fields.
The order of declared fields within the struct is retained during any model transformation or code generation process. Because of this reason it is not allowed to use UML constructs which do not explicitly define the order of fields (e.g. when using a number of associations to structure member types).
To create an inline array definition of a structure member, it must be marked with "Attribute is a Collection" in the EA Attribute Detail view.

Defining Unions

Enter the new elements "Properties Details" dialog, click "Attributes..." and add any union fields you wish with their corresponding types. It is not required to place stereotypes to the fields.
To create an inline array definition of a union member, it must be marked with "Attribute is a Collection" in the EA Attribute Detail view.

Defining Enumerations

Enter the new elements "Properties Details" dialog, click "Attributes..." and add any enumeration fields you wish with their corresponding data type.
Since Franca 0.9 string constants are deprecated for enums. To simplify usage of enums in UML, enumeration members may have an empty type field to indicate usage of integers.
All fields have to use the same (or empty) data type!
It is not required to place stereotypes to the fields.
The order of declared members within the enumeration is retained during any model transformation or code generation process.
Optional: if a field shall have a constant value, provide it as "initial value". Numeric initial values may be provided in decimal, octal, binary or hexadecimal notation.

Note:
Franca currently (Franca 0.8.8) supports String and numeric enumeration constants, while most programming languages like C++ do support only numeric enumerations.
It is recommended to NOT to use string constants for enumerations (see Franca issue 52).

Note2:
Enterprise Architect contains some implicit logic for UML::enumeration typed elements. They are considered as type "Enumeration", not type "Class". They cannot be extended as Franca allows. Furthermore, if an element of type Class (which can be extended) is created with stereotype "enumeration" and you copy-paste this object, it is transformed to an element of type Enumeration and loses ability to be extended.
To overcome this annoying behaviour it is proposed to use UML::Class with stereotype «FrancaEnum».

Defining Maps

Enter the new elements "Properties Details", click "Attributes..." and add the map´s key as member, provide its data type and use stereotype «key».
Then add the map´s value as member, provide its data type and use stereotype «value».
It is not allowed to define any other members.

Defining Arrays

There are two different kinds of arrays, anonymous inline arrays and named data types defining an array.

anonymous inline arraynamed array
struct MyStruct {
    String [] myarray
}
array StringArray of String

To create an anonymous inline array of an attribute, structure- or union member in UML, check "Attribute is a Collection" option in its EA Detail view and enter Multiplicity (e.g. "0..*") to make EA show the attribute with square brackets. Inline arrays of method parameters are marked using stereotype «array».

To create a named array in UML, add a directed association with stereotype «arrayOf», oriented from the new array data type to the origin data type.

Inheritance

Add a generalization with stereotype «extends», oriented from the new derived data type to the origin data type.
Only single inheritance is allowed, multiple inheritance is forbidden according to Franca specification 0.3.0.

Interfaces

Interfaces are placed within UML packages by selecting a package in the EA project browser, right click -> Add -> Add Element and configure the type "Interface".{} and stereotype «interface» in the dialog box.
The stereotype shall be «FrancaServiceInterface» in order to distinguish between Franca service interfaces and other types of interfaces, e.g. internal library calls.
The service interface is mandatory in UML even if it would be empty (e.g. because only broadcasts are to be defined).
It may only contain methods and attributes, but no broadcasts.

interface version specification

Interface versions can optionally be configured in EA interface properties dialog and shall be specified like major.minor, with major and minor containing only numbers.

interface version specification "4.2"
version { major 4 minor 2 }

The semantics to use for interface version changes is specified in http://semver.org/spec/v2.0.0.html.

Inheritance

Inheritance between interfaces is expressed by an "Generalization" arrow.
Only single inheritance is allowed, multiple inheritance is forbidden according to Franca specification 0.3.0.

Attributes

To add an attribute to an interface, select the interface in the EA project browser and right click -> "Attributes..." to enter the dialog box.
Configure stereotype as of one of «attribute», «attribute readonly», «attribute nosubscriptions» or «attribute readonly nosubscriptions».
Valid name and type properties have to be specified, too.
Attributes will appear as items with a blue icon in EA.
To create an inline array definition of an attribute, it must be marked with "Attribute is a Collection" in the EA Attribute Detail view.

Methods

To add a method to an interface, select the interface in the EA project browser and right click -> "Operations..." to enter the dialog box.
Configure stereotype as of one of «method» or «method fireandforget».
To specify parameters and return values, use the edit button near the parameters text field. Method call arguments must be specified as direction "in" parameters.
Please note that Franca IDL allows to have many parameters as return values, so return values have to be specified as parameters with direction "out".
Methods will appear as items with a pink icon in EA.
Inline array definitions for method parameters must be marked with stereotype «array».

method errors

To add an error return value to a method, configure method parameters with the «error» stereotype and direction out.
There are several use cases that can be specified for a method error. Franca IDL allows maximum one Franca error to be specified per method, so even if there are several error parameters specified in UML they will be mapped to one Franca error.

  1. reference to a predefined enumeration
    Create method parameter with stereotype «error» and select a predefined enumeration type from your UML model for "type" field.
    The default value of the parameter must be left empty.
  2. anonymous enumeration of error codes
    Create method parameter with stereotype «error» and empty "type" field.
    Several error arguments like this may be specified for the same method to support multiple alternative error codes to be returned.
    If constant values for the error codes are required they may be specified within the "default value" field optionally.
  3. reference to a predefined enumeration with additional extensions
    Combine UML error parameter entries from usecase 1 and 2 within a method.

Note:
Any restrictions that apply to definition of enumerations are also valid for method errors.

Broadcasts

In general broadcasts are multicast signals sent from a server component to a client component.
Franca IDL specifies attributes, methods and broadcasts within one Franca interface.
In UML (and implementations) there must be separate service (sender) and broadcast (receiver) interfaces in order to provide attributes/methods and receive broadcasts.
This is opposite logic between UML and Franca IDL.

The solution to this problem is to move all broadcasts of a Franca interface to a separate broadcast interface. The broadcast interface shall have the same name as the service interface (which will have the name of the Franca interface) with additional "Client" as suffix. For example, Franca interface Foo would be modeled as a pair of Foo (with attributes/methods) and FooClient (with broadcasts) in UML. The broadcast interface shall have the stereotype «FrancaClientInterface».
The broadcast interface is optional, if no broadcasts shall be specified for a Franca interface it can be left out completely.
Broadcast interfaces may be empty.
In order to model the relationship between these two UML interfaces, an undirected "association" relation from broadcast interface to service interface is created to define the relationship to the service interface. The association has to use the stereotype «FrancaInterface».

 

Example: modelling client and service interface with inheritance

Furthermore, the broadcasts in the broadcast interface shall be modeled as methods with stereotype «broadcast» or «broadcast selective».

To add a broadcast to a broadcast interface, select the broadcast interface in the EA project browser and right click -> "Operations..." to enter the dialog box.
Configure stereotype as of one of «broadcast» or «broadcast selective».
Several "in" parameters may be specified, "out" parameters are invalid.
To specify parameters, use the edit button near the parameters text field.
Broadcasts will appear as items with a pink icon in EA.
Regular methods and attributes are not allowed in broadcast interfaces.

Managed Interfaces

Franca can express that one kind of interface is responsible for managing another type of interface. An example could be an USB host controller interface, which is responsible for managing USB device profile interfaces. A management relation can be expressed using an directed association with stereotype «manages».

Modeling Sequences

Using above rules is not sufficient to draw UML sequence diagrams. Although regular method calls and broadcasts can be pictured, attribute get/set access or change events require additional conventions.

Attribute Access via get/set methods

Enterprise Architect supports Properties to automatically generate get/set accessory methods for attributes. To create property accessor methods for a given attribute (already defined as specified above) is done by setting the check box "Property" in the interface attribute property dialog (select an attribute, then right click "Attribute Properties...").

Attribute Access via notification

Franca also offers the semantics of attribute change notifications, which can be specified in UML using «attribute» or «attribute readonly» stereotypes.
In order to support modeling of UML sequences with attribute change notifications, it is required to define one receiver method in the client interface for each attribute offering change notifications and provide the stereotype «callback».
The name of the change notification method should follow a naming rule, which makes mapping to its adjacent attribute easy.
Any method in the client interface with stereotype «callback» will not be visible in Franca, it is just a workaround to support sequence diagrams.

Example

Example UML treeresulting Franca-IDL file: "Logical_View/SW_Platform_Components/MyComponent.fidl"
|_GENIVI Model
  |_«root» Logical View
           |_SW Platform Components
             |_«fidl» MyComponent
                      |_«FrancaServiceInterface» TestInterfaceA
                                    |_«attribute» myattr
                      |_datatypes
                        |_«struct» MyStructType
package Logical_View.SW_Platform_Components.MyComponent
 
typeCollection datatypes {
    struct MyStructType {
    }
}
 
interface TestInterfaceA {
    attribute datatypes.MyStructType myattr
}

This example will produce one Franca IDL file named "Logical_View/SW_Platform_Components/MyComponent.fidl", which contains both interfaces and a type collection named datatypes.
Its Franca package name is "SW_Platform_Components".

Summary of used Stereotypes

UML StereotypeStatusUsed on UML TypeDescription
«array»agreedClassdefine a named array data type
«array»agreedmethod parameterdefine an anonymous inline array
«arrayOf»agreedConnectorassociate the referred type to specify an array upon
«attribute»agreedClassdefine an attribute with read/write access and notification
«attribute readonly»agreedClassdefine an attribute with read only access and notification
«attribute nosubscriptions»agreedClassdefine an attribute with read/write access without notification
«attribute readonly nosubscriptions»agreedClassdefine an attribute with read only access without notification
«broadcast»agreedClassdefine a broadcast method as part of a FrancaClientInterface
«broadcast selective»agreedClassdefine a selective broadcast method as part of a FrancaClientInterface
«enumeration»deprecatedClassdefine an enumeration data type
«error»agreedClassdefine method error codes
«extends»agreedConnectorinherit from another interface
«fidl»agreed/TBDPackagemark an UML package and its sub tree as contents to be represented within a Franca FIDL file. TBD für Franca versions >= 0.9.0
«FrancaEnum»agreedClassdefine an enumeration data type
«FrancaClientInterface»agreedClassmark an UML interface as a Franca client interface which receives broadcast notifications
«FrancaInterface»agreedConnectorspecify association between FrancaServiceInterface and FrancaClientInterface parts
«FrancaServiceInterface»agreedClassmark an UML interface as a Franca service interface
«key»agreedClassdefine a map key
«manages»tbdClassspecify managed interface relationships
«map»agreedClassdefine a map data type
«method»agreedClassdefine an interface method
«method fireandforget»agreedClassdefine an interface method which does not return any results nor execution status
«nofidl»agreedPackageexclude an UML package and its sub tree from Franca contents specification
«root»agreedPackagedefine the root of a Franca namespace
«struct»agreedClassdefine a structure data type
«struct polymorphic»proposedClassdefine a structure data type which supports polymorphism if used as method parameter or attribute
«typedef»agreedClassdefine a named data type
«union»agreedClassdefine a union data type
«value»agreedClassdefine a map value

References

Franca Specification 0.3.0

Attachments

  File Modified
PNG File uml-root-tagged-values.png Oct 14, 2015 by Manfred Bathelt
PNG File uml-root.png Oct 14, 2015 by Manfred Bathelt
PNG File interfacebroadcast.png Oct 14, 2015 by Manfred Bathelt

 

 

 

 

 

 

  • No labels