New COMOutline

Draft 0.6

October2010

Content

1.Overview

2.Concepts

2.1.Property

2.1.1.Property Service capabilities

2.1.2.Property COM Schema extensions

2.2.Activity

2.2.1.Consumer

2.2.2.Optional relay provider

2.2.3.Final provider

2.2.4.Activity Service capabilities

2.2.5.Activity COM Schema extensions

2.3.Event

2.3.1.Event Service capabilities

2.3.2.Event COM Schema extensions

3.COM service specifications

3.1.Property

3.1.1.General

3.1.2.Usage

3.1.3.Common model usage

3.1.4.OPERATION: setProperty

3.2.Activity

3.2.1.General

3.2.2.Usage

3.2.3.Common model usage

3.3.Event

3.3.1.General

3.3.2.Usage

3.3.3.Common model usage

3.4.Retrieval

4.COM data types

4.1.New COM Structures

4.2.Event structures

4.2.1.EventOccurrence

4.2.2.EventStatus

4.3.Property structures

4.3.1.PropertyStatus

4.4.Activity structures

4.4.1.ActivityOccurrence

4.4.2.OperationOccurrence

4.4.3.ActivityStatus

4.4.4.OperationStatus

4.4.5.ActivityNotificationType

5.MO COM service example

5.1.Deployment

5.2.PTU Service

5.2.1.PTU

5.2.2.Data structures

5.2.3.Service XML

1.Overview

The new COM extends the previous COM. As such it fulfills the following objectives:

It defines an entity model that MO services extend and an associated set of operations for the management and observation of that model.

By defining this standard service entity model it allows not only the specification of standard operations but also the definition of a standard historical archive and the associated services that support the archive.

The new COM adds some new features and constraints:

  • Itshall be used by every MO service.

This doesn’t mean that every MO service shall inherit from the COM operations. It means that the COM design rules shall be followed by every MO services (with COM inheritance or not).

  • It defines specific entities (or type of entities) dedicated to MO services:
  • Property
  • Activity
  • Event

Those entities are represented by the COM structures:Occurrence and Status.There is no use of Definition in these services to keep their implementation complexity down. Their creation shall be compliant with some design rules required by the new COM.

  • It includes the Common::Retrieval service (it shall be moved from Common to COM)

2.Concepts

The new COM conceptsare extracted from the current Core area:

  • Property (simplified version of Core::Parameter)
  • Activity (simplified version of Core::Action)
  • Event (simplified version of Core::Alert)

These COM services are simplified versions of their Core counterparts, it is expected that the Core services are enhanced versions of these that add the dynamic Definition aspect not included in the COM versions. Other features may also be added by Core such as Check and Conversion services in Parameter.

2.1.Property

A property contains a single MAL::Element.No information can be associated to the status of a property. Its status is only represented by a MAL::Element.

The update interval of a property is implementation specific, it is not something that can be altered, except by service specific extensions. Updates that share the same updating interval are to be published at the same time gathered as a set of COM::PropertyStatus update objects and sent in a single MAL::UpdateList. The transport layer is responsible for building the packets and conveying them: the current service Core::Aggregation is therefore not useful any more from this “physical packet” point of view; however it may be retained for the dynamic definition aspect.

2.1.1.Property Service capabilities

The COM::Property service extends COM::Status for the monitoring of properties and defines a capability for the setting of properties.

The definition of the properties in the COM extended schema specifies whether the property is read only, if it is then the set operations shall reject its identifier.

2.1.2.Property COM Schema extensions

The COM Schema contains extra elements in the service area that lists the set of properties, their type, and names:

<com:properties>

<com:property name="<name>" readOnly="false" comment="">

<smc:type name="Boolean" area="MAL"/>

</com:property>

<com:property name="<name>" readOnly="true" comment="">

<smc:type name="<type>" area="<area>" service="<service>"/>

</com:property>

</com:properties>

</smc:service>

This ability to define properties can be created at the Service level and the Capability Set level. This allows properties to be capability set dependent.

2.2.Activity

The declaration of Activity entities is given by the MO service definition: each operation tagged as a COM::Activity in the service XML represents an instance of Activity entity.

An MO service must be a COM service in order to use this feature.

Each marked operation defined by an MO service leads to a “Common Model Updates” behavior implemented by the Activity service provider.

Any component type providing or consuming an MO service that has COM::Activity operation has also to provide the service COM::Activity.

The Activity service provider is distributed in the MO service consumer and provider.

Note:

This behavior can be extended by defining other COM::Activity[Occurrence/Status] subtypes (e.g. the future Procedure service).

