JOSIF Main Page | JOSIF Guidebook | Modeling | General Patterns
| Table of Contents | ||||||||
|---|---|---|---|---|---|---|---|---|
|
The patterns listed in this section are part of the current JOSIF version. For a description of the patters planned for future versions, see General Patterns - Future.
Only in JOSIF R1.1
Only in JOSIF R1.1
The EntityIdentifier is used to uniquely identity an object across an interface. The EntityIdentifier are assumed to be opaque and globally unique.
An EntityIdentifier contains three attributes: context, dn and type.
The dn attribute contains the DistinguishedName of the object that is assumed to be unique within a given system context.
The context attribute contains an implementation specific Context which determines the system specific context for the Entity. It disambiguates the dn of the object to make it globally unique.
For entity-centric interfaces, like Resource Alarm Management, the dn contains the unique id of the alarm within the alarm list, i.e. in this case the alarmId and the context is specific to each alarm list, i.e. each instantiation of the interface.
Note that the context, even if implementation specific should have a common scheme for all interfaces involved in a given deployment. However, the way to define the context might vary. It might be a jndi entry like in OSS/J, a security token or any other form.
The type defines the type of the referenced entity. This string is implementation technology specific. For example in XML it is filled by the implementation with an XML type reference. In java it is filled with a classpath reference.
An EntityIdentifier is equal to another EntityIdentifier if both the context and dn attributes are identical.
To simplify implementation, all attributes in an EntityIdentifier are defined as strings or name value pairs of strings.
Entity Identifiers should be used to reference objects across the interface. They can be involved as input parameters in operations, either explicit or common operations.
There are 2 ways to define an EntityIdentifier as explicit attribute or parameter:
- If the EntityIdentifier only relates to a single class, then the type of the class should be used as datatype for the attribute or parameter setting to true the attribute passedById of the corresponding tipAttribute, or tipParameter stereotype. This is true also for navigable association ends (or roles).
- If the EntityIdentifier can relate to multiple classes not known at modeling time, then the datatype ObjectName should be used. This datatype will be replaced by the generators by an EntityIdentifiers.
EntityIdentifiers should not be arbitrarily extended.
Extensibility
Extensibility is provided through the attribute extensionInfo.
This attribute has a datatype Any that is described in Extensibility in Internal Framework Model Note that this datatype is different from the primitive any datatype, as it includes a list of any.
Entities and notifications are extensible by default. So an extensionInfo attribue is added for all entities and notifications.
Association classes, Enumerations and Exceptions are not extensible.
Limited extensibility is available for Exceptions by using the details attribute present in all exceptions (See details in Internal Framework Model#Pre-defined Exceptions).For datatypes and operations, extensibility is controlled at the model level.
For datatype, if the attribute isExtendable of the stereotype tipDatatype is set, then the extensionInfo will be added as an attribute of the datatype. For operations, if the attribute isExtendable of the stereotype tipOperation is set, then the extensionInfo will be added as an inOut parameter of the operation.
Exceptions
There are two types of common exceptions defined in the Interface Framework, i.e., predefined common exceptions and optional common exceptions.
- The predefined common exceptions are automatically inserted into all operations, with the exception of one-way operations which do not have exceptions at all. These exceptions are listed in Internal Framework Model#Pre-defined Exceptions.
- The optional common exceptions are used as needed for a given operation. They must be explicitly added to an operation. These exceptions are listed in Common Framework Model#Common Exceptions.
Interface developers should try as much as possible to reuse these common exceptions rather than creating new ones.
Every common exception contains an “error reason” parameter of type String that may be used to supply more information (See details in Internal Framework Model#Pre-defined Exceptions). This information should contain the specific condition(s) that have resulted in the exception as defined in the description part of the associated Use Cases.
Exception Hierarchy
The following figure shows the predefined exceptions and their hierarchy relationship, where the hierarchy goes from general (at the top) to more specific (moving towards the bottom). The distinction is made between exceptions that are caused by the server (server-side issue) and exceptions that are essentially the fault of the requesting system (client-side issues).
The server system, i.e., the system that generates the exception, should use the most specific exception that it can determine. So, for example, the UnableToComply exception (general) would only be used if the server cannot determine a more appropriate (specific, detailed) exception such as CommunicationLoss.
The following figure shows the optional exceptions and their hierarchy relationship, where the hierarchy goes from general (at the top) to more specific (moving towards the bottom). The distinction is made between exceptions that are caused by the server (server-side issue) and exceptions that are essentially the fault of the requesting system (client-side issues).
2 remarks on this figure:
- In some cases, an optional common exception is related to one of the predefined common exceptions. In those cases, the related predefined common exception is also shown (in green).
- NotInValidState and ObjectInUse cannot be classified as caused strictly by client- or server-side. For example, another client might be using an object instance when a client tries to manage the same object instance. This is more of a race condition as opposed to an exception caused by either the client or the server.
...
Iterator Pattern
Iterator Protocol Neutral
Iterator Meta-Model Definitions
In the Interface Meta-Model#Operational_Modeling, the Iterator Pattern applies as one of the special Client-Server exchange cases regarding the transfer of (potentially) large set of (bulk) data. The Iterator Pattern allows the following two data transfer interaction styles:
...
...
In the Interface Meta-Model (TIP Meta-Model), an operation is explicitly identified using the Iterator Pattern when:
- The Interface Meta-Model#Operation is marked with bulkTransferPattern set with ITERATOR, and
- At least, one Interface Meta-Model#Parameter is marked with the isBulkPotential and its multiplicity must allow more than a single instance (array of data).
Iterator Implicit Model Definitions
All Iterator Pattern interface model meta-data definitions are implicitly established (not visible to TIP Interface Model projects) in the Iterator package of the TIP Framework TIP_Generator_Internal_Model sub-project.
Iterator Model Example
The Service Problem Management is the very first of the TIP Interfaces to be using the TIP Framework.
Its Tigerstripe model includes the following operation definitions using the Iterator interaction pattern.
The below settings define the output parameter objects as an array of ServiceProblem entity instances that can be retrieved using an iterator because it has the potential to be bulk:
- TIP service interface: ServiceProblemInterface
- Operation: getServiceProblemsByTemplate
- tipOperation stereotype:
- bulkTransferPattern = ITERATOR
- Argument:
- Name: objects
- Type: org.tmforum.tip.service.problem.ServiceProblem
- Multiplicity: 0..*
- Direction: out
- tipParameter stereotype:
- passedById is not set (Entity instances are to be returned as an array).
- isBulkPotential is set (Need for an iterator associated with this array of entity data).
- tipOperation stereotype:
Iterator Protocol Specific
- Refer to the TIP Framework TIP Soap Generator sub-project for XML mapping rule details tipOperation: BulkTransferPattern - Iterator in TIP Soap Generator Mapping Rules - Part VI
Notifications
TIP defines a common parent for all TIP Notifications. It is called NotificationBase and shown in orange on the figures below. 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 1 attribute: sourceTime. Please refer to Internal Framework Model#Notifications for details.
TIP defines 4 types of standard notifications:
- Object Creation Notification
- Object Deletion Notification
- Object Discovery Notification
- Attribute Value Change Notification
TIP defines a common parent for all TIP Common Notifications. It is called CommonNotification and shown in green on the figures below.
CommonNotification inherits by injection of CommonNotificationBase, shown in orange on the figures below.
This type is injected by the TIP Generators into code generated from Tigerstripe Event (i.e. notification) artifacts where the 'Extends' field is equal to Common Notification. It includes 3 attributes: sourceTime (inherited from NotificationBase, ObjectType and ObjectId. Please refer to Internal Framework Model#Notifications for details.
The concept of State Change does not exist as this has been merged in the AVC Notification.
For each of the standard notifications above, there is a base notification object defined in the Common Model (Common Framework Model#Common Notifications). Those notifications are shown in green in the figures below.
The TIP Framework generators will generate for each class the appropriate notifications based on the stereotypes defined for the objects. These notifications will inherit from one of the common objects listed above.
Object Creation Notification
The exception hierarchy for Object Creation Notification is shown on the figure below:
Object Creation notification is enabled for a given entity if the atribute objectCreationNotification of the tipClass stereotype is set to YES for this entity.
In this case, the generators (especially SOAP Generator) will generate a notification called <Entity>OCN (in the figure, ServiceProblemOCN in purple) that inherits from OCNotification.
This notification will contain a single atribute object of type <Entity> (Service Problem in the figure) that will contain the value of all the attributes of the entity set at creation.
Object Deletion Notification
The exception hierarchy for Object Deletion Notification is shown on the figure below:
Object Deletion notification is enabled for a given entity if the atribute objectDeletionNotification of the tipClass stereotype is set to YES for this entity.
In this case, the generators (especially SOAP Generator) will generate a notification called <Entity>ODelN (in the figure, ServiceProblemODelN in purple) that inherits from ODelNotification.
This notification does not contain any additional attribute.
Object Discovery Notification
The exception hierarchy for Object Discovery Notification is shown on the figure below:
Object Discovery notification is enabled for a given entity if the atribute objectDiscoveryNotification of the tipClass stereotype is set to YES for this entity.
In this case, the generators (especially SOAP Generator) will generate a notification called <Entity>ODisN (in the figure, ServiceProblemODisN in purple) that inherits from ODisNotification.
Attribute Value Change Notification
The exception hierarchy for OAttribute Value Change Notification is shown on the figure below:
Attribute Value Change notification is enabled for a given entity if one of the atribute of the entity (or naviguable association end) has the attribute notificationDefinition of the tipAttribute stereotype is set to YES for this entity.
In this case, the generators (especially SOAP Generator) will generate a notification called <Entity>AVCN (in the figure, ServiceProblemAVCN in purple) that inherits from AVCNotification.
This notification will contain all the attributes that have notificationDefinition enabled.
This would allow to report the new values of those attributes.
...
Only in JOSIF R1.1
Common Operations Describes the Common Operations pattern.
Filtering
Only in JOSIF R1.1
Operations requiring selection of entities based on attribute values may
provide a filter construct.
This filter construct may be based on primitive.filter or be associated
via common operations stereotypes (see common operations).
A common operation stereotype may define a filter as being a template
or a combination of a template and a query filter.
A query filter is mapped to a string which is implementation technology specific. For example in XML it is filled by the implementation with an XPATH expression. In java it is filled by a JPA query expression.
A template filter is mapped to a sequence of attribute matching filters
(using associative lookup).
When both template and query filters are specified then a choice construct
is being generated.
Operation using primitive filters as input arguments are mapped to operations
using query filters.