Interface Meta-Model

Owned by Craig Gallen [Administrator] (Unlicensed)
Last updated: Feb 07, 2013Version comment
14 min read

JOSIF Main Page | JOSIF Guidebook | Modeling | Interface Meta-Model

Introduction

JOSIF interface specifications include data and operation aspects.

Data aspects are written in terms of entities and datatypes with their attributes and are described in section Information Modelling.

Operation aspects are written in terms of operation signatures and notification signatures.
Notification signatures specify any argument types.

Operational aspects are described in section Operational Modelling.

For instance, in the Web-services Profile, entities and datatypes are specified in terms of XML-Schema. Operation and notification signatures are specified in terms of WSDL operation-types while argument types are specified by means of XML data-types (i.e. a WSDL and XML schema).

The meta-model of a TIP interface shown below shows the split between the information modeling and the interface modeling:


The Information part of the meta-model (colored in blue) will be mapped to both RSM and Tigerstripe artifacts.
The Operational part of the meta-modeld (colored in orange) will be mapped only to Tigerstripe.
Boxes in light yellow refer to datatypes used in the meta-model.

The meta-model is also available as a Tigerstripe project (See TIP MetaModel Model).

Stereotypes are used to complement standard UML properties to bring implementation-related decoration. This information is decribed here in a neutral way. Patterns used to define the stereotypes can be found in the Stereotypes section of the General Patterns. Detailed description of the stereotypes can be found in TIP RSM Profile for the Information Model part and in TIP Profile for the Operational part and the overvall implementation view in Tigerstripe.

Information Modeling

The SID will be the foundation for the TIP Information Model i.e. all the information and data aspects of all TIP interfaces will be defined in the SID and imported from the SID to Tigerstripe. The information model developed for any interface will be delivered as part of the SID model.

The information model should follow the various patterns used throughout the SID.

The Information Modeling part covers classes (entities), datatypes, enumerations, associations and association classes.

The different meta-model objects related to the Information Model are described in this section.

ABE (Aggregated Business Entity)

A ABE or Aggregated Business Entity is the grouping mechanism used in SID. The properties of an ABE are high cohesion within the ABE and loose coupling among ABEs.

The ABE corresponds to a UML package, but not all packages are ABEs, as an ABE can contain sub-packages.

If there is a need to change SID ABEs, lie add new ABEs or split existing ABE, this needs to be identified very early in the process (study or BA) and the SID team needs to be involved in the process to get their agreement.

Package hierarchy is identical in RSM and Tigerstripe, but package names are different as RSM package names are not suitable for implementation.
The attribute implementationPackage of the tipPackage stereotype is used to do this mapping. It will contain the name of the implementation package to be used in Tigerstripe. It is mandatory for all implemented packages.
Figures, examples, instances should be grouped in specific packages, which will be marked with the stereotype _ doNotImplement_. Such packages won't be exported to Tigerstripe.

The following picture provides an overview of the structure of the ABEs in the SID

and the one below the structure of the same packages as implementation packages in Tigerstripe

Modeling Rules

Use all the SID patterns defined in Appendix 2 of the SID Model: Addendum 0 – SID Primer.

Note: the SID patterns are currently covered in a separate primer document, but not complete (the SID team are working to improve this)

A few key SID patterns to remember:

  • No multiple inheritance, not supported at implementation level.

  • All attributes should have a data type

  • Only diagrams in “figure” folders, marked doNotImplement. Same for instances or examples.

  • No operations on entities. This is only part of the Operational Model, described later and defined in Tigerstripe.
  • Associations should be navigable in at least one direction.
  • Associations should have names and association roles should also have names, as those names will be used as attribute names if the association is navigable.
  • Avoid special characters in names and description, like <, &... Use plain text for all descriptions.
  • Avoid nested classes.

UML 2.0 adds “pointer” attributes in both entities when adding a bidirectional association this means that cross ABE associations must be closely managed.

Entity

TIP calls for each of the components to be managed within the OSS/BSS application to be modeled as an entity; entities (instances) are classified into entity types (classes).