2.2.1.Consumer

Before the interaction is initiated, an OperationOccurrence structure shall be archived and distributed using a CompleteOccurrenceUpdate structure. It shall use a MAL::UpdateType of Creation.

After the interaction is ended, a CompleteOccurrenceUpdate structure shall be archived and distributed but setting the occurrence field to NULL. It shall use a MAL::UpdateType of Deletion.

The intermediate stages don’t lead to any updates being published by the consumer.

2.2.2.Optional relay provider

When an Operation is being passed via a relay provider, the following behaviour shall be seen.

The following OperationStatus shall be archived and distributed using a CompleteStatusUpdate structure.

  1. Upon reception of the interaction:
  2. The update type shall beModification.
  3. The activity notification type shall be RECEPTION.
  4. The OperationStatus fields messageHeader and messageBody are set to NULL.
  5. Upon transmission of the interaction to the next provider (next destination):
  6. The update type shall beModification.
  7. The activity notification type shall be FORWARD.
  8. The OperationStatus fields messageHeader and messageBody are set to NULL.

This pattern may be repeated for each relay provider.

2.2.3.Final provider

The following OperationStatus shall be archived and distributed using a CompleteStatusUpdate structure.

  1. Before the interaction is handled:
  2. If the IP is SEND then the update type shall be DELETION else the update type shall beModification.
  3. The activity notification type shall be ACCEPTANCE.
  4. The OperationStatus fields messageHeader and messageBody are set to NULL.
  5. For each stage of the IP:
  6. If it is the final stage of the IP (i.e. completed or an error is being returned) the update type shall beDeletion else it shall be MODIFICATION.
  7. The activity notification type shall be EXECUTION.
  8. The OperationStatus fields messageHeader and messageBody are assigned with the operation returned message header and body.

2.2.4.Activity Service capabilities

The COM::Activity service extends COM and includes the standard Occurrence and Status capability sets for the monitoring of Activity progress.

2.2.5.Activity COM Schema extensions

Each COM::Activity operation is marked as such as follows:

<smc:invokeIP xsi:type="com:COMInvokeOperationType" ...

2.3.Event

Event partially replaces the current Core::Alert service.

A service defines the set of Events that it may raise during its lifetime. An event is defined as a type that extends COM::EventOccurrence and is listed in a special COM service of the service specification.

A component can raise an Event at any time by publishing the event occurrence.

If an operation is defined in a Service that has error codes, these can be marked as Event error codes in the XML, in this case an associated Event shall be published concurrently.

There is COM service associated with events that allows Events to be monitored, however event generation control is through MO service specific extensions (this is something that Core::Alert will probably provide).

An event shall be raised as a COM::CompleteOccurrenceUpdate structure with the occurrence set to a specific COM::EventOccurrenceand a MAL::UpdateType of Deletion.

2.3.1.Event Service capabilities

The COM::Event service extends COM and includes the standard Occurrence and Status capability sets for the monitoring of Events.

2.3.2.Event COM Schema extensions

Each Service specific event is defined as a normal data type but it must extend COM::EventOccurrence:

<smc:composite name="LimitEvent" shortForm="MIAPL" comment="">

<smc:extends>

<smc:type name="EventOccurrence" area="COM" service="Event"/>

</smc:extends>

<smc:field name="direction" canBeNull="false" comment="">

<smc:type name="PointingDirection" area="MIA" service="PTU"/>

</smc:field>

</smc:composite>

The COM Schema contains extra elements in the service area that lists the set of Event that this service will raise on the COM::Event PubSub channel:

<com:eventsRaised>

<com:event name="<event identifier>">

<smc:type name="LimitEvent" area="MIA" service="PTU"/>

</com:event>

</com:eventsRaised>

The COM Schema also allows operations that have already been identified as COM::Activities to augment any raised errors with the fact that the error will also be published on the COM::Event PubSub channel:

</smc:messages>

<smc:errors>

<smc:errorRef xsi:type="com:COMErrorReferenceType" comment="">

<smc:type name="MAXIMUM" area="MIA" service="Cam"/>

<smc:extraInformation comment="">

<smc:type name="LimitEvent" area="MIA" service="PTU"/>

</smc:extraInformation>

</smc:errorRef>

</smc:errors>

</smc:invokeIP>

3.COM service specifications

3.1.Property

3.1.1.General

The Propertyservice provides operations to monitor and set the Property values.

Area Identifier / Service Identifier / Area Number / Service Number / Service Version
COM / Property
Interaction Pattern / Operation Name / Operation Number / Support in replay / Capability Set
All Common Model Status Operations
SUBMIT / setProperty / 100 / No

