Common Operations

Owned by Craig Gallen [Administrator] (Unlicensed)
Last updated: Dec 04, 2012Version comment

JOSIF Main Page | JOSIF Guidebook | Modeling | General Patterns | Common Operations

Only in JOSIF V1.1.

Common operations cover create, delete, set and get applied to a single entity class.

They define patterns and signatures for each of these operations. Those operations are defined using tipEntityXxx stereotypes on the corresponding entity artifact, where Xxx is the name of the operation. These stereotypes are defined in the TIP_Profile.

The generators, based on the values of the attributes of each stereotype, will generate the corresponding common operation.

Associating Common Operations to a Service Interface

Operations can only be part of a Service Interface. However, the common operations are defined through stereotypes applied on an Entity artifact (Thing in our example).

So it is needed to associate this entity to a service interface.
This is done with a single association to a service interface, resulting in all defined common operations to be added to the service interface. The Details pane of the Service Interface is used to add the entity for which common operations need to be generated as a managed entity as shown below:

Note that this step is adding behind the scene a dependency between the service interface and the entity called "manages". This dependency is already resulting in having the events for the entity being generated by this service interface, providing consistency.

Create Common Operation

This common operation is defined by the stereotype tipEntityCreate that describes the various attributes used to configure this operation.

The following figure shows the documentation that will be generated for this directive:

There will be at maximum one create operation per object type that will be created automatically by the Tigerstripe generators. Only one object will be created at a time.

The referenceObject specifies an existing instance of a managed object of the same class as the new object to be created. Attribute values associated with the reference object instance become the default values for those not specified by the createData parameter.

The createDataForObjectType is just a placeholder here. The generator will define a specific structure based on the attributes of the given object type that are settable at time of object creation. This is defined by the attribute settableAtCreation of the tipAttribute stereotype.

The object name would be in createData in the case of autonaming.
If the server determines that the object already exists (either via the name or some other info), then the request shall fail with the exception Duplicate. If supported by the object type in question, an Object Creation notification is sent when this operation is successful.

This operation is extendable by the user, if needed. It is based on the value of the attribute isExtendable of the tipEntityCreate stereotype. The operation is mandatory or not based on the value of the attribute isExtendable of the tipEntityCreate stereotype.

Delete Common Operation

This common operation is defined by the stereotype tipEntityDelete that describes the various attributes used to configure this operation.

The following figure shows the documentation that will be generated for this directive:

The objects to be deleted are identified by their EntityIdentifier which is the type used in TIP for identifying an object. If deletion based on a filter is needed, then a getThingIds must be used to return all ids matching a filter. This set of ids can then be used as input of the delete operation.

If supported by the object type in question, an Object Deletion notification is sent when this operation is successful.

This operation is not extendable. The operation is mandatory or not based on the value of the attribute support of the tipEntityDelete stereotype.

Get Common Operations

The common operations define 3 different get operations:

1. Single entity get (getThing): getting the values of a single instance,

2. Multiple entities get (getThings): get all entities matching a filter, returning the values,

3. Multiple entities get by ids (getThingIds): get all entities matching a filter, returning only the ids

It is possible to have all 3 get directives defined for the same interface. For this reason and for alignment with the set, it has been decided to use 2 stereotypes: one for single instance get et and one for multiple instances get.

Using a single stereotype with an attribute to indicate single/ multiple or both would have been possible, but it would have implied that the description, extensibility and support attributes would be shared.

Get Single Instance Common Operation

This common operation is defined by the stereotype tipEntityGet that describes the various attributes used to configure this operation.

The following figure shows the documentation that will be generated for this directive:

This operation is always extendable by the user. The operation is mandatory or not based on the value of the attribute support of the tipEntityGet stereotype.

Get Multiple Instances Common Operation

This common operation is defined by the stereotype tipEntityGetMuliple that describes the various attributes used to configure this operation.

GetThingIds Common Operation

getThingIds will be generated if the value of the attribute ‘’getType’’ of the tipEntityGetMuliple stereotype is id or 'both'.

The following figure shows the documentation that will be generated for this directive:

The values of the objects are returned by ids, as a set of EntityIdentifiers.

Filter type is defined in the Common Model. It can be either a template filter or a choice of template or query filter. Please refer to Filtering for more details. Support of the template filter is mandatory.

This operation is always extendable by the user. The operation is mandatory or not based on the value of the attribute ‘’support’’ of the tipEntityGetMultiple stereotype.

GetThings Common Operation

getThings will be generated if the value of the attribute ‘’getType’’ of the tipEntityGetMuliple stereotype is value or both.

The following figure shows the documentation that will be generated for this directive:

The values of the objects are returned using an iterator.

