Tooling

Owned by Craig Gallen [Administrator] (Unlicensed)
Last updated: Feb 12, 2013Version comment

JOSIF Main Page | JOSIF Guidebook | Tooling

Principles

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

  • Information Modeling: this is done in the SID, using the Information Model Tooling, based on RSM.
  • Operational Modeling: this is in separate projects, using the Interface Tooling, based on Tigerstripe.

Each interface project should have a unique short acronym, usually 2 to 5 letters, like PM, SSO, RAM...
This acronym will be used in a number of places in the interface. We will use XXX as interface acronym in the examples below.

Information Model Tooling

This work is done in the SID, using the RSM tool and is decribed in the wiki of the TM Forum SID Community at the page
Procedures for SID domain Members. Please refer to this page for all details on Information Model tooling.

Setting up the Interface Project

Tigersripe is used for the interface projects. The JOSIF Project Creator must be used to create the interface projects.

The project name used in JOSIF Project Creator should be TIP_XXX, where XXX is the interface short acornym. The corresponding id for the Model project should be: org.tmforum.tip.xxx Note the lower case for xxx in the id. The id for the Dependency project should suffixed by dep, i.e. org.tmforum.tip.xxx.dep

The Getting Started page contains all the details to help initial setup.

TIP Profile

The TIP Profile page contains the description of the TIP Profile in Tigerstripe, including primitive datatypes and stereotypes.

Interface Design

Importing Information Model

In TIP, for a given interface project, there are 2 different Tigerstripe model projects:

  • The Model project, which contains the main ABE(s).
  • The Dependencies project, where the dependencies of the Model project, i.e. the objects outside the project ABE(s), but referenced by those objects.

For example, for Service Problem Management specification, we have following Tigerstripe model projects:

  • TIP_SPM_Model which contains the Service Problem ABEs.
  • TIP_SPM_Dependency where the dependencies such as TroubleTicket, GeographicPlace, Party e.t.c defined.

For each project, the information model part (class, datatypes, association) would need to be imported from the SID branch used for information modeling.

A model project might contain no information model ABE if it is a pure task-centric interface like an Inventory interface. In this case, no import is needed for the Model project.

The TIP SID Import tool is used for importing the information model. The use of this tool requires to set up a SID_Import.xml file in each project. The syntax and the use of this tool are explained in the  TIP SID Import page.

The main steps of the import process are:

  • Define the ABEs to import in the SID_Import.xml file of the Model project,
  • Define the main objects referenced by this model in the SID_Import file of the Dependencies project. Include only the main objects (datatypes and classes) and don't worry of parents or associations, they will be handled by the import tool,
  • Import the data for the Dependency project (Import->Tigerstripe/ UML2Import),
  • Build the module for the Dependency project (Export->Tigerstripe/ Tigerstripe Module, accept all defaults),
  • Copy this module to the Model project and add it as a dependency,
  • Import the data for the Model project. All external references should be resolved. If the model project still has errors, check if a dependency has not been forgotten and if so, update the SID_Import file of the Dependency project and restart the process.

Don't forget that data that might be needed by the operations and not present in the Model project should also be imported in the Dependency project.

One of the most frequent errors when imported is due to Rich Text present in the SID. Rich Text should be converted to Plain Text before exportign the SID. If not done, please checj step 10 on the SID wiki page Installing RSM for SID use

Avoid not supported Tigerstripe features

A few uml features that might be used in the SID are not supported by Tigerstripe:

  • Abstract associations
  • Inheritance of associations
  • Multiplicity of 0

If one of those features has been used in an object that needs to be imported, the problem would have to be fixed, either by marking the abstract association as doNotImplement, or by changing the multiplicity of zero to one that is supported.

Developing the Operational Model

The Operational Model includes all additional information not present in the Information Model.

It includes operations in Service Interfaces, Notifications and Exceptions In some specific cases, some datatypes or enumerations not relevant for the Information Model might also be added at this level. However, in the more general case, if a specific data object is needed for an operation, then it should be checked first:
1) if it exists in the SID. In this case, simply edit the SID_Import.xml file of the Dependencies Model and follow the steps described in Importing Information Model to import the dependencies model again and rebuild the corresponding module.
2) if it needs to be added to the Information Model of the interface. In this case, augment the Information Model in the SID and follow the steps described in Importing Information Model to import the Model again.

Service Interfaces

Operations are grouped in Service Interfaces that are named Session Facade in Tigerstripe. An interface specification must have at least one Service Interface, but having more than one is possible if needed by the design of the interface. Please use the stereotype tipServiceInterface to indicate if the implementation of the service interface is mandatory or not.

