B.2 Guidelines (Style Guide for CORBA SS IDL)

32.1533GPPIntegration Reference Point (IRP) technology specific templates, rules and guidelinesRelease 17Telecommunication managementTS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

This subclause describes the style guide for writing IDL statements for Interface IRP and NRM IRP. The guidelines are largely based on the OMG IDL Style Guide (OMG document: ab/98-06-03) [9] with extensions for IRP use.

The guide sets out consistent naming, structural conventions and usage of SS interface for the IDL in IRP CORBA SS specifications.

B.2.1 Modules and File

B.2.1.1 Use of Modules

All declarations of IDL shall be contained in modules. No declarations of interfaces and definitions shall appear in the global scope.

Nesting modules is a useful technique when dealing with large namespaces to avoid name clashes and clarify relationships. A module nested within another module shall not have the same name as a top-level module in any other IRP CORBA SS specification.

B.2.1.2 File Names

CORBA SS specifications contain IDL statements.

The rule defined below specifies:

How to partition/extract these IDL statements to be placed in a file; and
How to name the file.

Note that IDL uses "#include "X"" statement where X is a name of a file containing IDL statements.

Rule:

In the annex where IDL statements are defined, use a special marker to indicate that a set of IDL statements shall be contained in one file. The name of the file shall be the name of the first IDL module, concatenated with four characters ".idl". Within a CORBA SS, multiple markers (implying multiple files), can be used.

It is not allowed to have an IDL module split into multiple files.

B.2.1.3 Include Conventions

All included IDL files shall be specified using the <…> form of #include. For example:

#include <ManagedGenericIRPConstDefs.idl>

B.2.1.4 File Structure

B.2.1.4.1 File Internal Identification

The first line of the IDL file shall contain "//File:" followed by a single space followed by the name of the file.
For example,

//File: ExampleIRPConstDefs.idl

B.2.1.4.2 File Guard

An IDL file shall use a guard (consisting of three pre-processor lines) to avoid multiple definition errors. An example of a guard for the file called TestManagementIRPConstDefs.idl is:

#ifndef _TestManagementIRPConstDefs_idl_

#define _TestManagementIRPConstDefs_idl_

…remainder of the IDL

#endif // _TestManagementIRPConstDefs_idl_

B.2.1.4.3 Required Contents

If any other files are to be included, the #include statements come after the guard.

After #include lines, if any, and immediately before the module statement, the following line shall appear:

#pragma prefix "3gppsa5.org"

B.2.1.4.4 Example illustrating a File Structure

//File: ExampleIRPConstDefs.idl

#ifndef _EXAMPLE_IRP_CONST_DEFS_IDL_

#define _EXAMPLE_IRP_CONST_DEFS_IDL_

// This module describes/is part of…

#include "ExampleIncludeOne.idl"

#include "ExampleIncludeTwo.idl"

#pragma prefix "3gppsa5.org"

module ExampleIRPConstDefs {

// IDL Definitions here

};

#endif // _EXAMPLE_IRP_CONST_DEFS_IDL_

B.2.2 Identifiers

B.2.2.1 Mixed Case, Beginning Upper, No Underscores

The following categories of identifiers follow the Mixed Case, Beginning Upper, No Underscores rules:

– module

– interface

– typedef

– Constructed types (struct, union, enum)

– exception

The "No underscores" rule is also applicable to all words that begin with an upper case letter with the remaining letters being lower case.

As a further note on naming, it is not necessary to append the value "Type" to an identifier. The fact that it is a type is obvious from the consistent application of this naming convention.

Examples:

module PMIRPConstDefs(…);

interface AttributeNameValue(…);

B.2.2.2 Lower Case with Underscores

The following categories of identifiers follow the Lower Case with Underscores rules. All letters are lower case and words (if more than one) are separated with underscores.

– Operation name and notification name

– Attribute name

– Parameter name

– Structure member name

Examples:

get_notification_categories(…);

string comment_text;

void get_alarm_count (…, out unsigned long critical_count,..);

struct Comment {…; string user_id; string system_id;..};

B.2.2.3 Upper Case with Underscores

The following categories of identifiers follow Upper Case with Underscores rules. All letters are in upper case and words have an underscore separating them.

– Enum value

– Constant

Examples:

enum SubscriptionState {ACTIVE, SUSPENDED, INVALID};

const string JOB_ID = "JOB_ID";

B.2.2.4 Naming IDL Sequence Types

Typically a new type declared as an IDL sequence of another type will have the text "List" appended to the name of the base type. Another convention is to declare such types as unordered sequences or ordered sets for consistency with ASN.1 notation. In this case they should have the "Seq" or "Set" (instead of "List") appended respectively.

Example of an "ordered set":

typedef sequence <SubscriptionId> SubscriptionIdSet;

B.2.3 Interface IRP

Every Interface IRP should have 3 IDL modules (each specified in a separate IDL file):

module YyyIRPConstDefs {…}; // no change from Rel-5 practice.

module YyyIRPSystem {…}; // no change from Rel-5 practice.

module YyyIRPNotifications {…}; // new compared to Rel-5 practice

The first module defines all necessary IDL constructs, such as constant strings and type definitions, for the methods and notifications. The second module defines the methods. The third module defines the notifications.

B.2.3.1 Constant String and Type Definitions

This first module defines all necessary IDL constructs used by the methods (defined in the second module) and notifications (defined in the third module). The name of this module is YyyIRPConstDefs where Xxx is the name of the subject Interface IRP. An example is "PMIRPConstDefs".

Within this module, define data types used in the methods.

Also, define the data types of the attribute values used in the notifications.

CORBA SS authors should always check the generic types defined in "ManagedGenericIRPConstDefs" before creating a new type.

