\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<Account, 50> accounts; 
      }; 

      struct UnlimitedAccounts { 
        string bankSortCode<10>; 
        // No maximum length of sequence. 

      sequence<Account> 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<string> 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 <orb.idl> 
     ... 
\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}



