Mapping GDMO Templates to IDL Interfaces

Figure: Inheritance Hierarchy of Interfaces of Managed Object Classes

Since all generated IDL interfaces inherit from ManagedObject, the necessary functionality to support CMIS request and responses can be provided through the implementation of the OSIMgmt::ManagedObject interface. It is envisaged that the ManagedObject interface will provide support for such things as scoping, filtering, and attribute groups, by declaring operations on a per object basis for use by the gateway to fulfill scoped and filtered requests. This issue is deferred to the definition of Interaction Translation and of the ManagedObject interface in a separate document.

GDMO identifiers are subject to the same lexical translation and disambiguation rules defined for ASN.1 identifiers in Lexical Translation . As "/" is a legal character in GDMO identifiers (but not in ASN.1), it will be translated as the literal string "_SLASH_".

GDMO template order is determined by its use inside Managed Object classes. Templates not used (for example, Name Bindings, Parameters, Attributes, Packages, etc, that are declared but are not used or not accessible from Managed Object classes in the document) are not mapped. Imported templates are considered as if they were local to the current document for lexical purposes.

With the exception of managed object classes, each template REGISTERED AS clause is not mapped into the IDL files generated by the specification translation.

Error Handling

This solution will allow any invokers of an IDL operation to handle CMIP errors through exceptions. To enhance IDL readability, macros are provided defining the set of exceptions which each operation type might raise. A convenient side-effect of this is that PARAMETERs in general and SPECIFIC-ERRORs in particular need only be mapped to a type-declaration, so that a suitable TypeCode would be generated for use with IDL any.

Mapping Managed Object Templates to IDL

For each template in a GDMO specification, the method for translating from that template to the appropriate IDL definitions is described. This is done recursively starting from the MANAGED OBJECT CLASS template shown in Managed Object Class Template Structure .

Table: Managed Object Class Template Structure

A managed object class, maps to a management IDL interface with the same name plus additional interfaces which support notifications. Interface top inherits from ManagedObject and #includes OSIMgmt.idl. All other management interfaces multiply inherit from the interfaces corresponding to the managed object classes in the DERIVED FROM clause and must #include the files where IDL interface definitions corresponding to those managed object class templates have been generated. Then for each package, CONDITIONAL or otherwise, do the following steps (output to management IDL interface unless otherwise stated):

• Generate IDL comments containing the name of the package and, if it is CONDITIONAL, the PRESENT IF text.

• List the names of the attributes, actions and notifications as comments.

• Copy the behaviours of the package as comments.

• Copy the attribute-group information as comments.

• Declare a set of IDL operations for each attribute in each package as described in Mapping an Attribute as a Set of IDL Operations . Copy any behaviour text and/or attribute specification relating to the attribute as comments in order to include information about default-values, permitted-values, required-values, etc.

• For each Action, declare an IDL operation, as described in Mapping to an Operation on the Primary Interface . If the action has a WITH REPLY SYNTAX clause, then generate the IDL necessary to support the handling of multiple replies.

• For each Notification, copy the behaviour text of the corresponding NOTIFICATION template as a comment. In addition, generate IDL operations in the _N and _NP modules (as described in Mapping to Operations in Notification Modules ).

The REGISTERED AS clauses are translated as:

// <class-label> ... REGISTERED AS { a b c d e f }

#pragma ID <mapped-class-label> "OSIOID:a.b.c.d.e.f"

This is only done for Managed Object Class templates.

Mapping an Attribute as a Set of IDL Operations

<type>	<attribute-label>Get() raises (ATTRIBUTE_ERRORS);
void	<attribute-label>Set(in <type> value)
        raises (ATTRIBUTE_ERRORS);
void	<attribute-label>Add(in <type> value)
        raises (ATTRIBUTE_ERRORS);
void	<attribute-label>Remove(in <type> value)
        raises (ATTRIBUTE_ERRORS);
<type>	<attribute-label>SetDefault()
        raises (ATTRIBUTE_ERRORS);

