Mapping GDMO Templates to IDL Interfaces

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_".

The IDL mapping of a GDMO document consists in mapping each of its Managed Object Class templates with all referenced templates within it considered as if they were specified inline. Attribute Groups are not mapped. Package templates are mapped by the mapping of their contents. Templates that are not referenced by any managed object class template are not mapped. Thus, Name Binding templates are not mapped to IDL definitions.

The mapping algorithm progresess by mapping the Managed Object Class templates in their order in the GDMO document. The contained templates are mapped as described in the following sections, considering them in the order in which they are referenced and taking into account inheritance and multiple containement resolution. Mapped Parameters are placed at the IDL module scope level, so the same Parameter is mapped only once (the first time it is referenced).

Imported templates (those defined in an external GDMO document) are considered as if they were local to the current document for lexical purposes, that is, their GDMO name is considered as if it was only the template label (the document reference is dropped).

Also, the IDL mapping of a GDMO document performs the mapping of all declared Notification templates into the _N and _NP modules, as specified in Mapping Notifications to IDL Operations.

All template REGISTERED AS clauses are mapped into IDL constants within the <nickname>RegId IDL file and module.

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.

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.

  Attribute related parameters are mapped outside the IDL interface in the same module, as described in Mapping Parameters to IDL Types. This applies to all referenced parameters in the attribute template and the ones associated to the attributes when used in the package template. A comment is added inside the interface to describe the parameters related to each attribute.
  

• 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.

  Action related parameters are mapped outside the IDL interface in the same module, as described in Mapping Parameters to IDL Types. This applies to all referenced parameters in the action template and the ones associated to the actions when used in the package template. A comment is added inside the interface to describe the parameters related to each action.

• For each referenced Notification, add a comment indicating this, and copy the behaviour text of the corresponding NOTIFICATION template also as a comment. Notification-related Parameters which have a context type of EVENT-REPLY or SPECIFIC-ERROR are ignored because reply syntaxes for events are not supported. Any Parameters having a context type of EVENT-INFO are mapped in the _N and _NP modules, as well as in the main module, as described in Mapping Parameters to IDL Types. This applies to referenced parameters associated to the notifications when used in the package template (note that parameters referenced from the notification template are mapped with the notification template). A comment is added inside the interface to describe the Parameters related to each notification.

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 Translation of ASN.1 to IDL. 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.

Note:

Additional property-list values have been added to the list associated to each attribute within a package. These are SET-BY-CREATE (added in GDMO Amendment 1) and NO-MODIFY (added in GDMO Amendment 2). For the purpose of GDMO to IDL mapping, both can be ignored as they do not affect the access mechanisms available for a certain attribute.

Mapping Parameters to IDL Types

The mapping generates a new IDL type declaration, where the new type is named after the parameter label and the type is the translation of the WITH SYNTAX or ATTRIBUTE constructs. Behaviour definitions are transcribed as comments, as is the CONTEXT type information.

Examples

Mapping Actions to IDL Operations

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

If the ACTION template uses the "MODE CONFIRMED" clause, only confirmed action invocations may be used.

Mapping to an Operation on the Primary Interface

If the ACTION template uses the "MODE CONFIRMED" clause, it is mapped only to a confirmed method as explained above. Otherwise, an additional method is generated for unconfirmed invocations. Its name is that of the confirmed method with the word Unconfirmed appended. It will be an IDL oneway method without return parameters and with the same arguments as the corresponding confirmed operation.

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 };

This would translate in the primary interface as follows:

 

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. 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.

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 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 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, the any carrying the notification data should contain a value of type X711CMI::EventReportArgumentType. This type is defined as follows:

 

struct EventReportArgumentType {
    ObjectClassType managedObjectClass;
    ObjectInstanceType managedObjectInstance;
    ASN1_GeneralizedTimeOpt eventTime;
    EventTypeIdType eventType;
    ASN1_DefinedAnyOpt eventInfo;  // defined by:eventType
};

The eventInfo field should carry a value of the mapped IDL type translated from the WITH INFORMATION SYNTAX clause of the Notification template, if specified.

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 X711CMI::ASN1_GeneralizedTimeOpt eventTime,
    in X711Not::ObjectInfoType notifInfo);

  oneway void objectCreationUnconfirmed (
    in ASN1_ObjectIdentifier sourceObjectClass, 
    in X711CMI::ObjectInstanceType sourceObjectInstance, 
    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 X711CMI::ASN1_GeneralizedTimeOpt eventTime,
    out X711Not::ObjectInfoType notifInfo); 

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

Mapping Template Registrations to IDL

For each template that has a registration, a constant with the following format will be generated:

 

const ASN1_ObjectIdentifier <mapped-template-label> = \
    <template-registration>;

The format of the template registration value of the constant is the IDL string representation of the registration object identifier for the template, using the dot string notation, as specified in Mapping of Object Identifier.

All template registrations, regardless of whether or not they are referenced, must be mapped in the context of the document where they are declared.

Examples

 

myClass MANAGED OBJECT CLASS
    DERIVED FROM "X.721":top;
    CHARACTERIZED BY 
        myPackage PACKAGE
            ATTRIBUTES myAttr GET;
        REGISTERED AS  { 0 0 1 2 3 4 2}; ;
REGISTERED AS { 0 0 1 2 3 4 1 };

myAttr ATTRIBUTE
    WITH SYNTAX MyMod.MyAttrSyntax;
REGISTERED AS { 0 0 1 2 3 4 3 };

the template registrations would be mapped to:

 

// File: MyDocRegId.idl
module MyDocRegId {
    const ASN1_ObjectIdentifier myClass = "0.0.1.2.3.4.1";
    const ASN1_ObjectIdentifier myPackage = "0.0.1.2.3.4.2";
    const ASN1_ObjectIdentifier myAttr = "0.0.1.2.3.4.3";
};

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

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.