Filter type is defined in the Common Model. It can be either a template filter or a choice of template or query filter. Please refer to Filtering for more details. Support of the template filter is mandatory.

This operation is always extendable by the user. The operation is mandatory or not based on the value of the attribute ’’support’’ of the tipEntityGetMultiple stereotype.

Set Common Operations

The common operations define 3 different set operations:

1. Single entity set (setThing): setting a single instance, all attributes should be set in an atomic way,

2. Multiple entities set, best effort (setThings): set all entities matching a filter,

3. Multiple entities set, atomic (setThingsAtomic): set all entities matching a filter in an atomic way

It is possible to have 2 set directives defined for the same interface, a single instance one and a multiple instances
one. For this reason, it has been decided to use 2 stereotypes: one for single instance set and and one for multiple
instances set, as a given interface might need to support both. Using a single stereotype with an attribute to indicate
single/ multiple or both would have been possible, but it would have implied that the description, extensibility and
support attributes would be shared.

Set Single Instance Common Operation

This common operation is defined by the stereotype tipEntitySet that describes the various attributes used to configure this operation.

The following figure shows the documentation that will be generated for this directive:

The single instance is atomic, all attributes should be set.

The setDataFor<Thing> and AddDataFor<Thing> are just placeholders here. The generator will define a specific structure based on the attributes of the given object type that are settable (resp. settable and are set-valued (multiplicity , or 1..) for AddData) after object creation. One or more of the parameters valuesToBeSet, valuesToAdd, valuesToRemove can be provided in the same operation, but at least of those parameters should be present.

The entire modified object is returned.

If supported by the object type in question, an AVC notification is sent when this operation is successful.

This operation is extendable by the user, if needed. It is based on the value of the attribute isExtendable of the tipEntitySet stereotype. The operation is mandatory or not based on the value of the attribute support of the tipEntitySet stereotype.

Set Multiple Instances Common Operation

This common operation is defined by the stereotype tipEntitySetMuliple that describes the various attributes used to configure this operation.

SetThings Common Operation

setThings will be generated if the value of the attribute ‘’isAtomic’’ of the tipEntitySetMuliple stereotype is false.

The following figure shows the documentation that will be generated for this directive:

Best effort only applies at the entire object level, i.e., either all the request attributes for an given object are set or not.

The setDataFor<Thing> and AddDataFor<Thing> are just placeholders here. The generator will define a specific structure based on the attributes of the given object type that are settable (resp. settable and are set-valued (multiplicity , or 1..) for AddData) after object creation. One or more of the parameters valuesToBeSet, valuesToAdd, valuesToRemove can be provided in the same operation, but at least of those parameters should be present. There is only a single combination of valuesToBeSet, valuesToAdd and valuestoRemove with only 1 single value per attribute. This value will be set/added/removed in all object instances selected by the filter.

If supported by the object type in question, several AVC notifications are sent when this operation is successful.

Filter type is defined in the Common Model. It can be either a template filter or a choice of template or query filter. Please refer to Filtering for more details. Support of the template filter is mandatory.

Only the objects successfully modified are returned.

This operation is extendable by the user, if needed. It is based on the value of the attribute ‘’isExtendable’’ of the tipEntitySetMultiple stereotype. The operation is mandatory or not based on the value of the attribute ‘’support’’ of the tipEntitySetMuliple stereotype.

SetThingsAtomic Common Operation

setThingsAtomic will be generated if the value of the attribute ‘’isAtomic’’ of the tipEntitySetMuliple stereotype is true.

Note that setThingsAtomic is not yet implemented in JOSIF V1.1. Refer to mantis bug 505. This will be fixed in JOSIF V1.2

The following figure shows the documentation that will be generated for this directive:

This is an atomic operation, all objects should be successfully set or the operation will failed and no object will be set.

The setDataFor<Thing> and AddDataFor<Thing> are just placeholders here. The generator will define a specific structure based on the attributes of the given object type that are settable (resp. settable and are set-valued (multiplicity , or 1..) for AddData) after object creation. One or more of the parameters valuesToBeSet, valuesToAdd, valuesToRemove can be provided in the same operation, but at least of those parameters should be present. There is only a single combination of valuesToBeSet, valuesToAdd and valuestoRemove with only 1 single value per attribute. This value will be set/added/removed in all object instances selected by the filter.

If supported by the object type in question, several AVC notifications are sent when this operation is successful.

Filter type is defined in the Common Model. A filter should be able to specify a set of ids to cover the set multiple instances by id.

Only the objects successfully modified are returned, in this case, all the objects matching the filter.

This operation is extendable by the user, if needed. It is based on the value of the attribute ‘’isExtendable’’ of the tipEntitySetMultiple stereotype. The operation is mandatory or not based on the value of the attribute ‘’support’’ of the tipEntitySetMuliple stereotype.