\documentclass{article} \usepackage{hyperlatex} \texonly{\textheight 9in} \texonly{\topmargin -0.5in} \newcommand{\HlxIcons}{} \htmltitle{Introduction to CORBA IDL} \htmladdress{~} \htmlattributes{BODY}{BGCOLOR="#ffffe6"} \setcounter{htmlautomenu}{2} \htmlonly{\setcounter{secnumdepth}{0}} %\setcounter{htmldepth}{0} \newcommand{\hdrii}[1]{\subsection*{#1}} \newcommand{\hdriii}[1]{\subsubsection*{#1}} \title{Introduction to CORBA IDL} \author{Based on Ch 4 of Orbix Programmer's Guide} \date{January 22, 1999} \begin{document} \maketitle \hdrii{IDL Modules and Scoping} An IDL module defines a naming scope for a set of IDL definitions. Modules allow you to group interface and other IDL type definitions in logical name spaces. When writing IDL definitions, always use modules to avoid possible name clashes. The following example illustrates the use of modules in IDL: \begin{verbatim} module Finance { interface Account { ... }; }; \end{verbatim} \begin{itemize} \item The interface \verb|Account| is scoped within the module \verb|Finance|. \item IDL definitions are available directly within the scope in which you define them. \item In other naming scopes, you must use the scoping operator (\verb|::|) to access these definitions. For example, the fully scoped name of interface \verb|Account| is \verb|Finance::Account| \item IDL modules can be \emph{reopened}. For example, a module declaration can appear several times in a single IDL specification if each declaration contains different data types. In most IDL specifications, this feature of modules is not required. \end{itemize} \hdrii{Defining IDL Interfaces} An IDL interface describes the functions that an object supports in a distributed application. Interface definitions provide all of the information that clients need to access the object across a network. Consider the example of an interface that describes objects which implement bank accounts in a distributed application. \begin{verbatim} module Finance { interface Account { // The account owner and balance. readonly attribute string owner; readonly attribute float balance; // Operations available on the account. void makeDeposit(in float amount, out float newBalance); void makeWithdrawal(in float amount, out float newBalance); }; }; \end{verbatim} The definition of interface \verb|Account| includes both attributes and operations. These are the main elements of any IDL interface definition. \hdriii{Attributes in IDL Interface Definitions} \begin{itemize} \item Conceptually, attributes correspond to variables that an object implements. \item Attributes indicate that these variables are available in an object and that clients can read or write their values. \item In general, attributes map to a pair of functions in the programming language used to implement the object. These functions allow client applications to read or write the attribute values. \item However, if an attribute is preceded by the keyword \verb|readonly|, then clients can only read the attribute value. For example, the \verb|Account| interface defines the attributes \verb|balance| and \verb|owner|. These attributes represent information about the account which the object implementation can set, but which client applications can only read. \end{itemize} \hdriii{Operations in IDL Interface Definitions} \begin{itemize} \item IDL operations define the format of functions, methods, or operations that clients use to access the functionality of an object. \item An IDL operation can take parameters and return a value, using any of the available IDL data types. \item For example, the \verb|Account| interface defines the operations \verb|makeDeposit| and \verb|makeWithdrawal| as follows: \begin{verbatim} module Finance { interface Account { // Operations available on the account. void makeDeposit(in float amount, out float newBalance); void makeWithdrawal(in float amount, out float newBalance); ... }; }; \end{verbatim} \item Each parameter definition must specify the direction in which the parameter value is passed. The possible parameter passing modes are as follows: \begin{center} \begin{tabular}{rl} \verb|in| & The parameter is passed from the caller\\ & of the operation to the object. \\ \verb|out| & The parameter is passed from the object to the caller. \\ \verb|inout| & The parameter is passed in both directions. \\ \end{tabular} \end{center} \end{itemize} \hdrii{Raising Exceptions in IDL Operations} IDL operations can raise exceptions to indicate the occurrence of an error. \begin{itemize} \item CORBA defines two types of exceptions: \begin{itemize} \item \emph{System exceptions} are a set of standard exceptions defined by CORBA. \item \emph{User­defined exceptions} are exceptions that you define in your IDL specification. \end{itemize} \item Implicitly, all IDL operations can raise any of the CORBA system exceptions. \item No reference to system exceptions appears in an IDL specification. \item To specify that an operation can raise a user-defined exception, first define the exception structure and then add an IDL \verb|raises| clause to the operation definition. For example, the operation \verb|makeWithdrawal| in interface \verb|Account| could raise an exception to indicate that the withdrawal has failed, as follows: \begin{verbatim} module Finance { interface Account { exception WithdrawalFailure { string reason; }; void makeWithdrawal(in float amount, out float newBalance) raises(WithdrawalFailure); ... }; }; \end{verbatim} \item An IDL exception is a data structure that contains member fields. In the above example, the exception \verb|WithdrawalFailure| includes a single member of type \verb|string|. \item The \verb|raises| clause follows the definition of operation \verb|makeWithdrawal| to indicate that this operation can raise exception \verb|WithdrawalFailure|. \item If an operation can raise more then one type of user-defined exception, then include each exception identifier in the \verb|raises| clause and separate the identifiers using commas. \end{itemize} \hdrii{Invocation Semantics for IDL Operations} \begin{itemize} \item By default, IDL operations calls are \emph{synchronous}; that is, a client calls an operation and blocks until the object has processed the operation call and returned a value. \item The IDL keyword \verb|oneway| allows you to modify these invocation semantics. \item If you precede an operation definition with the keyword \verb|oneway|, a client that calls the operation will not block while the object processes the call.\footnote{Actually, the CORBA standard doesn't guarantee that it won't block.} For example, you could add a oneway operation to interface \verb|Account| that sends a notice to an \verb|Account| object, as follows: \begin{verbatim} module Finance { interface Account { oneway void notice(in string text); ... }; }; \end{verbatim} \item Orbix does not guarantee that a oneway operation call will succeed; so if a oneway operation fails, a client may never know. \item There is only one circumstance in which Orbix indicates failure of a oneway operation. If a oneway operation call fails before Orbix transmits the call from the client address space, then Orbix raises a system exception. \item A oneway operation cannot have any \verb|out| or \verb|inout| parameters and cannot return a value. \item Nor can a oneway operation have an associated \verb|raises| clause. \end{itemize} \hdrii{Inheritance of IDL Interfaces} IDL supports inheritance of interfaces. An IDL interface can inherit all the elements of one or more other interfaces. For example, the following IDL definition illustrates two interfaces, called \verb|CheckingAccount| and \verb|SavingsAccount|, that inherit from interface \verb|Account|: \begin{verbatim} module Finance { interface Account { ... }; interface CheckingAccount : Account { readonly attribute overdraftLimit; boolean orderChequeBook (); }; interface SavingsAccount : Account { float calculateInterest (); }; }; \end{verbatim} \begin{itemize} \item Interfaces \verb|CheckingAccount| and \verb|SavingsAccount| implicitly include all elements of interface \verb|Account|. \item An object that implements \verb|CheckingAccount| can accept invocations on any of the attributes and operations of this interface, and on any of the elements of interface \verb|Account.| \item However, a \verb|CheckingAccount| object may provide different implementations of the elements of interface Account to an object that implements \verb|Account| only. \item The following IDL definition shows how to define an interface that inherits both \verb|CheckingAccount| and \verb|SavingsAccount|: \begin{verbatim} module Finance { interface Account { ... }; interface CheckingAccount : Account { ... }; interface SavingsAccount : Account { ... }; interface PremiumAccount : CheckingAccount, SavingsAccount { }; }; \end{verbatim} Interface \verb|PremiumAccount| is an example of \emph{multiple inheritance} in IDL. \item An interface \emph{can} inherit from two interfaces that include a \emph{constant}, \emph{type}, or \emph{exception} definition of the same name. But then you must fully scope that name when using that constant, type, or exception. \item An interface \emph{cannot} inherit from two interfaces that include \emph{operations} or \emph{attributes} that have the same name. \end{itemize} \hdrii{The Object Interface Type} \begin{itemize} \item IDL includes the pre-defined interface \verb|Object|, which all user-defined interfaces inherit implicitly. \item The operations defined in this interface are described in the Orbix Reference Guide. \item While interface \verb|Object| is never defined explicitly in your IDL specification, the operations of this interface are available through all your interface types. \item In addition, you can use \verb|Object| as an attribute or operation parameter type to indicate that the attribute or operation accepts any interface type: \begin{verbatim} interface ObjectLocator { void getAnyObject(out Object obj); }; \end{verbatim} \item It is not legal IDL syntax to inherit interface \verb|Object| explicitly. \end{itemize} \hdrii{Forward Declaration of IDL Interfaces} \begin{itemize} \item In an IDL definition, you must declare an IDL interface before you reference it. \item A \verb|forward| declaration declares the name of an interface without defining it. \item This feature of IDL allows you to define interfaces that mutually reference each other. For example, IDL interface \verb|Account| could include an attribute of IDL interface type \verb|Bank,| to indicate that \verb|Account| stores a reference to a \verb|Bank| object. If the definition of interface \verb|Bank| follows the definition of interface \verb|Account|, you would forward declare \verb|Bank| as follows: \begin{verbatim} module Finance { // Forward declaration of Bank. interface Bank; interface Account { readonly attribute Bank branch; ... }; // Full definition of Bank. interface Bank { ... }; }; \end{verbatim} \item The syntax for a \verb|forward| declaration is the keyword \verb|interface| followed by the interface identifier. \end{itemize} \hdrii{Overview of the IDL Data Types} \begin{itemize} \item In addition to IDL module, interface, and exception types, there three general categories of data type in IDL: \begin{itemize} \item Basic types \item Complex types \item Pseudo object types \end{itemize} \item We examine each category of IDL types in turn and also describe how you can define new data type name constants in IDL. \end{itemize} \hdriii{IDL Basic Types} The basic types supported in IDL are \begin{tabular}{|l|l|} \hline {\bf IDL Type} & {\bf Range of Values} \\ \hline \hline short & $­2^{15} \ldots\ 2^{15} - 1$ (16­bit) \\ \hline unsigned short & $0\ldots\ 2^{16} - 1$ (16­bit) \\ \hline long & $-2^{31} \ldots\ 2^{31} - 1$ (32­bit) \\ \hline unsigned long & $0 \ldots\ 2^{32} - 1$ (32­bit) \\ \hline float & IEEE single-precision floating point numbers. \\ \hline double & IEEE double-precision floating point numbers. \\ \hline char & An 8-bit value. \\ \hline boolean & TRUE or FALSE. \\ \hline octet & An 8-bit value that is guaranteed not to undergo\\ & any conversion during transmission.\\ \hline any & The any type allows the specification of values\\ & that can express an arbitrary IDL type. \\ \hline \end{tabular} The \verb|any| data type allows you to specify that an attribute value, an operation parameter, or an operation return value can contain an arbitrary type of value to be determined at runtime. \hdriii{IDL Complex Types} The IDL \emph{complex types} are data types enum, struct, union, string, sequence, and array. \paragraph{Enum} An \emph{enumerated} type allows you to assign identifiers to the members of a set of values, for example: \begin{verbatim} module Finance { enum Currency {pound, dollar, yen, franc}; interface Account { readonly attribute float balance; readonly attribute Currency balanceCurrency; ... }; }; \end{verbatim} In this example, attribute \verb|balanceCurrency| in interface \verb|Account| can take any one of the values \verb|pound|, \verb|dollar|, \verb|yen|, or \verb|franc|. \paragraph{Struct} A \emph{struct} data type allows you to package a set of named members of various types, for example: \begin{verbatim} module Finance { struct CustomerDetails { string name; short age; }; interface Bank { CustomerDetails getCustomerDetails(in string name); ... }; }; \end{verbatim} In this example, the struct \verb|CustomerDetails| has two members. The operation \verb|getCustomerDetails| returns a struct of type \verb|CustomerDetails| that includes values for the customer name and age. \paragraph{Union} A \emph{union} data type allows you to define a structure that can contain only one of several alternative members at any given time. A union saves space in memory, as the amount of storage required for a union is the amount necessary to store its largest member. All IDL unions are discriminated. A discriminated union associates a label value with each member. The value of the label indicates which member of the union currently stores a value. For example, consider the following IDL union definition: \begin{verbatim} struct DateStructure { short Day; short Month; short Year; }; union Date switch (short) { case 1: string stringFormat;; case 2: long digitalFormat; default: DateStructure structFormat; }; \end{verbatim} The union type \verb|Date| is discriminated by a short value. For example, if this short value is 1, then the union member \verb|stringFormat| stores a date value as an IDL \verb|string|. The default label associated with the member \verb|structFormat| indicates that if the short value is not 1 or 2, then the \verb|structFormat| member stores a date value as an IDL struct. Note that the type specified in parentheses after the \verb|switch| keyword must be an integer, char, boolean or enum type and the value of each case label must be compatible with this type. \paragraph{String} An IDL \verb|string| represents a character string, where each character can take any value of the char basic type. If the maximum length of an IDL string is specified in the string declaration, then the string is bounded. Otherwise the string is unbounded. The following example shows how to declare bounded and unbounded strings: \begin{verbatim} module Finance { interface Bank { // A bounded string with maximum length 10. attribute string sortCode<10>; // An unbounded string. attribute string address; ... }; }; \end{verbatim} \hdriii{Sequence} In IDL, you can declare a \emph{sequence} of any IDL data type. An IDL sequence is similar to a one-dimensional array of elements, but it does not have a fixed length. If the sequence has a fixed maximum length, then the sequence is bounded. Otherwise, the sequence is unbounded. For example, the following code shows how to declare bounded and unbounded sequences as members of an IDL struct: \begin{verbatim} module Finance { interface Account { ... }; struct LimitedAccounts { string bankSortCode<10>; // Maximum length of sequence is 50. sequence accounts; }; struct UnlimitedAccounts { string bankSortCode<10>; // No maximum length of sequence. sequence accounts; }; }; \end{verbatim} A sequence must be named by an IDL \verb|typedef| declaration (to be described) before it can be used as the type of an IDL attribute or operation parameter. The following code illustrates this: \begin{verbatim} module Finance { typedef sequence CustomerSeq; interface Bank { void getCustomerList(out CustomerSeq names); ... }; }; \end{verbatim} \hdriii{Arrays} In IDL, you can declare an array of any IDL data type. IDL arrays can be multi-dimensional and always have a fixed size. For example, you can define an IDL struct with an array member as follows: \begin{verbatim} module Finance { interface Account { ... }; struct CustomerAccountInfo { string name; Account accounts[3]; }; interface Bank { getCustomerAccountInfo (in string name, out CustomerAccountInfo accounts); ... }; }; \end{verbatim} In this example, struct \verb|CustomerAccountInfo| provides access to an array of \verb|Account| objects for a bank customer, where each customer can have a maximum of three accounts. An array must be named by an IDL \verb|typedef| declaration before it can be used as the type of an IDL attribute or operation parameter. The IDL typedef declaration allows you define an alias for a data type, as described in ``Defining Data Type Names and Constants'' on page 61. The following code illustrates this: \begin{verbatim} module Finance { interface Account { ... }; typedef Account AccountArray[100]; interface Bank { readonly attribute AccountArray accounts; ... }; }; \end{verbatim} Note that an array is a less flexible data type than an IDL sequence, because an array always has a fixed length. An IDL sequence always has a variable length, although it may have an associated maximum length value. \hdrii{IDL Pseudo Object Types} CORBA defines a set of pseudo object types that ORB implementations use when mapping IDL to some programming languages. These object types have interfaces defined in IDL but do not have to follow the normal IDL mapping for interfaces and are not generally available in your IDL specifications. You can use only the following pseudo object types as attribute or operation parameter types in an IDL specification: \begin{verbatim} NamedValue Principal TypeCode \end{verbatim} To use any of these three types in an IDL specification, include the file \verb|orb.idl| in the IDL file as follows: \begin{verbatim} #include ... \end{verbatim} This statement indicates to the IDL compiler that types \verb|NamedValue|, \verb|Principal|, and \verb|TypeCode| may be used. The file \verb|orb.idl| should not actually exist in your system. Do not name any of your IDL files orb.idl. \hdrii{Defining Data Type Names and Constants} IDL allows you to define new data type names and constants. This section describes how to use each of these features of IDL. \hdriii{Data Type Names} The typedef keyword allows you define a meaningful or simpler name for an IDL type. \begin{verbatim} module Finance { interface Account { ... }; typedef Account StandardAccount; }; \end{verbatim} The identifier \verb|StandardAccount| can act as an alias for type \verb|Account| in subsequent IDL definitions. Note that CORBA does not specify whether the identifiers \verb|Account| and \verb|StandardAccount| represent distinct IDL data types in this example. \hdriii{Constants} IDL allows you to specify \emph{constant} data values using one of several basic data types. To declare a constant, use the IDL keyword \verb|const|. \begin{verbatim} module Finance { interface Bank { const long MaxAccounts = 10000; const float Factor = (10.0 ­ 6.5) * 3.91; ... }; }; \end{verbatim} The value of an IDL constant cannot change. You can define a constant at any level of scope in your IDL specification. \begin{verbatim} \end{verbatim} \end{document}