Model Transformation Rules

Owned by Craig Gallen [Administrator] (Unlicensed)
Last updated: Feb 06, 2013 by Marc FlauwVersion comment

JOSIF Main Page | JOSIF Guidebook | Modeling | General Patterns | Model Transformation Rules

Only in JOSIF V1.1.

Introduction

All the data objects of a TIP interface are part of the SID. So the modeling goes through 2 stages:

  1. Information Modeling: this is done in the SID, using the Information Model Tooling, based on RSM (will be RSA in the future).
  2. Implementation Modeling: this is in 2 separate projects (Model and Dependencies), using the Interface Tooling, based on Tigerstripe.

(Note that the operation model, e.g., the operations and notifications, are not included in the SID model at all but rather added in the second stage as part of the modeling in Tigerstripe.)

The SID is the overall information model developed within TM Forum. It covers the whole spectrum of the data of a service provider in one model. The SID is an information model and as such has a few specificities:

  • It contains nearly only classes, no datatypes,
  • Classes within it have usually few attributes but a lot of relations.

The Implementation Model is the data model used by an interface and specific to this interface.

SID Import Tool Overview

The base for the implementation model is a subset of the SID model which imported into the Tigerstripe tool from RSM (to be RSA in the future). The SID is exported in UML2 and imported into Tigerstripe. The TIP SID Import tool is used to pilot this import. It is an Eclipse plugin, accessible through the Import menu of Eclipse by selecting Tigerstripe/ UML2 Import.

In addition to the functionalities of selection, the TIP SID Import tool includes a set of unique transformation rules to move from the SID model to an implementation model in a repeatable and simple way.

The SID_Import tool uses an xml configuration file (SID_Import.xml) to keep the import and transformation rules specific to the project. Please refer to the TIP SID Import page for more details on how to use this tool.

For the Model project, the TIP_SID_Import tool allows one to select the ABEs to be imported. The scope of an interface is always one or more full ABEs. The import_package_only rule allows importing a full package, excluding all objects outside of the package even if used in it. This is a key rule for importing data model of an interface in the Model project.

An example of package rule for importing an ABE in a Model project is provided below:

<artifact>
       <type>package</type>
       <name>SID Phase 9dot5 Models::Resource Domain::Resource Trouble ABE::Alarm Severity Assignment Profile ABE</name>
       <rule>import_package_only</rule>
</artifact>

For the Dependencies project, the SID_Import tool allows to import specific classes or datatypes that are referenced by the model project. The 2 main rules are the import_datatype and import_class.

The import_datatype rule imports a datatype and all attributes and all datatypes required for its attributes. It is used to populate a dependency project with a datatype used either in the data model, but outside of interface ABE or used by a parameter.

<artifact>
	   <type>datatype</type>
	   <name>SID Phase 9dot5 Models::Resource Domain::Resource ABE::TIP Resource ABE::Network Resource Basic ABE::LayerRate</name>
	   <rule>import_datatype_and_attributes</rule>
</artifact>

The import_class rule imports a class and all attributes and all associations navigable from this class.

When following an association, by default, the target class will be empty unless it is tagged as passed by value. It is used to populate a dependency project with a class used either in the data model, but outside of interface ABE or used by a parameter.

Even if the SID is the source for the data part of the implementation, using it directly in the implementation would lead to interfaces that would be too complex and not useable. This has driven the need for model transformation rules.

Model Transformation Rules

The model transformation rules have been designed based on the needs of real interface projects and might evolve in future as new projects bring new requirements.

The main model transformation rules can be grouped into the following categories:

  • Exclusion
  • Pruning/Collapsing
  • Relationship Management
  • Extensibility

Exclusion Rules

There are 3 different ways to exclude objects in the implementation model

  1. doNotImplement stereotype: All data (e.g. class, datatype, association, package, attributes) marked doNotImplement will be excluded. As this stereotype is stored in the Information Model, the exclusion has to be valid for all interfaces. This stereotype is typically used on figures or figure packages, or on SID objects that have either been deprecated but are still kept in the SID, or excluded from implementation. The Import tool compensates for partial declaration, like a target class marked doNotImplement, but not the association or only a role marked doNotImplement
  2. tipProductSupport stereotype: This stereotype indicates attributes or classes that are specific to MTMN and MTOSI respectively but should not been implemented in TIP. All data marked with values nmlEmlOnly and onlyMtnmAndMtosi are excluded from the import process. This rule is implemented in JOSIF V1.1.1.
  3. Exclude statement in SID_Import.xml. This statement excludes an object only for the current interface. It should be used when in the context of an interface, some attributes or associations might not be needed, but might be useful in some other cases. It is applicable today only to attributes and association ends (roles).

Let’s illustrate the use of the exclude statement with the example below:

In this example, the Resource has a relation to the ResourceSecurityEntity. However, if the interface being designed is not related to security, this relationship is not useful. The stereotype doNotImplement cannot be used as it would prevent the use of this relationship in all interfaces.

The exclude statement for this relationship is provided below:

<artifact>
	<type>class</type>
	<name>SID Phase 9dot5 Models::Resource Domain::Resource ABE::LogicalResource ABE::LogicalResource</name>
	<rule>import_class_and_attributes_and_associations</rule>
	<exclude>
		<attribute>_resourceSecurityEntity</attribute>
	</exclude>
