Advanced Middleware IDL Specification ===================================== **Date: 10th October 2015** - Version: `0.3.0 <#>`_ - Latest version: :doc:`latest ` Editors: - `eProsima - The Middleware Experts `_ - `DFKI - German Research Center for Artificial Intelligence `_ - `ZHAW - School of Engineering (ICCLab) `_ Copyright © 2013-2015 by eProsima, DFKI, ZHAW. All Rights Reserved -------------- Abstract -------- Ahe Advanced Middleware GE enables flexible, efficient, scalable, and secure communication between distributed applications and to/between FIWARE GEs. The **Interface Definition Language (IDL)** Specifications allowes to describes the Data Types and Operations supported by a Service. Following is a list of the main features it supports: - **IDL, Dynamic Types & Application Types**: It support the usual schema of IDL compilation to generate support code for the data types. - **IDL Grammar**: An OMG-like grammar for the IDL as in DDS, Thrift, ZeroC ICE, CORBA, etc. - **Types**: Support of simple set of basic types, structs, and various high level types such as lists, sets, and dictionaries (maps). - **Type inheritance, Extensible Types, Versioning**: Advanced data types, extensions, and inheritance, and other advanced features will be supported. - **Annotation Language**: The IDL is extended with an annotation language to add properties to the data types and operations. These will, for example, allows adding security policies and QoS requirements. Status of this Document ----------------------- +-----------------+-----------------------+ | **Date** | **Description** | +=================+=======================+ | 8-April-2015 | Release 0.2.0 | +-----------------+-----------------------+ | 10-October-2015 | Release 0.3.0 | +-----------------+-----------------------+ -------------- Preface ------- The foundation of the FIWARE Middleware Interface Definition Language (IDL) is the Object Management Group (OMG) IDL 3.5. See `Appendix C <#appendix-c-omg-idl-3.5-grammar>`_ for the OMG IDL 3.5 grammar. To maintain backward compatibility, the FIWARE Middleware IDL grammar embraces all OMG IDL 3.5 features. IDL parsers are not required to implement all of the extended OMG features. Check the documentation of the specific parser implementations. The basic subset needed by DDS and future standard RPC over DDS must be supported. Related documentation --------------------- - `OMG DDS-XTypes 1.0 `_ Syntax Definition ----------------- The FIWARE Middleware IDL specification consists of one or more type definitions, constant definitions, exception definitions, or module definitions. Some definitions are allowed in the grammar for backward compatibility, but are not used by the FIWARE Middleware IDL and therefore will be ignored by the implmentations. :: ::= * + ::= ";" | ";" | ";" | ";" | ";" | ";" | ";" | ";" | ";" | ";" | ";" | ";" | | See section `Import Declaration <#import-declaration>`_ for the specification of ```` | See section `Module Declaration <#module-declaration>`_ for the specification of ```` | See section `Interface Declaration <#interface-declaration>`_ for the specification of ```` | See section `Value Declaration <#value-declaration>`_ for the specification of ```` | See section `Constant Declaration <#constant-declaration>`_ for the specification of ```` | See section `Type Declaration <#type-declaration>`_ for the specification of ```` | See section `Exception Declaration <#exception-declaration>`_ for the specification of ```` | See section `Repository Identity Related Declarations <#repository-identity-related-declarations>`_ for the specification of ```` and ```` | See section `Event Declaration <#event-declaration>`_ for the specification of ```` | See section `Component Declaration <#component-declaration>`_ for the specification of ```` | See section `Event Declaration <#event-declaration>`_ for the specification of ```` | See section `Annotation Declaration <#annotation-declaration>`_ for the specification of ```` | See section `Annotation Application <#annotation-application>`_ for the specification of ``< annotation_appl>`` Import Declaration ~~~~~~~~~~~~~~~~~~ An import statement conforms to the following syntax: :: ::= "import" ";" ::= | Import declarations are not supported by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and ignore the declaration. Module Declaration ~~~~~~~~~~~~~~~~~~ A module definition conforms to the following syntax: :: ::= ("module" | "namespace") "{" + "}" The module construct is used to scope IDL identifiers. FIWARE Middleware IDL supports the OMG IDL 3.5 keyword ``module``, but also adds the modern keyword ``namespace`` as an alias. Examples of module definitions: :: namespace MyNamespace { ... }; namespace YourNamespace { namespace HisNamespace { ... }; }; Interface Declaration ~~~~~~~~~~~~~~~~~~~~~ An interface definition conforms to the following syntax: :: ::= | ::= "{" "}" ::= [ "abstract" | "local" ] ("interface" | "service") ::= [ "abstract" | "local" ]("interface" | "service") [ ] ::= * ::= ";" | ";" | ";" | ";" | ";" | ";" | ";" Example of interface definition: :: service MyService { ... }; Interface Header ^^^^^^^^^^^^^^^^ The interface header consists of three elements: 1. An optional modifier specifying if the interface is an abstract interface. 2. The interface name. The name must be preceded by the old OMG IDL 3.5 keyword ``interface`` or the new modern keyword ``service``. 3. An optional inheritance specification. An interface declaration containing the keyword ``abstract`` in its header, declares an abstract interface. Abstract interfaces have slightly different rules from *regular* interfaces, as described in section `Abstract interface <#abstract-interface>`_. An interface declaration containing the keyword ``local`` in its header, declares a local interface. Local interfaces are not currently supported by the FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this, and explain the interface will be used as a *regular* interface. Interface Inheritance Specification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The syntax for interface inheritance is as follows: :: ::= ":" { "," }* ::= ::= | "::" | "::" Each ```` in an ```` must be the name of a previously defined interface or an alias to a previously defined interface. Interface Body ^^^^^^^^^^^^^^ The interface body contains the following kind of declarations: - Constant declarations whose syntax is described in section `Constant Declaration <#constant-declaration>`_. - Type declarations whose syntax is described in section `Type Declaration <#type-declaration>`_. - Exception declarations whose syntax is described in section `Exception Declaration <#exception-declaration>`_. - Attribute declarations whose syntax is described in section `Attribute Declaration <#attribute-declaration>`_. - Operation declarations whose syntax is described in section `Operation Declaration <#operation-declaration>`_. Abstract interface ^^^^^^^^^^^^^^^^^^ An interface declaration contains the keyword ``abstract`` in its header, declares an abstract interface. The following special rule apply to abstract interfaces: - Abstract interfaces may only inherit from other abstract interfaces. Value Declaration ~~~~~~~~~~~~~~~~~ Value type declarations are supported by FIWARE Middleware IDL, but aren't by FIWARE Middleware. Any FIWARE Middleware IDL parser has to explain that these declarations are not used and the parser will ignore them. Constant Declaration ~~~~~~~~~~~~~~~~~~~~ A constant definition conforms to the following syntax: :: ::= "const" "=" ::= | | | | | | | | | ::= ::= | "|" ::= | "^" ::= | "&" ::= | ">>" | "<<" ::= | "+" | "-" ::= | "*" | "/" | "%" ::= | ::= "-" | "+" | "~" ::= | | "(" ")" ::= | | | | | | | ::= "TRUE" | "FALSE" ::= Examples for constant declarations: :: const string c_str = "HelloWorld"; const i32 c_int = 34; const boolean c_bool = true; Type Declaration ~~~~~~~~~~~~~~~~ As in OMG IDL 3.5, FIWARE Middleware IDL provides constructs for naming data types; that is, it provides C language-like declarations that associate an identifier with a type. The IDL uses the keyword ``typedef`` to associate a name with a data type. Type declarations conform to the following syntax: :: ::= "typedef" | | | | "native" | ::= For type declarations, FIWARE Middleware IDL defines a set of type specifiers to represent typed value. The syntax is as follows: :: ::= | ::= | | ::= | | | | | | | | ::= | | | | | ::= | | ::= { "," }* ::= | ::= ::= The ```` in ```` must be a previously defined type introduced by a type declaration(\ ```` - see section `Type Declaration <#type-declaration>`_). The next subsections describe basic and constructed type specifiers. Basic Types ^^^^^^^^^^^ The syntax for the supported basic types is as follows: :: ::= "float" | "double" | "long" "double" | "float32" | "float64" | "float128" ::= | ::= | | ::= "short" | "i16" ::= "long" | "i32" ::= "long" "long" | "i64" ::= | | ::= "unsigned" "short" | "ui16" ::= "unsigned" "long" | "ui32" ::= "unsigned" "long" "long" | "ui64" ::= "char" ::= "wchar" ::= "boolean" ::= "octet" | "byte" ::= "any" Each IDL data type is mapped to a native data type via the appropriate language mapping. The syntax allows to use some OMG IDL 3.5 keywords and to use new modern keyword. For example, FIWARE Middleware IDL supports both keywords: ``long`` and ``i32``. The **any** type is not supported currently by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this. Constructed Types ~~~~~~~~~~~~~~~~~ | Constructed types are **structs**, **unions**, and **enums**. | Their syntax is as follows: :: ::= "typedef" | | | | "native" | ::= | | ::= "struct" | "union" Structures ^^^^^^^^^^ The syntax for the ``struct`` type is as follows: :: ::= "struct" "{" "}" ::= + ::= ";" Example of struct syntax: :: struct MyStruct { i32 f_int; string f_str; boolean f_bool; }; Unions ^^^^^^ The syntax for the ``union`` type is as follows: :: ::= "union" "switch" "(" ")" "{" "}" ::= | | | | ::= + ::= + ";" ::= "case" ":" | "default" ":" ::= The ```` in the ```` production must be a previously defined ``integer``, ``char``, ``boolean`` or ``enum`` type. Example of union syntax: :: union MyUnion switch(i32) { case 1: i32 f_int; case 2: string f_str; default: boolean f_bool; }; Enumerations '''''''''''' | Enumerated types consist of ordered lists of identifiers. | The syntax is as follows: :: ::= "enum" "{" { "," } * "}" ::= Example of an enumerated type: :: enum MyEnum { ENUM1, ENUM2, ENUM3 }; Template Types ^^^^^^^^^^^^^^ Template types are: :: ::= | | | | | Lists ''''' The FIWARE Middleware IDL defined the template type ``list``. A list is similar to the OMG IDL 3.5 ``sequence`` type. It is one-dimensional array with two characteristics: a maximum size (which is fixed at compile time) and a length (which is determined at run time). The syntax is as follows: :: ::= "sequence" "<" "," ">" | "sequence" "<" ">" | "list" "<" "," ">" | "list" "<" ">" Examples of list type declarations: :: list mylist; list myboundedlist; Sets '''' The FIWARE Middleware IDL includes the template type ``set``. At marshalling level it is like the template type ``list``. But at a higher level, contrary to the list type, a set can only contain unique values. The syntax is as follows: :: ::= "set" "<" "," ">" | "set" "<" ">" Examples of set type declarations: :: set myset; set myboundedset; Maps '''' The FIWARE Middleware IDL includes the template type ``map``, using the upcoming definition in OMG IDL 4.0. Maps are a collections, similar to lists, but items are associated with a *key*. Like lists, maps may be bounded or unbounded. The syntax is as follows: :: ::= "map" "<" "," "," ">" | "map" "<" "," ">" Examples of map type declaration: :: map mymap; map myboundedmap; In CDR marshalling, objects of type map shall be represented according to the following equivalent OMG IDL 3.5 definition: :: struct MapEntry__[_] { key; value_type> value; }; typedef sequence_[_][, ]> Map__[_]; Strings ''''''' The syntax for defining a string is as follows: :: ::= "string" "<" ">" | "string" Wstrings '''''''' The syntax for defining a wstring is as follows: :: ::= "wstring" "<" ">" | "wstring" Fixed Type '''''''''' The ``fixed`` data type represents a fixed-point decimal number of up to 31 significant digits. The scale factor is a non-negative integer less than or equal to the total number of digits. The ``fixed`` data type will be mapped to the native fixed point capability of a programming language, if available. If there is not a native fixed point type, then the IDL mapping for that language will provide a fixed point data types. The syntax of the fixed type is as follows: :: ::= "fixed" "<" "," ">" ::= "fixed" Complex Types ^^^^^^^^^^^^^ Arrays '''''' The syntax for array is as follows: :: ::= + ::= "[" "]" Example of array type declarations: :: i32 myi32array[32]; string mystrarray[32]; Native Types ^^^^^^^^^^^^ The syntax for native types is as follows: :: ::= "native" ::= Native types are not supported by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and ignore this definition. Exception Declaration ~~~~~~~~~~~~~~~~~~~~~ Exception declarations permit the declaration of struct-like data structures, which may be returned to indicate that an exceptional condition has occurred during the performance of a request. The syntax is as follows: :: ::= "exception" "{" * "}" Example of an exception declaration: :: exception myException { string msg; i32 code; }; Operation Declaration ~~~~~~~~~~~~~~~~~~~~~ Operation declarations in OMG IDL 3.5 and FIWARE Middleware IDL are similar to C function declarations. The syntax is as follows: :: ::= [ ] [ ] [ ] ::= "oneway" ::= | "void" Example of an operation declaration: :: service myService { void set(i32 param); i32 get(); i32 add(i32 param1, i32 param2) raises (myException); }; An operation declaration consists of: - An optional *operation attribute* that is supported by FIWARE Middleware IDL for backward compatibility. Operation attributes are described in section `Operation attribute <#operation-attribute>`_. - The *type* of the operation's return result. Operations that do not return a result must specify the void type. - An *identifier* that names the operation in the scope of the interface in which it is defined. - A *parameter list* that specifies zero or more parameter declarations for the operation. Parameter declaration is described in section `Parameter Declarations <#parameter-declarations>`_. - An optional *raises expression* that indicates which exception may be raised as a result of an invocation of this operation. Raises expression are described in section `Raises Expressions <#raises-expressions>`_. - An optional *context expression* that is inherited from OMG IDL 3.5, but FIWARE Middleware will not use. Context expressions are described in section `Context Expressions <#context-expressions>`_. Operation attribute ^^^^^^^^^^^^^^^^^^^ The syntax for operation attributes is as follows: :: ::= "oneway" This attribute is supported in FIWARE Middleware for backward compatibility. But in FIWARE Middleware IDL the preferedby way to define a **oneway** function is using the **@Oneway** annotation as described in section `Oneway functions <#oneway-functions>`_. Parameter Declarations ^^^^^^^^^^^^^^^^^^^^^^ Parameter declarations in FIWARE Middleware IDL operation declarations have the following syntax: :: ::= "(" { "," }* ")" | "(" ")" ::= [ ] ::= "in" | "out" | "inout" ::= "raises" "(" { "," }* ")" ::= | | | The FIWARE Middleware IDL will *not* use output parameters, as modern IDLs do. It supports the keywords ``in``, ``inout``, and ``out``, but any FIWARE Middleware IDL parser will inform users all parameters will be input parameters. Raises Expressions ^^^^^^^^^^^^^^^^^^ There are two kinds of raises expressions. Raises Expression ''''''''''''''''' A raises expression specifies which exceptions may be raised as a result of an invocation of the operation or accessing a readonly attribute. The syntax for its specification is as follows: :: ::= "raises" "(" { "," }* ")" The ````\ s in the raises expression must be previously defined exceptions. getraises and setraises Expression '''''''''''''''''''''''''''''''''' The syntax is as follows: :: ::= [ ] | ::= "getraises" ::= "setraises" ::= "(" { "," }* ")" ``getraises`` and ``setraises`` expressions are used in attribute declarations. Like in attribute declarations, theses expressions are supported by FIWARE Middleware IDL but not by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and it will ignore these expressions. Context Expressions ^^^^^^^^^^^^^^^^^^^ The syntax for content expressions is as follows: :: ::= "context" "(" { "," }* ")" Context expressions are supported by FIWARE Middleware IDL but not by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and it will ignore these expressions. Attribute Declaration ~~~~~~~~~~~~~~~~~~~~~ The syntax for attribute declarations is as follows: :: ::= | ::= "readonly" "attribute" ::= | { "," }* ::= "attribute" ::= | { "," }* These declarations are supported by FIWARE Middleware IDL but not by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and it will ignore these declarations. Repository Identity Related Declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The syntax for repository identity related declarations is as follows: :: ::= "typeid" ::= "typeprefix"