3.1.2.Usage

The consumer can provision the property values and monitor the property status changes.

3.1.3.Common model usage

The following Property service operations are COM operations:

  • setProperty

The Propertyservice complies with the common archive model as follows:

Definition / Occurrence / Status
Structure / Not used / Not used / PropertyStatus
Update structures / Not used / Not used / CompleteStatusUpdate

The entity identifiers are assigned as follows:

Identifier field / Definition / Occurrence / Status
entityId / Not used / Not used / <area>.<service>.<field>
definitionId / Not used / Not used / <service version>
occurrenceId / Not used / Set to NULL
statusId / Linear integral sequence generated by the service provider

The following variables are used in the table:

  • area: name of the area where the service is defined
  • service: name of the service that defines the property
  • service version: version number of the service
  • field: name of a field defining a property, from service specification

3.1.4.OPERATION: setProperty

TBW

3.1.4.1.General

TBW

Operation Name / setProperty
Interaction Pattern / SUBMIT
IP Sequence / Message / Field Type
IN / Submit / SetPropertyDetails
3.1.4.2.Structures

TBW

3.1.4.3.Common Model Updates

TBW

3.1.4.4.Errors
Error / Error # / Comments
UNKNOWN / Unknown property
INVALID / Invalidvalue

3.2.Activity

3.2.1.General

The Activity service provides operations to monitor operationoccurrences and status.

Area Identifier / Service Identifier / Area Number / Service Number / Service Version
COM / Activity
Interaction Pattern / Operation Name / Operation Number / Support in replay / Capability Set
All Common Model Occurrence Operations
All Common Model Status Operations

3.2.2.Usage

The consumer can monitor the operation occurrences creation, deletion and status changes.

3.2.3.Common model usage

The Activity service complies with the common archive model as follows:

Definition / Occurrence / Status
Structure / Not used / ActivityOccurrence / ActivityStatus
Update structures / Not used / TBD / TBD

The entity identifiers are assigned as follows:

Identifier field / Definition / Occurrence / Status
entityId / Not used / <area>.<service>.<operation> / From occurrence
definitionId / Not used / <service version> / From occurrence
occurrenceId / <uri consumer>/
<transaction id> / From occurrence
statusId / TBD

The following variables are used in the table:

  • area: name of the area where the service is defined
  • service: name of the service that provides the executed operation
  • operation: name of the operation
  • service version: version number of the service

The statusId is still undecided. It needs to provide a simple progression that can be followed however there are potentially many providers involved in publishing updates for a single Activity and therefore there is a risk of overlap.

3.3.Event

3.3.1.General

The Event service provides operations to monitor Eventoccurrences and status.

Area Identifier / Service Identifier / Area Number / Service Number / Service Version
COM / Event
Interaction Pattern / Operation Name / Operation Number / Support in replay / Capability Set
All Common Model Occurrence Operations
All Common Model Status Operations

3.3.2.Usage

The consumer can monitor the Event occurrences creation, deletion and status changes if the Event type supports Status (basic model does not).

3.3.3.Common model usage

The Event service complies with the common archive model as follows:

Definition / Occurrence / Status
Structure / Not used / EventOccurrence / EventStatus
Update structures / Not used / TBD / TBD

The entity identifiers are assigned as follows:

Identifier field / Definition / Occurrence / Status
entityId / Not used / <area>.<service>.<event / From occurrence
definitionId / Not used / <service version> / From occurrence
occurrenceId / TBD / From occurrence
statusId / Linear integral sequence generated by the service provider

The following variables are used in the table:

  • area: name of the area where the service is defined
  • service: name of the service that provides the event
  • event: name of the event from service specification
  • service version: version number of the service

3.4.Retrieval

This service is the current Common::Retrieval service and is just moved into the COM area.

4.COM data types

4.1.New COM Structures

4.2.Event structures

4.2.1.EventOccurrence

Structure Name / EventOccurrence
Extends / COM::Occurrence
Abstract
Field / Type / Comment

4.2.2.EventStatus

Structure Name / EventStatus
Extends / COM::Status
Abstract
Field / Type / Comment

4.3.Property structures

4.3.1.PropertyStatus

Structure Name / PropertyStatus
Extends / COM::Status
Short form / xxx
Field / Type / Comment
value / MAL::Element / The value of the property

4.4.Activity structures

4.4.1.ActivityOccurrence