</artifact>

Note that the role name is used in the exclude statement.

Collapsing Rules

The collapsing rule allows collapsing a class into either its direct parent or its direct child. This is especially useful in the top levels of the hierarchy where a class might have multiple levels of parents.

This is illustrated on the figure below:

The LogicalResource has 4 levels of parents Resource, ManagedEntity, Entity and RootEntity. All these parents are empty as they don’t have implementable attributes. So keeping them is not useful for the implementation.

In the figure above the collapsing can be recursive. From RootEntity to Entity, then from Entity to ManagedEntity and finally from ManagedEntity to Resource.

An example of collapsing statements is provided below:

<collapse>
      <from>SID Phase 9dot5 Models::Common Business Entities Domain::Root Business Entities ABE::RootEntity</from>
      <to>SID Phase 9dot5 Models::Common Business Entities Domain::Root Business Entities ABE::Entity</to>
</collapse>
<collapse>
      <from>SID Phase 9dot5 Models::Common Business Entities Domain::Root Business Entities ABE::Entity</from>
      <to>SID Phase 9dot5 Models::Common Business Entities Domain::Root Business Entities ABE::ManagedEntity</to>
</collapse>

If the class being collapsed has attributes and associations, then the SID_Import tool will handle them as if they were present on target class.
Collapsing is only valid today for direct parent or child today. Extension is planned to other associations, especially composite aggregations, in future.

Relationship Management Rules

Given the intensive use of relations in the SID, handling of relations is key for the SID Import tool.

The first question the interface developer needs to ask is whether the target object of the relation is needed by value or by id.

In most of the cases, referencing a remote object by id would be sufficient. To indicate that a remote object should be referenced by its id, the attribute Passed by Id of the tipAttribute stereotype of the relation role should be set to true. In this case the SID Import tool will still generate the association artifact, but will create the remote object as an empty class without attributes or associations, as they won’t be needed.

JOSIF has a standard entity identifier pattern (See Entity Identifier pattern) and the generators will handle this case by injecting the standard EntityIdentifier structure.

In case the target of the relation is not in the model, then an empty class needs to be added in the Dependencies model. A specific import_empty_class rule has been created for this case. This rule will create the class with its documentation and stereotypes but without any attribute or association.

An example is provided below:

	
           <artifact>
		<type>class</type>
		<name>SID Phase 9x Models::Resource Domain::Resource ABE::Resource</name>
		<rule>import_empty_class</rule>
	</artifact>

For this interface (Resource Alarm Management), the Managed Object attribute is a Resource, but only the id/name of the resource is needed. So an empty Resource object is created in the Dependencies project.

The handling of identifier as provided by the JOSIF Identifier pattern provides a typed identifier. There might be a few cases where this pattern might not be the best choice and a non-typed identifier might be more appropriate.

In this case, the approach is to refactor the identifier as a string as illustrated on the figure below:

In this example, it is not useful to have EntityIdentifier for securityServiceUser and securityServiceProvider'. These 2 relationship roles are transformed as attributes of type String in the ResourceAlarm entity.
This rule is not implemented yet in JOSIF Rel 1.1. Today, the relationship object should be deleted and the string attributes created by hand.
When the target object of the association needs to be passed by value, then the question the developer should ask is whether the target object should be an entity or a datatype.
An entity supports a lifecycle with associated events (ObjectCreation, Attribute Value change…). If the remote object is more of a utility object, simply used to carry data where having a separate lifecycle does not make sense, then the class should be refactored as a datatype.
The example below illustrates this rule:

The CrossedThreshold object does not have a real lifecycle as it just carries data associated with the threshold crossed. So this class should be refactored as a datatype.'This rule is partly implemented in JOSIF V1.1.1. '
To transfrom a class in a datatype, the class should be tagged with the keyword_baseType_or_dataType_in the SID as shown below:

As soon as a class is marked with one of these 2 keywords, the SID Import tool will transform it in a datatype.
Notes:
* If the object has to be imported in the Dependency model, then it should be added in the SID_Import.xml file of the Dependencies project with the rule: import_class_and_attributes_and_associations
* In JOSIF V.1.1.1, handling of associations targeting the transformed class is not supported. Attributes will have to be created by hand in the source classes. This will be fixed in a next release.
If the target object of the association needs to be passed by value and should not be refactored as a datatype, then be sure to uncheck the attribute_Passed by Id_of the tipAttribute stereotype of the relation role. If the target object is not in the Model, then add it to the Dependencies model using the rule import_class_and_attributes_and_associations.
h1. Extensibility Rules
The SID is using an extensibility pattern called CharacteristicValue/CharacteristicSpec. The figure below is showing a use of this pattern.

The use of this pattern allows one to indicate that the object can be extended by additional attributes which are not described in the model.
In the implementation model, a specific datatype_AttributeValuePair'' exists to allow adding new attributes identified by their names.

The CharacteristicValue/ characteristicSpec pf the SID should be refactored in a set of attributeValuePair.

This rule is not implemented yet in JOSIF rel 1.1. The workaround today is to manually edit the relationship to CharactericValue and to replace the datatype by AttributeValuePair.