where <type> is the ASN.1 for the Attribute type translated to IDL via the mechanisms defined in ASN.1 Type to CORBA-IDL Translation . Note that <attribute-label> is the attribute identifier after disambiguation (that is, it may have a suffix of the form <__n>). Note that Add and Remove operations manipulate sets and hence take values of the same type as the attribute itself.

For each attribute property in the list, IDL operations are generated according to Mapping Attribute Properties to IDL Operations . Each operation is generated at most once for each attribute in an interface.

Table: Mapping Attribute Properties to IDL Operations

Mapping Parameters to IDL Types

Table: Parameter Template Production

The mapping proceeds by translating the syntax of the attribute to an IDL type. If the ATTRIBUTE construct is used, the IDL type is the type of the reference attribute. Behaviour definitions are transcribed as comments, as is the CONTEXT type information. The mapping generates a new IDL type declaration, where the new type is named after parameter label and the type is the translation of the WITH SYNTAX or ATTRIBUTE constructs.

Examples

Example: Mapping Parameters to IDL Types

Mapping Actions to IDL Operations

As an additional complexity, actions may be either confirmed or unconfirmed, and this may be selected at run-time.

Table: Action Template Production

Mapping of Action Parameters

Mapping to an Operation on the Primary Interface

Handling Multiple Replies

Examples

Example 1

suspend ACTION
    MODE CONFIRMED
    PARAMETERS not-supported, not-running;
    WITH INFORMATION SYNTAX ActionModule.Suspend;
    WITH REPLY SYNTAX ActionModule.ServerState;
REGISTERED AS { 1 2 3 4 9 };
not-supported PARAMETER
    CONTEXT SPECIFIC-ERROR;
    WITH SYNTAX ActionModule.ReasonCode;
REGISTERED AS { 1 2 3 4 10 };
not-running PARAMETER
    CONTEXT SPECIFIC-ERROR;
    WITH SYNTAX ActionModule.ServerState;
REGISTERED AS { 1 2 3 4 11 };

This would translate in the primary interface as follows:

typedef ActionModule::ReasonCodeType not_supportedType; // SPECIFIC-ERROR
typedef ActionModule::ServerStateType not_runningType; // SPECIFIC-ERROR

ActionModule::ServerStateType suspend(in ActionModule::SuspendType actionInfo)
    raises (ACTION_ERRORS, UsingMR);

// PARAMETERS not-supported, not-running;

Example 2

suspend ACTION
    PARAMETERS not-supported, not-running, time-delay;
    WITH INFORMATION SYNTAX ActionModule.Suspend;
REGISTERED AS { 1 2 3 4 9 };

The operation definitions in the primary interface would look like this:

void suspend (in ActionModule::SuspendType actionInfo)
    raises (ACTION_ERRORS);

// PARAMETERS not-supported, not-running, time-delay;

oneway void suspendUnconfirmed (in ActionModule::SuspendType actionInfo);

Mapping Notifications to IDL Operations

Mapping of notifications must enable the use of typed or untyped events via the push or pull models. The mapping generates two sets of operations in the interfaces of the <nickname>_N and <nickname>_NP modules. However, due to issues surrounding the GDMO/CMIP notification mechanisms, the issue of how notification handling is setup is deferred to the Interaction Translation document. It is recommended that a comment be generated, listing the notifications on the primary interface.

CORBA event channels do not allow for operations which have a return type. In GDMO it is allowable for notifications to have reply syntaxes; however this is not believed to be used. In view of this it was decided not to map reply syntaxes for notifications. For similar reasons, no user exceptions are raised by notification operations.

Table: Notification Template Production

To maximise the flexibility of events, two alternatives are supported. Pure untyped events are supported by the CMIP header data as well as an any to carry the data. This results in the necessary type code being generated. Alternatively, interfaces supporting fully typed events are also generated in both push and pull flavours. Note that operations supporting typed delivery of notifications are produced in two interfaces per document (one for push and one for pull). These interfaces are called Notifications and PullNotifications and are scoped within a module with the same name as the file to ensure uniqueness.

Mapping of Event Parameters

Mapping to Operations in Notification Modules

in ASN1_ObjectIdentifier sourceObjectClass, 
in X711CMI::ObjectInstanceType sourceObjectInstance, 
in ASN1_ObjectIdentifier eventType, 
in X711CMI::ASN1_GeneralizedTimeOpt eventTime,