Structure Name / ActivityOccurrence
Extends / COM::Occurrence
Abstract
Field / Type / Comment
nextDestination / MAL::URI
estimateTimestamp / MAL::Time
success / MAL::Boolean

4.4.2.OperationOccurrence

Structure Name / OperationOccurrence
Extends / COM::ActivityOccurrence
Short form / xxx
Field / Type / Comment
messageHeader / MAL::MessageHeader
messageBody / MAL::Element

4.4.3.ActivityStatus

Structure Name / ActivityStatus
Extends / COM::Status
Abstract
Field / Type / Comment
nextDestination / MAL::URI
estimateTimestamp / MAL::Time
success / MAL::Boolean
notificationType / COM::Activity::ActivityNotificationType

4.4.4.OperationStatus

Structure Name / OperationStatus
Extends / COM::Activity::ActivityStatus
Short form / xxx
Field / Type / Comment
messageHeader / MAL::MessageHeader
messageBody / MAL::Element

4.4.5.ActivityNotificationType

Enumeration Name / ActivityNotificationType
Short form / xxx
Enumeration Value / Short form / Comment
RECEPTION / 1
FORWARD / 2
ACCEPTANCE / 3
EXECUTION / 4

5.MO COM service example

5.1.Deployment

5.2.PTU Service

The PTU (Pan Tilt Unit) service provides a service for the monitor and control of a PTU.

The PTU service extends the COM and defines COM::Properties and as a consequence an implementation is required to provide the COM:Property service.

5.2.1.PTU

Area Identifier / Service Identifier / Area Number / Service Number / Service Version
MIA / PTU / 1
Interaction Pattern / Operation Name / Operation Number / Support in replay / Capability Set
All Common Model Occurrence Operations
INVOKE / pointAt / No / 100
SUBMIT / track / No / 101

COM Model usage

Definition / Occurrence / Status
Structure / Not Used / COM:: SimpleOccurrence / Not Used
Update structures / Not Used / COM:: CompleteOccurrenceUpdate / Not Used

COM Activities

  • pointAt
  • track

COM Events

  • LimitReached
  • LostLock

COM Properties

  • pointingDirection
  • trackMode

5.2.2.Data structures

5.2.3.Service XML

<?xml version="1.0" encoding="UTF-8"?>

<smc:specification xmlns:xsi="

xmlns:smc="

xmlns:com="

<smc:area name="MIA" number="100">

<smc:service xsi:type="com:COMServiceType" name="PTU" number="1" version="1">

<smc:capabilitySet number="100">

<smc:invokeIP xsi:type="com:COMInvokeOperationType" name="pointAt" number="100"

supportInReplay="false"

comment="">

<smc:messages>

<smc:invoke>

<smc:type name="PointRequest" area="MIA" service="PTU"/>

</smc:invoke>

<smc:acknowledgement>

<smc:type name="OccurrenceKey" area="COM" service="COM"/>

</smc:acknowledgement>

<smc:response>

<smc:type name="PointingDirection" area="MIA" service="PTU"/>

</smc:response>

</smc:messages>

<smc:errors>

<smc:errorRef xsi:type="com:COMErrorReferenceType" comment="Cannot move any further">

<smc:type name="MAXIMUM" area="MIA"/>

<smc:extraInformation comment="The PTU has reached a maximum">

<smc:type name="LimitEvent" area="MIA" service="PTU"/>

</smc:extraInformation>

</smc:errorRef>

<smc:errorRef comment="Requested direction is not supported">

<smc:type name="INVALID" area="COM" service="COM"/>

</smc:errorRef>

</smc:errors>

</smc:invokeIP>

</smc:capabilitySet>

<smc:capabilitySet xsi:type="com:COMCapabilitySetType" number="101">

<smc:submitIP xsi:type="com:COMSubmitOperationType" name="track" number="101"

supportInReplay="false"

comment="">

<smc:messages>

<smc:submit>

<smc:type name="PointRequest" area="MIA" service="PTU"/>

</smc:submit>

</smc:messages>

</smc:submitIP>

<com:eventsRaised>

<com:event name="lostLock">

<smc:type name="LostLockEvent" area="MIA" service="PTU"/>

</com:event>

</com:eventsRaised>

<com:properties>

<com:property name="trackMode" canBeNull="false" readOnly="false"

comment="Is the PTU in auto tracking mode">

<smc:type name="Boolean" area="MAL"/>

</com:property>

</com:properties>

</smc:capabilitySet>

<smc:dataTypes>

<smc:composite name="LimitEvent" shortForm="MIAPL" comment="">

<smc:extends>

<smc:type name="EventOccurrence" area="COM" service="Event"/>