Entity types are characterized by a common set of properties that are exposed as attribute types.
An entity instance (or just entity) is an instance of a particular entity type (e.g. CircuitPack #1); the values of the attribute types define the state of the entity and help distinguish the entity from other entities.

The TIP does not define how managed entities are implemented within the OSS/BSS application; the guidebook only defines the realization of the interfaces to the managed entities. The guidebook neither defines how changes in the entities (by virtue of client management) are reflected in the related network- or service-components, nor how changes in the components are reflected in the related entity.

An entity is defined in the SID (RSM) as a UML class and it is mapped to Tigerstripe as an Entity artifact.

The characteristics of an Entity are:

  • documentation : documentation for the entity
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • inherits_from : indicates this entity class extends or inherits from another one.
    • RSM: corresponds to a Generalization association
    • Tigerstripe: maps to Extends
  • isAbstract : indicates that this entity class is abstract, i.e. cannot be instantiated.
    • RSM: maps to Abstract checkbox
    • Tigerstripe: maps to isAbstract checkbox
  • objectCreationNotification : Indicates of an Object Creation Notification should be generated. This is mapped to the attribute objectCreationNotification of the tipClass stereotype.
  • objectDeletionNotification : Indicates of an Object Deletion Notification should be generated. This is mapped to the attribute objectDeletionNotification of the tipClass stereotype.
  • objectDiscoveryNotification : Indicates of a Discovery Notification should be generated. This is mapped to the attribute objectDiscoveryNotification of the tipClass stereotype.
  • support : Indicates whether the identified entity must be represented in TIP interface or not. If the entity is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. This is mapped to the attribute support of the tipClass stereotype.

Attribute

An attribute represents some characteristic of an object type.

Attributes can be applied on Entities, Association Classes, Complex Datatypes, Notifications and Exceptions.

The characteristics of an Attribute are:

  • documentation : documentation for the attribute
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • readOnly : indicates the attribute is read-only, i.e. cannot be set.
    • RSM: Read Only is a checkbox in the "Qualifiers" group.
    • Tigerstripe: present as a checkbox.
  • isInvariant : Indicates if the attribute is invariant. This is mapped to the attribute isInvariant of the tipAttribute stereotype.
  • multiplicity : multiplicity of the attribute. Defined as Multiplicity for both RSM and Tigerstripe. The possible values are
    • 1
    • 0 to 1 (0..1)
    • N (0..N)
    • 1 to N (1..N)
  • defaultValue : Indicates the default value of the attribute. When a default value is defined, the "creator" do not have to provide a value.
  • ordered : Applicable for list of attributes (multiplicity of N or 1 to N). Indicates if the values of this attribute are ordered.
    • RSM: Ordered is a checkbox in the "Qualifiers" group.
    • Tigerstripe: Ordered present as a checkbox if the multiplicity is multiple.
  • unique: for a multi-valued multiplicity, this specifies whether the values in an instantiation of this attribute are unique (i.e., no duplicate attribute values are allowed); a set has unique values, while a bag can have non unique values. A sequence has both ordered and unique values.
  • notificationDefinition : Indicates if a common notification (AVC) will be generated for this object. Default value is false, meaning no notification generated. This is mapped to the attribute notificationDefinition of the tipAttribute stereotype.
  • passedById : Applicable when the datatype of the attribute is an Entity.

Indicated if this entity is passed by value (False) or by Id (true). This is mapped to the attribute passedById of the tipAttribute stereotype.

  • support : Indicates whether the identified attribute must be represented in TIP interface or not. If the attribute is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. This is mapped to the attribute support of the tipAttribute stereotype.

Datatype

Datatypes are usually complex components designed to become attributes of entities.

The data types can be categorized into:

  • Primitive (or basic) types (boolean, interger, string, real…)
  • Enumeration (list of predefined values)
  • Complex types (groups of attributes, types shared by all like TimePeriod….)
  • MultiValueList (set), represented using the underlying datatype with a multiplicity of N or 1 to N.

Primitive Types

TIP defines the following primitives datatypes:

TIP defines the following primitives datatypes:

  • any : allow at implementation level to be replaced by any datatype.
  • boolean
  • byte
  • char
  • date
  • double
  • float
  • int
  • long
  • objectName : will be replaced at interface level by an EntityIdentifier (please refer to the Entity_Identifier section of the Internal Framework Model) allowing to input any entity. When the entity to provide has a known type, then an explicit association should be preferred.
  • short
  • String : not that in Tigerstripe, this is String with a capital S.
  • time : correspond to ITU-T time.

Enumeration

All enumerations in TIP do not use any literal in RSM and use string based enum in Tigerstripe.

Complex Types

A complex datatype includes attributes. However, a datatype is completely different from an entity as it does not have any lifecycle, nor can it be used as basis for notifications. It is simply carrying data.

Association

Associations are characterized by their cardinality and the roles at each association end.

Containment is a special type of relationship. It is of particular importance for business entities such as the resource inventory business entities, for example, representing physical equipment hierarchies. There shouldn’t be any difference in the way containment relationships are managed by the TIP interfaces.

Abstract associations should be marked doNotImplement in RSM.

By convention, the name of the association should be self-descriptive and composed by the names of both ends separated by a verb describing the association, i.e. ProblemHasAffectedServices can be the name of an association between Problem and Service.

The characteristics of an Association are:

  • documentation : documentation for the association
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • inherits_from : indicates this association extends or inherits from another one.
    • RSM: corresponds to a Generalization association
    • Tigerstripe: maps to Extends

Association Class

An Association Class has all the characteristics of an Association with the addition of the support of attributes. From a meta-model point of view, an Association Class extends an Association.

The characteristics of an Association Class are:

  • documentation : (inherited from Association)documentation for the association class
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • inherits_from : (Inherited from Association) indicates this association class extends or inherits from another one.
    • RSM: corresponds to a Generalization association
    • Tigerstripe: maps to Extends
  • support : Indicates whether the identified association class must be represented in TIP interface or not. If the association class is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. This is mapped to the attribute support of the tipAssociationClass stereotype.

Association End

An association end has some unique set of properties, making it a separate meta-model object.

Each association has 2 association ends: a_end and z_end.
When an association end is navigable, then it acts as an attribute and the tipAttribute stereotype can be applied to it. It is useless to apply this stereotype and a non navigable association end.

The characteristics of an Association End are:

  • documentation : documentation for the association end
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • navigable : Navigable association ends will lead to an attribute in the remote object class. At least one end of an association should be navigable.
  • readOnly : indicates the association eend is read-only, i.e. cannot be set.
    • RSM: Read Only is a checkbox in the "Qualifiers" group.
    • Tigerstripe: present as a checkbox.
  • isInvariant : Indicates if the association end is invariant. This is mapped to the attribute isInvariant of the tipAttribute stereotype.
  • multiplicity : multiplicity of the association end. Defined as Multiplicity for both RSM and Tigerstripe. The possible values are
    • 1
    • 0 to 1 (0..1)
    • N (0..N)
    • 1 to N (1..N)
  • defaultValue : Indicates the default value of the aassociation end. When a default value is defined, the "creator" do not have to provide a value.
  • ordered : Applicable for list of attributes (multiplicity of N or 1 to N). Indicates if the values of this attribute are ordered.
    • RSM: Ordered is a checkbox in the "Qualifiers" group.
    • Tigerstripe: Ordered present as a checkbox if the multiplicity is multiple.
  • unique: for a multi-valued multiplicity, this specifies whether the values in an instantiation of this attribute are unique (i.e., no duplicate attribute values are allowed); a set has unique values, while a bag can have non unique values. A sequence has both ordered and unique values.
  • notificationDefinition : Indicates if a common notification (AVC) will be generated for this object. Default value is false, meaning no notification generated. This is mapped to the attribute notificationDefinition of the tipAttribute stereotype.
  • passedById : Applicable when the datatype of the attribute is an Entity.

Indicated if this entity is passed by value (False) or by Id (true). This is mapped to the attribute passedById of the tipAttribute stereotype.

  • support : Indicates whether the identified association end must be represented in TIP interface or not. If the association end is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. This is mapped to the attribute support of the tipAttribute stereotype.

Operational Modeling

The TIP Operational Model i.e. all the aspects related to operations of all TIP interfaces will be defined in Tigerstripe.

The Operational Model covers service interfaces, operations, events and exceptions.

The different meta-model objects related to the Operational Model are described in this section.

Service Interface

A Service Interface is the basis building block of the operation modeling part.
Each Interface Package contains at least one Interface Service.
The Service Interface wil lcontain operations.

A Service Interface can also manage Entities and emits Notifications.
In TIP, a number of notifications (Object Creation, AVC...) are defined against the Entity (see the Entitysection of the Interface Meta-Model). To indicate that these notifications will be emitted by a Service Interface, the entity should be associated as a Managed Entity to the Service Interface in the Details tab of the Service Interface. Explicit notifications can also be added there.

 

The characteristics of a Service Interface are:

  • documentation : documentation for the service interface
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • inherits_from : indicates this service interface extends or inherits from another one.
    • RSM: corresponds to a Generalization association
    • Tigerstripe: maps to Extends
  • isAbstract : indicates that this service interface is abstract, i.e. cannot be instantiated. The operations defined in this interface can only be implemented in derived interfaces.
  • support : Indicates whether the identified service interface must be represented in theTIP interface or not. If the service interface is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. At least one service interface in a given interface package should be marked Mandatory. This is mapped to the attribute support of the tipServiceInterface stereotype.

 

Operation

Operations are defined within the scope of a Service Interface.

Operations alwways retrun void. Output is returned using inOut or Out parameters. Operations can throw exceptions. All pre-defined exceptions (see the Exceptions section  in the General Patterns) are automatically added by the generators to the operation.

The characteristics of an Operation are:

  • documentation : documentation for the operation
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • isIdempotent : The operation can be repeated providing the same result every time.
  • bulkTransferPattern : This attribute allows the selection of the bulk data transfer implementation style. This is applicable when at least one of the parameter's isBulkPotential attribute of the tipParameter stereotype is set to true. Only ITERATOR is supported in JOSIF V1.0. Values:
    • NONE (default)
    • ITERATOR
    • FILE
  • emitsEvents : This attribute indicates the capability of the Target OS operation to emit event notifications. If checked, the operation can emit progress events. The events that can be emitted are listed under the emittedEvents attribute.
  • emittedEvents : This attribute lists the events that can be emitted by the operation. It is a list of event names, separated by commas. The event names should be fully qualified valid events defined in the model, e.g org.tmforum.tip.cbe.spm.myEvent.
  • isOneWay : This attribute indicates that the operation is either an input or an output with respect to the service interface. The operation is an input oneWay if it has only input parameters. It is an output oneWay if it has only output parameters.
  • isExtendable : Indicates if the operation is extendable.
  • support : Indicates whether the identified operation must be represented in the TIP interface or not. If the operation is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. At least one operation in a given service interface should be marked Mandatory. This is mapped to the attribute support of the tipOperation stereotype.

Parameter

Parameter represents the parameters or arguments of the operation. There are 3 types of operation parameters:

  • in parameters, used only in input
  • out parameters, used only in output
  • inout parameters, used in both input and output

The characteristics of an Parameter are:

  • documentation : documentation for the parameter
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • direction : This attribute defines the directionality of the operation parameter. Values:
    • in
    • inOut
    • out
  • multiplicity : multiplicity of the parameter. Defined as Multiplicity for both RSM and Tigerstripe. The possible values are
    • 1
    • 0 to 1 (0..1)
    • N (0..N)
    • 1 to N (1..N)
  • isBulkPotential : This attribute indicates that this parameter can potentially be a very large collection, which will require a bulk data transfer pattern implementation. Atomic definition (unit) is based on the parameter's associated data type. The selection of the bulk data transfer is defined using the tipOperation stereotype bulkTransferPattern attribute. This is mapped to the attribute isBultPotential of the tipParameter stereotype.
  • defaultValue : Indicates the default value of theparameter.

When a default value is defined, the "creator" do not have to provide a value.

  • isOrdered : Applicable for list of parameters (multiplicity of N or 1 to N). Indicates if the values of this parameter are ordered.
  • isUnique : for a multi-valued multiplicity, this specifies whether the values in an instantiation of this attribute are unique (i.e., no duplicate attribute values are allowed); a set has unique values, while a bag cna have non unique values. A sequence has both ordered and unique values.
  • passedById : Applicable when the datatype of the parameter is an Entity.

Indicated if this entity is passed by value (False) or by Id (true). This is mapped to the attribute passedById of the tipParameter stereotype.

  • support : Indicates whether the identified parameter must be represented in TIP interface or not. If the parameter is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. This is mapped to the attribute support of the tipParameter stereotype.

Notification

Notification represents the notifications explicitly defined in the model.
Generic notifications (Object Creation, AVC...) are defined at Entity and Attribute level directly using the corresponding stereotypes.

TIP defines a common parent for all TIP Notifications. It is called NotificationBase. This type is injected by the TIP Generators into code generated from Tigerstripe Event (i.e. notification) artifacts where the 'Extends' field has been left as an empty string. It includes 3 attributes: sourceTime, ObjectType and ObjectId. Please refer to the Notifications section of the Internal Framework Model for details.

The characteristics of a Notification are:

  • documentation : documentation for the notification
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • inherits_from : indicates this notification extends or inherits from another one.
    • RSM: corresponds to a Generalization association
    • Tigerstripe: maps to Extends
  • isAbstract : indicates that this notification is abstract, i.e. cannot be instantiated.
    • RSM: maps to Abstract checkbox
    • Tigerstripe: maps to isAbstract checkbox
  • support : Indicates whether the identified notification must be represented in TIP interface or not. If the notification is required to be represented in all cases then the value should be set to "M" (Mandatory) otherwise it should be set to "O" (Optional) indicating that a choice will be made on some other basis at some other point in the process. This is mapped to the attribute support of the tipNotification stereotype.

Exception

Exception represents the exceptions explicitly defined in the model.

There are two types of common exceptions defined in the Interface Framework, i.e., predefined common exceptions and optional common exceptions. Interface developers should try as much as possible to reuse these common exceptions rather than creating new ones. Please refer to Exceptions for more details on this pattern.

All exceptions have a common parent ExceptionBase. This type is injected by the TIP Generators into code generated from Tigerstripe Exceptions. See the section Pre-defined Exceptions of the Internal Framework Model for details.

the characteristics of an Exception are:

  • documentation : documentation for the exception
    • RSM: maps to Documentation
    • Tigerstripe : maps to Description
  • inherits_from : indicates this exception extends or inherits from another one.
    • RSM: corresponds to a Generalization association
    • Tigerstripe: maps to Extends