5 Methodology
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)
|
Original Data type |
IN parameter declaration |
OUT parameter declaration |
|
TpPrimitive |
parm : IN TpPrimitive |
parm : OUT TpPrimitiveRef |
|
TpStructured |
parm : IN TpStructured |
parm : OUT TpStructuredRef |
|
IpInterface |
parm : IN IpInterfaceRef |
parm : OUT IpInterfaceRefRef |
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;
};
};
};
};