Fractal | Fractal ADL | Cecilia Examples | Minus
 

Overview

The Cecilia IDL Language is a way to define interfaces in Cecilia, because the C programming language does not support natively the interface construct.

This IDL is strongly typed. In fact interface descriptions are used by the compilation tool-chain to make type based analysis to verify the compatibility of interconnected component interfaces, and to generate communication adaptors for component pairs that can not be naturally bound (JNI, RPC, etc.).

Basic Example

Cecilia IDL supports four types of constructs:

  • Interface defines the signature of a component interface. An interface contains a set of methods. Each method must have a distinct name. Optionally, an interface can extends another interface (multiple inheritance is not allowed). Finally, an interface may define constants;
  • Record defines a structured type. It contains a set of fields. Each field has a type and a name. Records are used to define component attributes and can also be used as method parameter or return types.
  • Enum (since Cecilia 1.2) defines an enumerated type. It contains a set of members. Each field has a name and optionally a value. Enums can be used as interfaces method parameter types and also as method return types.
  • Union (since Cecilia 2.0) defines a union type. It contains a set of fields. Each field has a type and a name. Unions can be used as method parameter or return types.

Each construct definition must be done in a separate file. The extension used for these files is .idl. The file name must correspond to the construct name which is defined in the file, and each IDL definition belongs to a package. The package name must correspond to the path in the file system.

An IDL definition can reference a type which is defined in another IDL definition. To this end, two kinds of identifiers may be used, a simple identifier or a qualified identifier. A qualified identifier corresponds to <package>.<interface> giving the absolute description of the IDL definition. An identifier corresponds only to <interface>, and may be considered as a relative path. An single identifier can be used to reference an IDL type which is defined in the same package. Otherwise, one may import the qualified identifier to use then an identifier in the IDL definition. Note that the imported identifiers overload the identifiers found in the same package.

The following IDL definition specifies an interface, called Printer, in the package video.api, which provides two distinct methods, one providing a print operation for a character, and the other for a string.

// file = video/api/Printer.idl
package video.api;

public interface Printer {
    void printChar(char c);
    void printString(string s);
}

The following IDL definition defines a record called ServiceAttributes in the package attributes which has two integer fields respectively called cols and rows.

// file = service/ServiceAttributes.idl
package attributes;

record ServiceAttributes {
    int cols;
    int rows;
}

The following IDL definition defines a DayOfTheWeek enumerated type in the package days, which has 7 members, named after the days of the week.

// file = days/DayOfTheWeek.idl
package days;

enum DayOfTheWeek {
    MONDAY,
    TUESDAY,
    WEDNESDAY,
    THURSDAY,
    FRIDAY,
    SATURDAY,
    SUNDAY
}

The following IDL definition defines a Handle union type in the package system, which has an integer field and a pointer field.

// file = system/Handle.idl
package system;

enum Handle {
    uint32_t handle;
    any ptr;
}

Cecilia IDL Grammar Specification

Common grammar elements

The very first element of the IDL language consists in the identifiers. As explained above, two kinds of identifiers are supported : qualified identifier and the simple identifier. The simple identifier corresponds to a string corresponding to a classical C identifier (starting with an alphabetical character and not containing arithmetical or boolean operator characters). A qualified identifier is a list of identifiers, connected with points.

QualifiedIdentifier ::=  (Identifier ( "." Identifier)* )

An IDL declaration starts with a package clause, followed by a list of import clauses, and contain one interface definition or one record definition or one enumeration definition.

Declaration ::= Package (Import)* (InterfaceDeclaration | RecordDeclaration | EnumDeclaration | UnionDeclaration)
Package     ::= "package" QualifiedIdentifier;
Import      ::= "import " QualifiedIdentifier;  

Another common element is the supported types. We distinguish between primitive types corresponding to keywords defined in the IDL language, and the complex types that are defined in other IDL definitions.

Type           ::= PrimitiveType | ComplexType
ComplexType   ::= QualifiedIdentifier | "any"
PrimitiveType  ::= (
 "boolean"                     |
 "char"                        |
 "byte"                        |
 "short"                       |
 "int"                         |
 "long"                        |
 "unsigned byte"               |
 "unsigned short"              |
 "unsigned int"                |
 "unsigned long"               |
 "float"                       |
 "double"                      |
 "(u?)int(8|16|32|64)_t"       |
 "(u?)int_least(8|16|32|64)_t" |
 "(u?)int_fast(8|16|32|64)_t"  |
 "(u?)intptr_t"                |
 "(u?)intmax_t"                |
 "size_t"                      |
 "ptrdiff_t"                   |
 "wchar_t"                     |
 "string"  ) 

Primitive and complex types are mapped to the C types as described in the Cecilia IDL to C page.

Interface definition grammar

An interface type declaration identified by Identifier contains two sorts of declarations: methods and constant fields. The keyword "public" isn't relevant and is only here for compatibility purpose.

InterfaceDeclaration  ::=  "public"? "interface" Identifier "{"
    ( 
    MethodDeclaration  |
    FieldDeclaration   |
    ";" 
    )*   
"}" 

The grammar of a method declaration is given below. The keyword "..." is used for passing arbitrary parameters number. The optional "in", "out", "in out" (default to "in") specify parameter passing modes, and allow the IDL compiler to map the operations to the target programming language, accordingly to the language capabilities. See the IDL to C Mapping page for a practical description of the mapping procedure from Cecilia IDL to C.

MethodDeclaration  ::=  ResultType Identifier FormalParameters ";"
ResultType         ::=  Type | "void"
FormalParameters   ::=  
    "("
      FormalParameter 
      ( "," FormalParameter )*
      ( "," "..." )? 
    ")" 
FormalParameter    ::=  ("in" | "out" | "in out")? Type Identifier              

A constant field declaration grammar looks like this. The expression must be a valid constant expression and only a primitive type can be assigned as a constant. No semantic check on the expression is done by the IDL compiler.

FieldDeclaration  ::=  PrimitiveType Identifier "=" Expression ("," Identifier "=" Expression)* ";"                     

Record definition grammar

The grammar of the record definition is given below. A record can contain any type.

RecordDeclaration      ::=  "record" Identifier "{
    (BasicFieldDeclaration)* 
"}"
BasicFieldDeclaration  ::=  Type Identifier ("," Identifier)* ";"

Enum definition grammar

The grammar of the enum definition is given below. A enum must contain one or more members, each of them can optionally specify a value. Note that for enum definitions import statements have no meaning.

EnumDeclaration      ::=  "enum" Identifier "{
    (EnumMemberDeclaration)
    ( "," EnumMemberDeclaration )*
"}"
EnumMemberDeclaration  ::=  Identifier (":" Expression)?

Union definition grammar

The grammar of the union definition is given below. An union can contain any type.

UnionDeclaration      ::=  "union" Identifier "{
    (BasicFieldDeclaration)* 
"}"
BasicFieldDeclaration  ::=  Type Identifier ("," Identifier)* ";"
 
2007-2009 © ObjectWeb Consortium  | Last Published: 2009-04-21 13:35  | Version: 2.1.0