followed by an in parameter of type translated from the WITH INFORMATION SYNTAX clause named notifInfo. The operations are named as <notificaton-label> and <notification-label>Unconfirmed respectively. Both operations have the return type void.

Similarly, the pull model is supported by two operations generated in the _NP module. These have the following out parameters for the CMIP header components:

out ASN1_ObjectIdentifier sourceObjectClass, 
out X711CMI::ObjectInstanceType sourceObjectInstance, 
out ASN1_ObjectIdentifier eventType, 
out X711CMI::ASN1_GeneralizedTimeOpt eventTime,

followed by an out parameter of type translated from the WITH INFORMATION SYNTAX clause named notifInfo. The operations are named as pull_<notification-label> and try_<notification-label> and have void and boolean return types respectively. Note that with the pull model, event delivery is inherently confirmed.

To support the untyped event mechanism, a suitable IDL type will be defined in the OSIMgmt.idl file. However, definition of such a type is postponed to Interaction Translation.

Example

objectCreation NOTIFICATION
    BEHAVIOUR objectCreationBehaviour;
    WITH INFORMATION SYNTAX Notification-ASN1Module.ObjectInfo
        AND ATTRIBUTE IDS
        sourceIndicator SourceIndicator,
        attributeList AttributeList,
        notificationIdentifier NotificationIdentifier,
        correlatedNotifications CorrelatedNotifications,
        additionalText AdditionalText,
        additionalInformation AdditionalInformation;
REGISTERED AS { joint-iso-ccitt ms(9) smi(3) part2(2) notification(10) 6}

would be translated as follows:

// in X721_N module 
  void objectCreation (
    in ASN1_ObjectIdentifier sourceObjectClass, 
    in X711CMI::ObjectInstanceType sourceObjectInstance, 
    in ASN1_ObjectIdentifier eventType, 
    in X711CMI::ASN1_GeneralizedTimeOpt eventTime,
    in X711Not::ObjectInfoType notifInfo);

  oneway void objectCreationUnconfirmed (
    in ASN1_ObjectIdentifier sourceObjectClass, 
    in X711CMI::ObjectInstanceType sourceObjectInstance, 
    in ASN1_ObjectIdentifier eventType, 
    in X711CMI::ASN1_GeneralizedTimeOpt eventTime,
    in X711Not::ObjectInfoType notifInfo);

// in X721_NP module
  void pull_objectCreation (
    out ASN1_ObjectIdentifier sourceObjectClass, 
    out X711CMI::ObjectInstanceType sourceObjectInstance, 
    out ASN1_ObjectIdentifier eventType, 
    out X711CMI::ASN1_GeneralizedTimeOpt eventTime,
    out X711Not::ObjectInfoType notifInfo); 

  boolean try_objectCreation (
    out ASN1_ObjectIdentifier sourceObjectClass, 
    out X711CMI::ObjectInstanceType sourceObjectInstance, 
    out ASN1_ObjectIdentifier eventType, 
    out X711CMI::ASN1_GeneralizedTimeOpt eventTime,
    out X711Not::ObjectInfoType notifInfo);

Resolving Inheritance Collisions

The following steps should be applied in order to each managed object class of the input GDMO document. Before processing a class, all its ancestors in the inheritance tree must be processed, and the results of that processing taken into account:

1. Check for repetition of attribute/operation names across all ancestors in inheritance tree.

2. Revise ancestor name collisions by revising the inheritance hierarchy, if required.

3. Add only non-redundant attribute/operation methods from the current object.

4. Map the revised derived managed object class to IDL interface.

Implementation of this (or an equivalent) algorithm is optional. If a translator does not implement such an algorithm, it will not be able to successfully translate GDMO documents that cause inheritance collisions.

This algorithm was chosen because it maintains the inheritance tree as large as possible, and it also results in the generation of cleaner IDL code.

Examples

Figure: Inheritance Hierarchy Showing Name Collision

Inheritance Hierarchy Showing Name Collision describes the inheritance hierarchy of managed object classes, where the same attributes are declared in inherited interfaces by the following GDMO:

aObject MANAGED OBJECT CLASS
    DERIVED FROM "dmi":top;
    CHARACTERIZED BY aObjectPkg1 PACKAGE
        ATTRIBUTES aAttr1 GET, aAttr2 GET; ;
REGISTERED AS {xxx ?};

bObject MANAGED OBJECT CLASS
    DERIVED FROM "dmi":top;
    CHARACTERIZED BY bObjectPkg1 PACKAGE
        ATTRIBUTES aAttr2 GET-REPLACE, bAttr1 GET; ;
REGISTERED AS {xxx ?};

cObject MANAGED OBJECT CLASS
    DERIVED FROM "dmi":top;
    CHARACTERIZED BY cObjectPkg1 PACKAGE
        ATTRIBUTES cAttr1 GET;;
REGISTERED AS {xxx ?};

dObject MANAGED OBJECT CLASS
    DERIVED FROM cObject;
    CHARACTERIZED BY dObjectPkg1 PACKAGE
        ATTRIBUTES aAttr1 GET-REPLACE, dAttr1 GET; ;
REGISTERED AS {xxx ?};

abObject MANAGED OBJECT CLASS
    DERIVED FROM aObject, bObject;
    CHARACTERIZED BY abObjectPkg1 PACKAGE
        ATTRIBUTES abAttr1 GET; ;
REGISTERED AS {xxx ?};

adObject MANAGED OBJECT CLASS
    DERIVED FROM aObject, dObject;
    CHARACTERIZED BY acObjectPkg1 PACKAGE
        ATTRIBUTES cAttr1 GET-REPLACE; ;
REGISTERED AS {xxx ?};

-- Assume for simplicity that all attributes have WITH SYNTAX "AttrType"

The IDL interfaces for aObject, bObject, cObject and dObject are:

interface aObject : X721::top
{
    AttrType aAttr1Get() raises (ATTRIBUTE_ERRORS);
    AttrType aAttr2Get() raises (ATTRIBUTE_ERRORS);
};

interface bObject : X721::top
{
    AttrType aAttr2Get() raises (ATTRIBUTE_ERRORS);
    void aAttr2Set(in AttrType value) raises (ATTRIBUTE_ERRORS);
    AttrType bAttr1Get() raises (ATTRIBUTE_ERRORS);};

interface cObject : X721::top
{
    AttrType cAttr1Get() raises (ATTRIBUTE_ERRORS);
};

interface dObject : cObject
{
    AttrType aAttr1Get();
    aAttr1Set(in AttrType value) raises (ATTRIBUTE_ERRORS);
    AttrType dAttr1Get() raises (ATTRIBUTE_ERRORS);
};

If abObject is mapped as inheriting from interfaces aObject and bObject, then there is collision on attribute aAttr2. In this case the inheritance tree is modified such that abObject is inherited only from aObject and include the attribute and operation of bObject that is not present in aObject and as well as its own attributes and operations to get:

interface abObject : aObject
{
    void aAttr2Set(in AttrType value) raises (ATTRIBUTE_ERRORS);
    AttrType bAttr1Get() raises (ATTRIBUTE_ERRORS);
    AttrType abAttr1Get() raises (ATTRIBUTE_ERRORS);
};

If adObject is mapped as inheriting from interfaces aObject and dObject, then there is a collision on attribute aAttr1. In this case the inheritance tree is modified such that adObject is inherited from aObject and cObject. In the revised object include the attribute and operation of dObject that is not present in aObject and cObject and its own attributes and operations to get:

interface adObject : aObject, cObject
{
    void aAttr1Set(in AttrType value) raises (ATTRIBUTE_ERRORS);
    AttrType dAttr1Get() raises (ATTRIBUTE_ERRORS);
    void cAttr1Set(in AttrType value) raises (ATTRIBUTE_ERRORS);
};

Revised Inheritance Hierarchy of Managed Object Classes describes the modified inheritance hierarchy of managed object classes shown in Inheritance Hierarchy Showing Name Collision .

Figure: Revised Inheritance Hierarchy of Managed Object Classes