For entity-centric interfaces centered around one object, like Service Problem or TroubleTicket, the recommendation is to name the main Service
Interface <Object>Interface. For example, ServiceProblemInterface in case of SPM where the main object is the Service Problem. For these entity-centric interfaces, if some common operations, like create, delete, get or set are needed, then it might be worth considering using the Common Operations pattern. This pattern is used by defining the needed tipEntityXxx stereotype on the corresponding entity artefact. If for any reason, this pattern is not suitable for interface, then defining explicitly the needed operation is possible. It is however recommended to try to follow as much as possible the signature of the corresponding common operation for consistency.

Operations

All TIP operations should return void.
Do not forget to add and document the tipOperation stereotype on each operation.
Add needed parameters with corresponding tipParameter stereotype.

Pre-defined Exceptions.are added to all operations. Any Common Exceptions. can be added and specific exceptions might be added as needed.

Notifications

For a given Entity, TIP defines 4 types of standard notifications:

  • Object Creation Notification
  • Object Deletion Notification
  • Object Discovery Notification
  • Attribute Value Change Notification

The concept of State Change does not exist as this has been merged in the AVC Notification.

The TIP Framework generators will generate for each class the appropriate notifications based on the stereotypes defined for the objects. Please refer to the Notification general pattern for more details on common notification.

It is also possible to define explicit notifications in the model using the Interface Meta-Model#Notification  artefact.

Validating the Model

The TIP Model Validator is a plugin allowing you to validate the model at any time during the development.

To validate the model, select it in the Explorer and in the righ-click menu, select Validate TIP Model.
The pop-up will indicate the results and any warning or error will be displayed in the standard Eclipse Problems panel.

It is recommended to run the  TIP Model Validator right after importing the Information Model, as it implements some TIP specific rules stricter than the standard UML checks of RSM.

The validator should also be run once the first operations have been developed and before publishing the specifications.

Adding needed files for the Specification

All the files that need to be included in the final specification need to be included in the project <PROJECT_NAME>_Spec_Release_Package. For example, TIP_SPM_Spec_Release_Package for the SPM specification.

Under the directory src/main/resources of this project, several directories have been created by the Project Creator:

  • Business_Agreement: put in this directory the BA document (in doc and pdf formats) corresponding to this specification
  • Information_Agreement: this directory contains a sub-directory models. Put in this directory the modules corresponding to the Dependencies and the Model project. The modules are read-only versions of the models. They are the jar files generating bu doing an Export-> Tigerstripe Module.
  • Interface_Implementation: for any additional file related to the implementation
  • ReleaseNotes: this directory contains the release notes (in doc and pdf format) and the notice applicable to this project.
  • Supporting_Material This directory contains any additional supporting documents that need to be included in the specification kit.

Generating the Specification

The maven tool is used for generating the specification.

The Getting Started page provides details on the installation and initial setup needed. All the steps in this page should have been followed to have a clean environment.

For generating the specification:

1. Close Eclipse. The maven build will run the Tigerstripe generators and leaving Eclipe open might interfere with the build process.

2. Navigate in a explorer window to the <PROJECT_NAME>_BaseProject in your Eclipse workspace and open a command window in this folder. Alternatively, use Run..., then type in the Open: box

cmd

, and then do a

 cd <PROJECT_NAME>_BaseProject

, replacing <PROJECT_NAME> by your own project like TIP_SPM.

3. In the command window type

mvn -U clean install

This will build your project.

The resulting specification kit is located in the target directory of the <PROJECT_NAME>_Spec_Release_Package.

Interface Projects

This section describes the various projects that are part of a TIP interface specification.

These projects must be created by the  JOSIF Project Creator  for getting correct settings.

In the examples below, it is assumed that the TIP project name (TIP_Archetype_Project) entered in the project creator is TIP_SPM.

BaseProject

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_BaseProject.

This is the base project used as base for the other maven projects.

Model

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_Model.

This is the project that will contain the model of the interface. Please refer to Interface Design for more details.

Dependencies

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_Dependencies.

This is the project that will contain the model dependencies for the model project. This project will be used to generate a Tigerstripe module (read-only version of the model) that will be used in the model project. Please refer to Interface Design for more details.

DocSpecPackage

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_DocSpecPackage.

This project is used for packaging the IA documentation.

ModelSpecPackage

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_ModelSpecPackage.

This project is used for packaging the model files.

JvtSpecPackage

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_JVTSpecPackage.

This project is used for packaging the Jvt interface of the interface.

SoapSpecPackage

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_SoapSpecPackage.

This project is used for packaging the SOAP specification of the interface. Note that when applying the generators on the model, the result present in the target directory of the model project is incomplete and this step is needed to add the missing files coming from common and internal models.

Spec_Release_Package

Assuming TIP_SPM as project name in Project Creator, this project will be named: TIP_SPM_Spec_Release_Package.

This project is used to build the interface kit. This project is also containing the additonal files needed for the specification. Please refer to Adding needed files for the Specification for details.