For the attribute names of the structured notifications, define an interface AttributeNameValue that captures the string definitions. Make sure these definitions do not clash with those defined for the notification header, i.e. notification id, event time, system DN, managed object class and managed object instance (see NotificationIRPNotification::Notify).

An example from PMIRPConstDefs:

/**

* This block identifies attributes which are included as part of the

* PMIRP. These attribute values should not

* clash with those defined for the attributes of notification

* header (see IDL of Notification IRP).

interface AttributeNameValue

{

const string JOB_ID = "JOB_ID";

const string JOB_STATUS = "JOB_STATUS";

const string REASON = "REASON";

const string MONITOR_ID = "MONITOR_ID";

const string MONITOR_STATUS = "MONITOR_STATUS";

};

B.2.3.2 Operations

The second module defines the methods. The name of the module is YyyIRPSystem where Yyy is the name of the subject Interface IRP. An example is AlarmIRPSystem.

At the beginning of this module, define all required exceptions. Naming conventions for exception are covered in B.2.2.1 above. CORBA SS authors should always check if the generic exceptions defined in the ManagedGenericIRPSystem can be reused before declaring new exception types.

Then define one interface called YyyIRP encapsulating all methods of the subject Yyy Interface IRP. If the subject Interface IRP IS specifies that its YyyIRP inherits from XxxIRP, then reflect the inheritance relation in the interface definition. The following is an example of AlarmIRP that inherits from ManagedGenericIRP.

module AlarmIRPSystem

{

…

interface AlarmIRP : ManagedGenericIRPSystem:: ManagedGenericIRP {…};

…

};

Naming conventions for operations are covered in B.2.2.2 above.

B.2.3.3 Notifications

Use a separate module to define the notifications. The name the module is YyyIRPNotifications where Yyy is the name of the subject Interface IRP. Examples are KernelCMIRPNotifications and PMIRPNotifications.

For NotificationIRPNotifications, do:

– Define one IDL interface Notify. Capture the four constant strings that are the names of the four NV (name value) pairs of filterable_body_field of the CORBA structured event. These four CORBA NV pairs are mapped from the five notification header attributes (defined by the Notification IRP IS), i.e. the objectClass, objectInstance, notificationId, eventTime and systemDN.

For YyyIRPNotifications where Yyy is not Notification, do:

– At the beginning of this module, define the const strings for the notification types that correspond to the set of notifications specified by (and not inherited by and not imported by) the subject Interface IRP.

– Then define a number of IDL interfaces corresponding to notifications specified in the subject Interface IRP. These interfaces should inherit from NotificationIRPNotifications::Notify. Within each interface, the first IDL statement defines the notification type (that is used as the second field of the fixed header of the structured notification). The second and subsequent IDL statements define the attribute names of this notification type, excepting those already defined by NotificationIRPNotifications::Notify. The data type of the attribute value, which is defined in YyyIRPConstDefs, should be mentioned in the comment block of this IDL statement.

– Then define a number of IDL interfaces corresponding to notifications imported, if any. These interfaces should inherit from the imported interface. An example is interface NotifyObjectCreation : KernelCMIRPNotifications:: NotifyObjectCreation. Within this interface, define all necessary IDL constructs, if any, which are not defined in the imported interface. This interface may contain no IDL statement if the IDL constructs defined in the imported interface are sufficient. For each interface imported, insert a comment "The first field of this notification carries the IRPVersion of this CORBA SS."

– There is no need to re-define interfaces for notifications that are already specified in other Interface IRP, and from which the subject IRP inherits.

The following is an extract from PMIRPNotifications.

module PMIRPNotifications

{

const string ET_MEASUREMENT_JOB_STATUS_CHANGED = "notifyMeasurementJobStatusChanged";

const string ET_THRESHOLD_MONITOR_STATUS_CHANGED = "notifyThresholdMonitorStatusChanged";

interface NotifyMeasurementJobStatusChanged: NotificationIRPNotifications::Notify

{

const string EVENT_TYPE = ET_MEASUREMENT_JOB_STATUS_CHANGED;

/**

* This constant defines the name of the jobId property,

* which is transported in the filterable_body fields.

* The data type for the value of this property

* is PMIRPConstDefs::JobIdType.

const string JOB_ID = PMIRPConstDefs::AttributeNameValue::JOB_ID;

…

};

interface NotifyXXX : NotificationIRPNotifications::Notify

{

…

};

…

};

B.2.4 NRM IRP

Use one module to define the IDL constructs for the managed object classes. The name of this module is XxxNRIRPConstDefs where Xxx is the name of the subject NRM IRP.

An example is UtranNRIRPConstDefs.

Within the module, define a set of IDL interfaces each of which corresponds to a managed object class specified. The interface definition respects the inheritance relation specified.

After the interface definition, the type definition for each attribute defined for the managed object class is defined (including inherited attributes). The type is defined in one of two ways:

1) With a typedef of the type that matches the attribute definition in the NRM Information Object Class (IOC) mapping table, or

2) With a CORBA IDL comment if the same attribute name is already defined in managed object classes already defined in this NRM.

An example of managed object class RncFunction, which inherits from GenericNRIRPConstDefs::ManagedFunction, is shown below.

module UtranNRIRPConstDefs

{

…

/**

* Definitions for MO class RncFunction

interface RncFunction : GenericNRIRPConstDefs::ManagedFunction

{

const string CLASS = "RncFunction";

// Attribute Names

const string rncFunctionId = "rncFunctionId";

const string mcc= "mcc";

const string mnc= "mnc";

const string rncId= "rncId";

};

typedef string rncFunctionId;

typedef long mcc;

typedef long mnc;

typedef long rncId;

// userLabel

…

};

Annex C (normative):
Technology specific rules & guidelines for SOAP SSs