29.1983GPPOpen Service Architecture (OSA) Application Programming Interface (API) - Part 1Release 1999TS

Following is a description of the methodology used for the establishment of stage 3 specification in the scope of 3GPP CN OSA.

5.1 Tools and Languages

The Unified Modelling Language (UML) [14] is used as the means to specify class and state transition diagrams. Additionally, Object Management Group’s (OMG) [15] Interface Definition Language (IDL) is used as the means to programmatically define the interfaces. IDL files are either generated manually from class diagrams or by using a UML tool. In the case IDLs are manually written and/or being corrected manually, correctness has been verified using a CORBA2 (orbos/97-02-25) compliant IDL compiler, e.g. [13].

5.2 Packaging

A hierarchical packaging scheme is used to avoid polluting the global name space. The root is defined as:

org.threegpp.osa

Note that the CORBA module hierarchy defined in the IDLs does not necessrly parallels the logical UML package hierarchy.

5.3 Colours

For clarity, class diagrams follows a certain colour scheme. Blue for application interface packages and yellow for all the others.

5.4 Naming scheme

The following naming scheme is used for both documentation and IDLs.

packages

lowercase.

Using the domain-based naming (For example, org.threegpp.osa)

classes, structures and types. Start with T

TpCapitalizedWithInternalWordsAlsoCapitalized

Exception class:

TpClassNameEndsWithException

Interface. Start with Ip:

IpThisIsAnInterface

constants:

P_UPPER_CASE_WITH_UNDERSCORES_AND_START_WITH_P

methods:

firstWordLowerCaseButInternalWordsCapitalized()

method’s parameters

firstWordLowerCaseButInternalWordsCapitalized

collections (set, array or list types)

TpCollectionEndsWithSet

class/structure members

FirstWordAndInternalWordsCapitalized

Spaces in between words are not allowed.

5.5 Error results

As OMG IDL supports exception handling with high efficiency, OSA methods communicate errors in the form of CORBA exceptions of type TpGeneralException in the IDLs; the CORBA methods themselves always return void. But in the documentation, errors are communicated using a return parameter of type TpGeneralResult.

5.6 References

In the interface specification whenever parameters are to be passed by reference, the “Ref” suffix is appended to their corresponding data type (e.g. IpAnInterfaceRef anInterface), a reference can also be viewed as a logical indirection. Therefore, structured or primitive data type passed as out parameters are references. An interface passed as an in parameter is also a reference but an interface passed as an out parameter is a double indirection (i.e.: RefRef)

In IDL, however, the following rules apply:

– Interfaces are implicitly passed by reference.

– out parameters are also implicitly passed by reference.

This leads to:

– Interface as an in parameter: Passed by Reference.

– Structure or primitive type as an in parameter: Passed by Value.

– Structure or primitive type as an out parameter: Passed by Reference.

– Interface as an out parameter: As reference passed by reference.

To simplify the documentation without adding ambiguities, parameters (interfaces, structures and primitive data types) are used as is when specified as in or out parameters in the IDL. This means that there will be no “Ref” added after the data types of parameters in the IDL.

5.7 Number of out parameters

In order to support mapping to as many languages as possible, there is only 1 out parameter allowed per operation.

5.8 Strings and Collections

For character strings, the String data type is used without regard to the maximum length of the string. In IDL, the data type String is typedefed^[1] from the CORBA primitive string. This CORBA primitive is made up of a length and a variable array of byte.

For homogeneous collections of instances of a particular data type the following naming scheme is used: <datatype>Set. In OMG IDL, this maps to a sequence of the data type. A CORBA sequence is implicitly made of a length and a variable array of elements of the same type.

Example: typedef sequence<TpSessionID> TpSessionIDSet;

Collection types can be implemented (for example, in C++) as a structure containing an integer for the number part, and an array for the data part.

Example: The TpAddressSet data type may be defined in C++ as:

typedef struct {

short number;

TpAddress address [];

} TpAddressSet;

The array "address" is allocated dynamically with the exact number of required TpAddress elements based on "number".

5.9 Prefixes

OSA constants and data types are not defined in the global name space but in the org.threegpp.osa module.

5.10 Naming space across CORBA modules

The following shows the naming space used in this specification.

module org {

module threegpp { // cannot use 3gpp, names need to start with letter

module osa {

// The fully qualified name of the following constant

// is org::threegpp::osa::P_THIS_IS_AN_OSA_GLOBAL_CONST

const long P_THIS_IS_AN_OSA_GLOBAL_CONST= 1999;

// Add other OSA global constants and types here

module framework {

// no scoping required to access P_THIS_IS_AN_OSA_GLOBAL_CONST

const long P_FW_CONST= THIS_IS_AN_OSA_GLOBAL_CONST;

};

module mm {

// scoping required to access P_FW_CONST

const long P_M_CONST= framework::P_FW_CONST;

};

};

};

};