\documentclass[11pt,twoside,a4paper]{book}
\usepackage[T1]{fontenc}
\usepackage{palatino}

% To make the PostScript version:
%
%  $ latex omniORB
%  $ bibtex omniORB
%  $ latex omniORB
%  $ latex omniORB
%  $ latex omniORB
%  $ dvips omniORB
%
% To make the PDF version (having already made the PS version):
%
%  $ pdflatex omniORB
%  $ pdflatex omniORB
%
% To make the HTML version, you need HeVeA 1.05.
%
%  $ hevea omniORB
%  $ hacha omniORB.html
%
% HeVeA and HaChA come from http://pauillac.inria.fr/~maranget/hevea/


\bibliographystyle{alpha}

% Semantic mark-up:
\newcommand{\type}[1]{\texttt{#1}}
\newcommand{\intf}[1]{\texttt{#1}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\op}[1]{\texttt{#1()}}
\newcommand{\cmdline}[1]{\texttt{#1}}
\newcommand{\term}[1]{\textit{#1}}

\hyphenation{omni-ORB}

% Environment to make important statements stand out:
\newenvironment{statement}%
 {\noindent\begin{minipage}{\textwidth}%
  \vspace{.5\baselineskip}%
  \noindent\rule{\textwidth}{2pt}%
  \vspace{.25\baselineskip}%
  \begin{list}{}{\setlength{\listparindent}{0em}%
                 \setlength{\itemindent}{0em}%
                 \setlength{\leftmargin}{1.5em}%
                 \setlength{\rightmargin}{\leftmargin}%
                 \setlength{\topsep}{0pt}%
                 \setlength{\partopsep}{0pt}}
  \item\relax}
 {\end{list}%
  \vspace{-.25\baselineskip}%
  \noindent\rule{\textwidth}{2pt}%
  \vspace{.5\baselineskip}%
  \end{minipage}}

% Itemize with no itemsep:
\newenvironment{nsitemize}%
 {\begin{itemize}\setlength{\itemsep}{0pt}}%
 {\end{itemize}}

% URL-like things:
\usepackage[T1]{url}
\newcommand{\weburl}{\url}
\newcommand{\email}{\begingroup \urlstyle{rm}\Url}
\newcommand{\file}{\begingroup \urlstyle{tt}\Url}
\newcommand{\envvar}{\begingroup \urlstyle{tt}\Url}
\newcommand{\makevar}{\begingroup \urlstyle{tt}\Url}
\newcommand{\corbauri}{\begingroup \urlstyle{tt}\Url}


% HeVeA barfs at the following:

%BEGIN LATEX

\addtolength{\oddsidemargin}{-0.2in}
\addtolength{\evensidemargin}{-0.6in}
\addtolength{\textwidth}{0.5in}

\newcommand{\dsc}{\discretionary{}{}{}}

\pagestyle{headings}
\setcounter{secnumdepth}{3}
\setcounter{tocdepth}{3}

\usepackage{listings}
\lstdefinelanguage{idl}%
  {keywords={any,attribute,boolean,case,char,const,context,default,double,enum,exception,FALSE,float,in,inout,interface,long,module,Object,octet,oneway,out,raises,readonly,sequence,short,string,struct,switch,TRUE,typedef,unsigned,union,void},%
  sensitive,%
  singlecomment={/*}{*/},%
  commentline=//,%
  stringizer=[b]",%
  directives={define,elif,else,endif,error,if,ifdef,ifndef,line,include,pragma,undef,warning}%
  }[keywords,comments,strings,directives]

\lstset{basicstyle=\ttfamily\small,
        keywordstyle=,
        commentstyle=\itshape,
        labelstyle=\tiny,
        stringspaces=false,
        abovecaptionskip=0pt,
        belowcaptionskip=0pt,
        indent=\parindent,
        fontadjust}

\lstnewenvironment{idllisting}{\lstset{language=idl}}{}
\lstnewenvironment{cxxlisting}{\lstset{language=C++}}{}
\lstnewenvironment{makelisting}{\lstset{language=[gnu]make}}{}

%END LATEX

% These things make up for HeVeA's lack of understanding:

%HEVEA\newcommand{\dsc}{}
%HEVEA\newcommand{\vfill}{}
%HEVEA\newcommand{\mainmatter}{}
%HEVEA\newcommand{\backmatter}{}
%HEVEA\newcommand{\lstset}[1]{}
%HEVEA\newcommand{\textbackslash}{$\backslash$}
%HEVEA\usepackage{verbatim}
%HEVEA\newenvironment{idllisting}{\verbatim}{\endverbatim}
%HEVEA\newenvironment{cxxlisting}{\verbatim}{\endverbatim}
%HEVEA\newenvironment{makelisting}{\verbatim}{\endverbatim}


% Hyperref things for pdf and html:
\usepackage{hyperref}

\newif\ifpdf
\ifx\pdfoutput\undefined
  \pdffalse
\else
  \pdfoutput=1
  \pdftrue
\fi
\ifpdf
  \hypersetup{colorlinks,citecolor=red,urlcolor=blue}
\fi


% Finally, the set-up is almost over, and we can start the document:

\begin{document}

\pagenumbering{roman}
\pagestyle{empty}


\begin{center}

\vfill

{ \Huge
The omniORB version 3.0\\[4mm]
User's Guide
}

\vfill

{ \Large
Sai-Lai Lo\\
{\normalsize (\textit{email: \href{mailto:slo@uk.research.att.com}%
                                  {\email{slo@uk.research.att.com}}})}\\[2ex]
%
David Riddoch\\
{\normalsize (\textit{email: \href{mailto:djr@uk.research.att.com}%
                                  {\email{djr@uk.research.att.com}}})}\\[2ex]
%
Duncan Grisby\\
{\normalsize (\textit{email: \href{mailto:dgrisby@uk.research.att.com}%
                                  {\email{dgrisby@uk.research.att.com}}})}%
                                  \\[2ex]
%
AT\&T Laboratories Cambridge\\
}


\vfill
\vfill
May 2000
\vfill

\end{center}

\clearpage

{\Large \bf Changes and Additions, May 2000}
\begin{itemize}
\item Updated to omniORB 3.
\end{itemize}


\cleardoublepage

%HEVEA{\Large \bf Contents}
\tableofcontents

\cleardoublepage

\pagestyle{headings}

\pagenumbering{arabic}

\mainmatter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

omniORB is an Object Request Broker (ORB) that implements the 2.3
specification of the Common Object Request Broker Architecture
(CORBA)~\cite{corba23-spec}\footnote{Most of the 2.3 features have
been implemented. The features still missing in this release are listed
in section~\ref{missing}. Where possible, backward compatibility has
been maintained up to specification 2.0.}. It has passed the Open
Group CORBA compliant testsuite and is one of the three ORBs to have
been granted the CORBA brand in June 1999\footnote{More information
can be found at \weburl{http://www.opengroup.org/press/7jun99_b.htm}}.

This user guide tells you how to use omniORB to develop CORBA
applications. It assumes a basic understanding of CORBA.

In this chapter, we give an overview of the main features of omniORB
and what you need to do to setup your environment to run omniORB.

\section{Features}

\subsection{CORBA 2.3 compliant}

omniORB implements the Internet Inter-ORB Protocol (IIOP).  This
protocol provides omniORB the means of achieving interoperability with
the ORBs implemented by other vendors. In fact, this is the native
protocol used by omniORB for the communication amongst its objects
residing in different address spaces. Moreover, the IDL to C++
language mapping provided by omniORB conforms to the latest revision
of the CORBA specification. Type Any and TypeCode are now supported
(introduced in version 2.5.0). DynAny is supported since 2.6.0. The
Dynamic Invocation Interface and Dynamic Skeleton Interface are
supported since 2.7.0. The C++ mapping has been updated to the CORBA
2.3 specification since 2.8.0. The POA was introduced with 3.0.


\subsection{Multithreading}

omniORB is fully multithreaded. To achieve low IIOP call overhead,
unnecessary call-multiplexing is eliminated. At any time, there is at
most one call in-flight in each communication channel between two
address spaces. To do so without limiting the level of concurrency,
new channels connecting the two address spaces are created on demand
and cached when there are more concurrent calls in progress. Each
channel is served by a dedicated thread. This arrangement provides
maximal concurrency and eliminates any thread switching in either of
the address spaces to process a call. Furthermore, to maximise the
throughput in processing large call arguments, large data elements are
sent as soon as they are processed while the other arguments are being
marshalled.

\subsection{Portability}

At AT\&T Laboratories, the ability to target a single source tree to
multiple platforms is very important. This is difficult to achieve if
the IDL to C++ mapping for these platforms are different. We avoid
this problem by making sure that only one IDL to C++ mapping is used.
We run several flavours of Unix, Windows NT, Windows 95 and our
in-house developed systems for our own hardware. omniORB has been
ported to all these platforms. \textbf{The IDL to C++ mapping for
all these targets is the same}.

omniORB uses real C++ exceptions and nested classes. We keep to the
CORBA specification's standard mapping as much as possible and do not
use the alternative mappings for C++ dialects. The only exception is
the mapping of \textbf{modules}.

Starting with 2.6.0, the code generated by the IDL compiler of omniORB
can be compiled using \textbf{C++ classes} or \textbf{namespaces} to
represent IDL \textbf{modules} depending on the availability of
namespace support in the compiler.

omniORB relies on the native thread libraries to provide the
multithreading capability. A small class library
(omnithread~\cite{tjr96a}) is used to encapsulate the (possibly
different) APIs of the native thread libraries. In application code,
it is recommended but not mandatory to use this class library for
thread management. It should be easy to port omnithread to any
platform that either supports the POSIX thread standard or has a
thread package that supports similar capabilities.

\subsection{Missing features}
\label{missing}

omniORB is not (yet) a complete implementation of the CORBA 2.3 core.
The following is a list of the missing features.

\begin{itemize}

\item omniORB does not have its own Interface Repository. However, it
can act as a client to an IR.

\item The IDL types wchar, wstring, fixed, and valuetype are not
supported in this release.

\item The \type{PortableServer::Current} interface is not yet
supported.

\item The DSI interface has changed significantly.  Old code will have
to be re-written to the new interface.  There is no support for using
the DSI with the BOA.  This part of the ORB is incomplete, since it
depends in part on \type{PortableServer::Current}.  See
chapter~\ref{chap:dsi} for a way to workaround this problem for now.

\end{itemize}

These features may be implemented in the short to medium term. It is
best to check out the latest status on the omniORB home page
(\weburl{http://www.uk.research.att.com/omniORB/}).


\section{Setting Up Your Environment}
\label{setup}

At AT\&T Laboratories Cambridge, you should use the OMNI Development
Environment (ODE)~\cite{tjr96b} and the OMNI tree version 5.0 or above
to compile your programs. If this is the case, there is no extra setup
you have to do other than those described in the ODE documentation.

If you are running omniORB at other sites, you (or your system
administrator) should install omniORB by following the instructions in
the installation notes.

\begin{itemize}

\item On Unix platforms, the omniORB runtime looks for the environment
variable \envvar{OMNIORB_CONFIG}. If this variable is defined, it
contains the pathname of the omniORB configuration file. If the
variable is not set, omniORB will use the compiled-in pathname to
locate the file.

\item On ARM/ATMos, the omniORB runtime looks for configuration
information in the file \file{omniORB.cfg}.

\item On Win32 platforms (Windows NT, 2000, 95, 98), omniORB first
checks the environment variable \envvar{OMNIORB_CONFIG} to obtain the
pathname of the configuration file. If this is not set, it then
attempts to obtain configuration data in the system registry. It
searches for the data under the key
%BEGIN LATEX
\file{HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0}.
%END LATEX
%HEVEA \verb|HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0|.

\end{itemize}

The configuration file is used to obtain an object reference for the
Naming Service, via either a stringified IOR or an Interoperable
Naming Service URI. The entry in the configuration file should be
specified in the form:

\begin{verbatim}
   ORBInitRef NameService=<URI for the Naming Service>
\end{verbatim}

The easiest way of specifying the Naming Service is with a
\corbauri{corbaname:} URI, as described in
section~\ref{sec:corbaname}.

Comments in the configuration file should be prefixed with a
`\texttt{\#}' character.

On Win32 platforms, the naming service reference can be placed in the
system registry, in the (string) value \texttt{ORBInitRef}, under the
key
%BEGIN LATEX
\file{HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0}.
%END LATEX
%HEVEA \verb|HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0|.

\subsection{Deprecated configuration file entries}

\texttt{ORBInitRef} is new with omniORB 3.0. The omniORB 2 formats are
still supported, so you can specify the Naming Service IOR using a
line of the form:

\begin{verbatim}
   NAMESERVICE <IOR for the Naming Service>
\end{verbatim}

Since 2.6.0, two other entries have been supported, but are now made
obsolete by the Interoperable Naming Service URIs:

\begin{verbatim}
   ORBInitialHost <hostname string>
   ORBInitialPort <port number (1-65535)>
\end{verbatim}

The corresponding entries under the Win32 system registry are the keys
named \texttt{ORBInitialHost} and \texttt{ORBInitialPort}.

The two entries provide information to the ORB to locate a
(proprietary) bootstrap service at runtime. The bootstrap service is
able to return the initial object reference for the Naming Service and
others.


\section{Platform specific variables}

To compile omniORB programs correctly, several C++ preprocessor defines
\textbf{must} be specified to identify the target platform.

\begin{flushleft}
\begin{tabular}{|l|l|}
\hline
Platform            & CPP defines \\
\hline
Sun Solaris 2.5     & \verb|__sparc__   __sunos__    __OSVERSION__=5| \\
%\hline
Digital Unix 3.2    & \verb|__alpha__   __osf1__     __OSVERSION__=3| \\
%\hline
HPUX 10.x           & \verb|__hppa__    __hpux__     __OSVERSION__=10| \\
%\hline
HPUX 11.x           & \verb|__hppa__    __hpux__     __OSVERSION__=11| \\
%\hline
IBM AIX 4.x         & \verb|__aix__     __powerpc__  __OSVERSION__=4| \\
%\hline
Linux 2.0 (x86)     & \verb|__x86__     __linux__    __OSVERSION__=2| \\
%\hline
Linux 2.0 (alpha)   & \verb|__alpha__   __linux__    __OSVERSION__=2| \\
%\hline
Linux 2.0 (powerpc) & \verb|__powerpc__ __linux__    __OSVERSION__=2| \\
%\hline
Windows/NT 3.5      & \verb|__x86__     __NT__       __OSVERSION__=3  __WIN32__| \\
%\hline
Windows/NT 4.0      & \verb|__x86__     __NT__       __OSVERSION__=4  __WIN32__| \\
%\hline
Windows/95          & \verb|__x86__     __WIN32__| \\
%\hline
OpenVMS 6.x (alpha) & \verb|__alpha__   __vms        __OSVERSION__=6 | \\
%\hline
OpenVMS 6.x (vax)   & \verb|__vax__     __vms        __OSVERSION__=6 | \\
%\hline
SGI Irix 6.x        & \verb|__mips__    __irix__     __OSVERSION__=6 | \\
%\hline
Reliant Unix 5.43   & \verb|__mips__    __SINIX__    __OSVERSION__=5 | \\
%\hline
ATMos 4.0           & \verb|__arm__     __atmos__    __OSVERSION__=4| \\
%\hline
NextStep 3.x        & \verb|__m68k__    __nextstep__ __OSVERSION__=3| \\
%\hline
Unixware 7          & \verb|__x86__     __uw7__      __OSVERSION__=5| \\
\hline
\end{tabular}
\end{flushleft}

The preprocessor defines for new platform ports not listed above can
be found in the corresponding platform configuration files. For
instance, the platform configuration file for Sun Solaris 2.6 is in
\file{mk/platforms/sun4_sosV_5.6.mk}. The preprocessor defines to
identify a platform are in the make variable
\makevar{IMPORT_CPPFLAGS}.

In a single source multi-target environment, you can put the
preprocessor defines as the command-line arguments for the compiler.
Alternately, you could create a sitedef.h file in the same directory
as \file{omniORB3/CORBA.h}. Write into the file the appropriate set of
preprocessor defines and add

\begin{cxxlisting}
#include <omniORB3/sitedef.h>
\end{cxxlisting}

\noindent at the beginning of \file{omniORB3/CORBA_sysdep.h}.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The Basics}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{ch_basic}

In this chapter, we go through three examples to illustrate the
practical steps to use omniORB. By going through the source code of
each example, the essential concepts and APIs are introduced. If you
have no previous experience with using CORBA, you should study this
chapter in detail. There are pointers to other essential documents you
should be familiar with.

If you have experience with using other ORBs, you should still go
through this chapter because it provides important information about
the features and APIs that are necessarily omniORB specific. Now that
omniORB supports the Portable Object Adapter, there are very few
omniORB specific details.


\section{The Echo Object Example}

Our example is an object which has only one method. The method simply
echos the argument string. We have to:

\begin{enumerate}

\item define the object interface in IDL;
\item use the IDL compiler to generate the stub code\footnote{The stub
code is the C++ code that provides the object mapping as defined in
the CORBA 2.3 specification.};
\item provide the \term{servant} object implementation;
\item write the client code.

\end{enumerate}

The source code of this example is included in the last section of
this chapter. A makefile written to be used under the OMNI Development
Environment (ODE)~\cite{tjr96b} is also included.


\section{Specifying the Echo interface in IDL}

We define an object interface, called \intf{Echo}, as follows:

\begin{idllisting}
interface Echo {
    string echoString(in string mesg);
};
\end{idllisting}


If you are new to IDL, you can learn about its syntax in Chapter 3 of
the CORBA specification 2.3~\cite{corba23-spec}. For the moment, you
only need to know that the interface consists of a single operation,
\op{echoString}, which takes a string as an argument and returns a
copy of the same string.

The interface is written in a file, called \file{echo.idl}. It is part
of the CORBA standard that all IDL files should have the extension
`\file{.idl}', although omniORB does not enforce this. If you are
using ODE, the IDL files should be placed in the \file{idl} directory
of your export tree. This is done so that the stub code will be
generated automatically and kept up-to-date with your IDL file.

For simplicity, the interface is defined in the global IDL namespace.
You should avoid this practice for the sake of object reusability.  If
every CORBA developer defines their interfaces in the global IDL
namespace, there is a danger of name clashes between two independently
defined interfaces. Therefore, it is better to qualify your interfaces
by defining them inside \code{module} names. Of course, this does not
eliminate the chance of a name clash unless some form of naming
convention is agreed globally. Nevertheless, a well-chosen module name
can help a lot.

\section{Generating the C++ stubs}

From the IDL file, we use the IDL compiler to produce the C++ mapping
of the interface. The IDL compiler for omniORB is called omniidl.
Given the IDL file, omniidl produces two stub files: a C++ header file
and a C++ source file. For example, from the file \file{echo.idl}, the
following files are produced:

\begin{nsitemize}
\item\file{echo.hh}
\item\file{echoSK.cc}
\end{nsitemize}

\noindent omniidl must be invoked with the \cmdline{-bcxx} argument to
tell it to generate C++ stubs. The following command line generates
the stubs for \file{echo.idl}:

\begin{makelisting}
omniidl -bcxx echo.idl
\end{makelisting}

\noindent If you are using our make environment (ODE), you don't need
to invoke omniidl explicitly. In the example file \file{dir.mk}, we
have the following line:

\begin{makelisting}
CORBA_INTERFACES = echo
\end{makelisting}

\noindent That is all we need to instruct ODE to generate the stubs.
Remember, you won't find the stubs in your working directory because
all stubs are written into the \file{stub} directory at the top level
of your build tree.

The full arguments to omniidl are detailed in
chapter~\ref{chap:omniidl}.


\section{Object References and Servants}

We contact a CORBA object through an \term{object reference}. The
actual implementation of a CORBA object is termed a \term{servant}.

Object references and servants are quite separate entities, and it is
important not to confuse the two. Client code deals purely with object
references, so there can be no confusion; object implementation code
must deal with both object references and servants. omniORB 3 uses
distinct C++ types for object references and servants, so the compiler
will complain if you use a servant when an object reference is
expected, or vice-versa.

\begin{statement}
\centerline{\textbf{Warning}}

omniORB 2 \emph{did not} use distinct types for object references and
servants, and often accepted a pointer to a servant when the CORBA
specification says it should only accept an object reference. If you
have code which relies on this, it will not compile with omniORB 3,
even under omniORB 3's BOA compatibility mode.
\end{statement}



\section{A Quick Tour of the C++ stubs}

The C++ stubs conform to the mapping defined in the CORBA 2.3
specification (chapter 23). It is important to understand the mapping
before you start writing any serious CORBA applications. Before going
any further, it is worth knowing what the mapping looks like.

For the example interface \intf{Echo}, the C++ mapping for its object
reference is \type{Echo\_ptr}. The type is defined in \file{echo.hh}.
The relevant section of the code is reproduced below. The stub code
produced by other ORBs will be functionally equivalent to omniORB's,
but will almost certainly look very different.

\begin{cxxlisting}
class Echo;
class _objref_Echo;
class _impl_Echo;
typedef _objref_Echo* Echo_ptr;

class Echo {
public:
  // Declarations for this interface type.
  typedef Echo_ptr _ptr_type;
  typedef Echo_var _var_type;

  static _ptr_type _duplicate(_ptr_type);
  static _ptr_type _narrow(CORBA::Object_ptr);
  static _ptr_type _nil();

  // ... methods generated for internal use
};

class _objref_Echo :
  public virtual CORBA::Object, public virtual omniObjRef {
public:
  char * echoString(const char* mesg);

  // ... methods generated for internal use
};
\end{cxxlisting}

In a compliant application, the operations defined in an object
interface should \textbf{only} be invoked via an object reference.
This is done by using arrow (`\code{->}') on an object reference.
For example, the call to the operation \op{echoString} would be
written as \code{obj->echoString(mesg)}.

It should be noted that the concrete type of an object reference is
opaque, i.e.\ you must not make any assumption about how an object
reference is implemented. In our example, even though \type{Echo\_ptr}
is implemented as a pointer to the class \type{\_objref\_Echo}, it
should not be used as a C++ pointer, i.e. conversion to \type{void*},
arithmetic operations, and relational operations, including test for
equality using \code{operator==} must not be performed on the type.

In addition to class \type{\_objref\_Echo}, the mapping defines three
static member functions in the class \type{Echo}: \op{\_nil},
\op{\_duplicate}, and \op{\_narrow}.

The \op{\_nil} function returns a nil object reference of the Echo
interface. The following call is guaranteed to return TRUE:

\begin{cxxlisting}
CORBA::Boolean true_result = CORBA::is_nil(Echo::_nil());
\end{cxxlisting}

Remember, \op{CORBA::is\_nil} is the only compliant way to check if an
object reference is nil. You should not use the equality
\code{operator==}.

The \op{\_duplicate} function returns a new object reference of the
\intf{Echo} interface. The new object reference can be used
interchangeably with the old object reference to perform an operation
on the same object.

All CORBA objects inherit from the generic object
\type{CORBA::Object}.  \type{CORBA::\dsc{}Object\_ptr} is the object
reference type for \type{CORBA::Object}.  Any \type{\_ptr} object
reference is therefore conceptually inherited from
\type{CORBA::Object\_ptr}. In other words, an object reference such as
\type{Echo\_ptr} can be used in places where a
\type{CORBA::Object\_ptr} is expected.

The \op{\_narrow} function takes an argument of type
\type{CORBA::Object\_ptr} and returns a new object reference of the
\intf{Echo} interface.  If the actual (runtime) type of the argument
object reference can be widened to \type{Echo\_ptr}, \op{\_narrow}
will return a valid object reference. Otherwise it will return a nil
object reference. Note that \op{\_narrow} performs an implicit
duplication of the object reference, so the result must be released.
Note also that \op{\_narrow} may involve a remote call to check the
type of the object, so it may throw CORBA system exceptions such as
\code{COMM\_FAILURE}.

To indicate that an object reference will no longer be accessed, you
must call the \op{CORBA::release} operation. Its signature is as
follows:

\begin{cxxlisting}
class CORBA {
  static void release(CORBA::Object_ptr obj);
  ... // other methods
};
\end{cxxlisting}

Once you have called \op{CORBA::release} on an object reference, you
should no longer use that reference. This is because the associated
resources may have been deallocated. Notice that we are referring to
the resources associated with the object reference and \textbf{not the
servant object}. Servant objects are not affected by the lifetimes of
object references. In particular, servants are not deleted when all
references to them have been released---CORBA does not perform
distributed garbage collection.

As described above, the equality \code{operator==} should not be used
on object references. To test if two object references are equivalent,
the member function \op{\_is\_equivalent} of the generic object
\type{CORBA::Object} can be used. Here is an example of its usage:

\begin{cxxlisting}
Echo_ptr A;
...            // initialise A to a valid object reference 
Echo_ptr B = A;
CORBA::Boolean true_result = A->_is_equivalent(B); 
// Note: the above call is guaranteed to be TRUE
\end{cxxlisting}

You have now been introduced to most of the operations that can be
invoked via \type{Echo\_ptr}. The generic object \type{CORBA::Object}
provides a few more operations and all of them can be invoked via
\type{Echo\_ptr}. These operations deal mainly with CORBA's dynamic
interfaces. You do not have to understand them in order to use the C++
mapping provided via the stubs. For details, please read the CORBA
specification~\cite{corba23-spec}, chapter 23.

Since object references must be released explicitly, their usage is
prone to error and can lead to memory leakage. The mapping defines the
\term{object reference variable} type to make life easier. In our
example, the variable type \type{Echo\_var} is defined\footnote{In
omniORB, all object reference variable types are instantiated from the
template type \type{\_CORBA\_ObjRef\_Var}.}.

The \type{Echo\_var} is more convenient to use because it will
automatically release its object reference when it is deallocated or
when assigned a new object reference. For many operations, mixing data
of type \type{Echo\_var} and \type{Echo\_ptr} is possible without any
explicit operations or castings\footnote{However, the implementation
of the type conversion operator between \type{Echo\_var} and
\type{Echo\_ptr} varies slightly among different C++ compilers; you
may need to do an explicit cast if the compiler complains about the
conversion being ambiguous.}. For instance, the operation
\op{echoString} can be called using the arrow (`\code{->}') on a
\type{Echo\_var}, as one can do with a \type{Echo\_ptr}.

The usage of \type{Echo\_var} is illustrated below:


\begin{cxxlisting}
Echo_var a;
Echo_ptr p = ... // somehow obtain an object reference

a = p;           // a assumes ownership of p, must not use p any more

Echo_var b = a;  // implicit _duplicate

p = ...          // somehow obtain another object reference

a = Echo::_duplicate(p);     // release old object reference
                             // a now holds a copy of p.
\end{cxxlisting}



\subsection{Servant Object Implementation}
\label{stubobjimpl}

Before the Portable Object Adapter (POA) specification, many of the
details of how servant objects should be implemented and registered
with the system were unspecified, so server-side code was not portable
between ORBs. The POA specification rectifies that. omniORB 3 still
supports the old omniORB 2.x BOA mapping, but you should always use
the POA mapping for new code. BOA code and POA code can coexist within
a single program. See section~\ref{sec:BOAcompat} for details of the
BOA compatibility, and problems you may encounter.

For each object interface, a \term{skeleton} class is generated.  In
our example, the POA specification says that the skeleton class for
interface \intf{Echo} is named \type{POA\_Echo}. A servant
implementation can be written by creating an implementation class that
derives from the skeleton class.

The skeleton class \type{POA\_Echo} is defined in \file{echo.hh}. The
relevant section of the code is reproduced below.

\begin{cxxlisting}
class _impl_Echo :
  public virtual omniServant
{
public:
  virtual char * echoString(const char*  mesg) = 0;
  // ...
};

class POA_Echo :
  public virtual _impl_Echo,
  public virtual PortableServer::ServantBase
{
public:
  Echo_ptr _this();
  // ...
};
\end{cxxlisting}

The code fragment shows the only member functions that can be used in
the object implementation code. Other member functions are generated
for internal use only. As with the code generated for object
references, other POA-based ORBs will generate code which looks
different, but is functionally equivalent to this.


\begin{description}

\item[\op{echoString}]\mbox{}\\
%
It is through this abstract function that an implementation class
provides the implementation of the \op{echoString} operation. Notice
that its signature is the same as the \op{echoString} function that
can be invoked via the \type{Echo\_ptr} object reference.

\item[\op{\_this}]\mbox{}\\
%
This function returns an object reference for the target object,
provided the POA policies permit it. The returned value must be
deallocated via \op{CORBA::\dsc{}release}.  See section~\ref{objeg1}
for an example of how this function is used.

\end{description}

\section{Writing the servant implementation}
\label{objimpl}

You define an implementation class to provide the servant
implementation. There is little constraint on how you design your
implementation class except that it has to inherit from the stubs'
skeleton class and to implement all the abstract functions defined in
the skeleton class. Each of these abstract functions corresponds to an
operation of the interface. They are the hooks for the ORB to perform
upcalls to your implementation.

Here is a simple implementation of the Echo object.

\begin{cxxlisting}
class Echo_i : public POA_Echo,
	       public PortableServer::RefCountServantBase
{
public:
  inline Echo_i() {}
  virtual ~Echo_i() {}
  virtual char* echoString(const char* mesg);
};

char* Echo_i::echoString(const char* mesg)
{
  return CORBA::string_dup(mesg);
}
\end{cxxlisting}

There are four points to note here:

\begin{description}

\item[Storage Responsibilities]\mbox{}\\
%
A string, which is used both as an in argument and the return value of
\op{echoString}, is a variable size data type. Other examples of
variable size data types include sequences, type `any', etc. For these
data types, you must be clear about whose responsibility it is to
allocate and release the associated storage. As a rule of thumb, the
client (or the caller to the implementation functions) owns the
storage of all IN arguments, the object implementation (or the callee)
must copy the data if it wants to retain a copy. For OUT arguments and
return values, the object implementation allocates the storage and
passes the ownership to the client. The client must release the
storage when the variables will no longer be used.  For details,
please refer section 23.22 of the CORBA 2.3 specification.

\item[Multi-threading]\mbox{}\\
%
As omniORB is fully multithreaded, multiple threads may perform the
same upcall to your implementation concurrently. It is up to your
implementation to synchronise the threads' accesses to shared data.
In our simple example, we have no shared data to protect so no thread
synchronisation is necessary.

Alternatively, you can create a POA which has the
\code{SINGLE\_THREAD\_MODEL} Thread Policy. This guarantees that all
calls to that POA are processed sequentially.

\item[Reference Counting]\mbox{}\\
%
As well as inheriting from the Echo skeleton class, the servant class
is also derived from \type{PortableServer::RefCountServantBase} which,
as the name suggests, is a mixin class which provides reference
counting for the servant object. This means that an \type{Echo\_i}
instance will be deleted when no more references to it are held by
application code or the POA itself. Not that this is totally separate
from the reference counting which is associated with object
references---a servant object is \emph{never} deleted due to a CORBA
object reference being released.

\item[Instantiation]\mbox{}\\
%
Servants which derive from \type{PortableServer::RefCountServantBase}
must not be instantiated as automatic variables (i.e.\ on the
stack). Instead, you should always instantiate them using the
\code{new} operator, i.e.\ their storage is allocated on the
heap. Otherwise, the POA may attempt to delete an object on the stack.

\end{description}

\section{Writing the client}

Here is an example of how an \type{Echo\_ptr} object reference is
used.

\lstset{labelstep=1,gobble=4}
\begin{cxxlisting}
 1  void
 2  hello(CORBA::Object_ptr obj)
 3  {
 4    Echo_var e = Echo::_narrow(obj);
 5
 6    if (CORBA::is_nil(e)) {
 7      cerr << "cannot invoke on a nil object reference.\n"
 8           << endl;
 9      return;
10    }
11
12    CORBA::String_var src = (const char*) "Hello!";
13    CORBA::String_var dest;
14
15    dest = e->echoString(src);
16
17    cerr << "I said,\"" << src << "\"."
18         << " The Object said,\"" << dest <<"\"" << endl;
19  }
\end{cxxlisting}
\lstset{labelstep=0,gobble=0}

Briefly, the function \op{hello} accepts a generic object reference.
The object reference (\code{obj}) is narrowed to \type{Echo\_ptr}. If
the object reference returned by \op{Echo::\_narrow} is not nil, the
operation \op{echoString} is invoked. Finally, both the argument to
and the return value of \op{echoString} are printed to \code{cerr}.

The example also illustrates how \type{T\_var} types are used. As it
was explained in the previous section, \type{T\_var} types take care
of storage allocation and release automatically when variables of the
type are assigned to or when the variables go out of scope.

In line 4, the variable \code{e} takes over the storage responsibility
of the object reference returned by \op{Echo::\_narrow}. The object
reference is released by the destructor of \code{e}. It is called
automatically when the function returns. Lines 6 and 15 show how a
\type{Echo\_var} variable is used. As said earlier, \type{Echo\_var}
type can be used interchangeably with \type{Echo\_ptr} type.

The argument and the return value of \op{echoString} are stored in
\type{CORBA::\dsc{}String\_var} variables \code{src} and \code{dest}
respectively. The strings managed by the variables are deallocated by
the destructor of \type{CORBA::String\_var}. It is called
automatically when the variable goes out of scope (as the function
returns). Line 15 shows how \type{CORBA::String\_var} variables are
used. They can be used in place of a string (for which the mapping is
\type{char*})\footnote{A conversion operator of
\type{CORBA::String\_var} converts a \type{CORBA::\dsc{}String\_var}
to a \type{char*}.}. As used in line 12, assigning a constant string
(\type{const char*}) to a \type{CORBA::String\_var} causes the string
to be copied. On the other hand, assigning a \type{char*} to a
\type{CORBA::String\_var}, as used in line 15, causes the latter to
assume the ownership of the string\footnote{Please refer to the CORBA
specification section 23.7 for the details of the String\_var
mapping. Other \type{T\_var} types are also covered in chapter 23.}.

Under the C++ mapping, \type{T\_var} types are provided for all the
non-basic data types.  It is obvious that one should use automatic
variables whenever possible both to avoid memory leak and to maximise
performance. However, when one has to allocate data items on the heap,
it is a good practice to use the \type{T\_var} types to manage the
heap storage.

\section{Example 1 --- Colocated Client and Implementation}
\label{objeg1}

Having introduced the client and the object implementation, we can now
describe how to link up the two via the ORB and POA. In this section,
we describe an example in which both the client and the object
implementation are in the same address space. In the next two
sections, we shall describe the case where the two are in different
address spaces.

The code for this example is reproduced below:


\lstset{labelstep=1,gobble=4}
\begin{cxxlisting}
 1  int
 2  main(int argc, char **argv)
 3  {
 4    CORBA::ORB_ptr orb = CORBA::ORB_init(argc,argv,"omniORB3");
 5
 6    CORBA::Object_var       obj = orb->resolve_initial_references("RootPOA");
 7    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);
 8
 9    Echo_i *myecho = new Echo_i();
10    PortableServer::ObjectId_var myechoid = poa->activate_object(myecho);
11
12    Echo_var myechoref = myecho->_this();
13    myecho->_remove_ref();
14
15    PortableServer::POAManager_var pman = poa->the_POAManager();
16    pman->activate();
17
18    hello(myechoref);
19
20    orb->destroy();
21    return 0;
22  }
\end{cxxlisting}
\lstset{labelstep=0,gobble=0}

The example illustrates several important interactions among the ORB,
the POA, the servant, and the client. Here are the details:

\subsection{ORB initialisation}

\begin{description}

\item[Line 4]\mbox{}\\
%
The ORB is initialised by calling the \op{CORBA::ORB\_init}
function. The function uses the 3rd argument to determine which ORB
should be returned. To use omniORB 3, this argument must either be
`omniORB3' or NULL. If it is NULL, there must be an argument, -ORBid
`omniORB3', in \code{argv}\footnote{For backwards compatibility, the
ORB identifier `omniORB2' is also accepted.}. Like all command-line
arguments understood by the ORB, it will be removed from \code{argv}
when \op{CORBA::ORB\_init} returns. Therefore, an application is not
required to handle any command-line arguments it does not
understand. If the ORB identifier is not `omniORB3', the
initialisation will fail and a nil \type{ORB\_ptr} will be returned.
If supplied, omniORB also reads the configuration file
\file{omniORB.cfg}. Among other things, the file provides a list of
initial object references. One example of these object references is
the Naming service. Its use will be discussed in
section~\ref{resolveinit}. If any error occurs during the processing
of the configuration file, the system exception
\code{CORBA::INITIALIZE} is raised.

\end{description}


\subsection{Obtaining the Root POA}

\begin{description}

\item[Lines 6--7]\mbox{}\\
%
To activate our servant object and make it available to clients, we
must register it with a POA. In this example, we use the \term{Root
POA}, rather than creating any child POAs. The Root POA is found with
\op{orb->resolve\_initial\_\dsc{}references}, which returns a plain
\type{CORBA::Object}. In line 7, we narrow the reference to the right
type for a POA.

A POA's behaviour is governed by its \term{policies}. The Root POA has
suitable policies for many simple servers, and closely matches the
`policies' used by omniORB 2's BOA. See Chapter 11 of the CORBA 2.3
specification\cite{corba23-spec} for details of all the POA policies
which are available.

\end{description}


\subsection{Object initialisation}

\begin{description}

\item[Line 9]\mbox{}\\
%
An instance of the Echo object is initialised using the \code{new}
operator.

\item[Line 10]\mbox{}\\
%
The servant object is activated in the Root POA using
\op{poa->activate\_\dsc{}object}, which returns an object identifier
(of type \type{PortableServer::\dsc{}ObjectId*}). The object id must
be passed back to various POA operations. The caller is responsible
for freeing the object id, so it is assigned to a \type{\_var} type.

\item[Line 12]\mbox{}\\
%
The object reference is obtained from the servant object by calling
\op{\_this}. Like all object references, the return value of
\op{\_this} must be released by \op{CORBA::release} when it is no
longer needed. In this case, we assign it to a \type{\_var} type, so
the release is implicit at the end of the function.

One of the important characteristics of an object reference is that it
is completely location transparent. A client can invoke on the object
using its object reference without any need to know whether the
servant object is colocated in the same address space or is in a
different address space.

In the case of colocated client and servant, omniORB is able to
short-circuit the client calls so they do not involve IIOP. The calls
still go through the POA, however, so the various POA policies affect
local calls in the same way as remote ones. This optimisation is
applicable not only to object references returned by \op{\_this}, but
to any object references that are passed around within the same
address space or received from other address spaces via IIOP calls.

\item[Line 13]\mbox{}\\
%
The server code releases the reference it holds to the servant
object. The only reference to that object is now held by the POA (it
gained the reference on the call to \op{activate\_object}), so when
the object is deactivated (or the POA is destroyed), the servant
object will be deleted automatically. After this point, the code must
no longer use the \code{myecho} pointer.

\end{description}


\subsection{Activating the POA}

\begin{description}

\item[Lines 15--16]\mbox{}\\
%
POAs are initially in the \term{holding} state, meaning that incoming
requests are blocked. Lines 15 and 16 acquire a reference to the POA's
POA manager, and use it to put the POA into the \term{active} state.
Incoming requests are now served.

\end{description}


\subsection{Performing a call}

\begin{description}

\item[Line 18]\mbox{}\\
%
At long last, we can call \op{hello} with this object reference. The
argument is widened implicitly to the generic object reference
\type{CORBA::Object\_ptr}.

\end{description}


\subsection{ORB destruction}

\begin{description}

\item[Line 20]\mbox{}\\
%
Shutdown the ORB permanently. This call causes the ORB to release all
its resources, e.g.\ internal threads, and also to deactivate any
servant objects which are currently active. When it deactivates the
\type{Echo\_i} instance, the object's reference count drops to zero,
so the object is deleted.

This call is particularly important when writing a CORBA DLL on
Windows NT that is to be used from ActiveX. If this call is absent,
the application will hang when the CORBA DLL is unloaded.

\end{description}



\section{Example 2 --- Different Address Spaces}

In this example, the client and the object implementation reside in
two different address spaces. The code of this example is almost the
same as the previous example. The only difference is the extra work
which needs to be done to pass the object reference from the object
implementation to the client.

The simplest (and quite primitive) way to pass an object reference
between two address spaces is to produce a \term{stringified} version
of the object reference and to pass this string to the client as a
command-line argument.  The string is then converted by the client
into a proper object reference.  This method is used in this
example. In the next example, we shall introduce a better way of
passing the object reference using the CORBA Naming Service.

\subsection{Object Implementation: Generating a Stringified Object Reference}

The \op{main} function of the server side is reproduced below. The
full listing (\file{eg2_impl.cc}) can be found at the end of this
chapter.

\lstset{labelstep=1,gobble=4}
\begin{cxxlisting}
 1  int main(int argc, char** argv)
 2  {
 3    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");
 4
 5    CORBA::Object_var       obj = orb->resolve_initial_references("RootPOA");
 6    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);
 7
 8    Echo_i* myecho = new Echo_i();
 9
10    PortableServer::ObjectId_var myechoid = poa->activate_object(myecho);
11
12    obj = myecho->_this();
13    CORBA::String_var sior(orb->object_to_string(obj));
14    cerr << "'" << (char*)sior << "'" << endl;
15
16    myecho->_remove_ref();
17
18    PortableServer::POAManager_var pman = poa->the_POAManager();
19    pman->activate();
20
21    orb->run();
22    orb->destroy();
23    return 0;
24  }
\end{cxxlisting}
\lstset{labelstep=0,gobble=0}

The stringified object reference is obtained by calling the ORB's
\op{object\_to\_\dsc{}string} function (line 13). This results in a
string starting with the signature `IOR:' and followed by some
hexadecimal digits. All CORBA 2 compliant ORBs are able to convert the
string into its internal representation of a so-called Interoperable
Object Reference (IOR). The IOR contains the location information and
a key to uniquely identify the object implementation in its own
address space\footnote{Notice that the object key is not globally
unique across address spaces.}. From the IOR, an object reference can
be constructed.

\subsection{Client: Using a Stringified Object Reference}
\label{clnt2}

The stringified object reference is passed to the client as a
command-line argument. The client uses the ORB's
\op{string\_to\_object} function to convert the string into a generic
object reference (\type{CORBA::Object\_ptr}). The relevant section of
the code is reproduced below. The full listing (\file{eg2_clt.cc}) can
be found at the end of this chapter.

\begin{cxxlisting}
try {
  CORBA::Object_var obj = orb->string_to_object(argv[1]);
  hello(obj);
}
catch(CORBA::COMM_FAILURE& ex) {
  ... // code to handle communication failure
}
\end{cxxlisting}


\subsection{Catching System Exceptions}

When omniORB detects an error condition, it may raise a system
exception.  The CORBA specification defines a series of exceptions
covering most of the error conditions that an ORB may encounter. The
client may choose to catch these exceptions and recover from the error
condition\footnote{If a system exception is not caught, the C++
runtime will call the \op{terminate} function. This function is
defaulted to abort the whole process and on some systems will cause a
core file to be produced.}. For instance, the code fragment, shown in
section~\ref{clnt2}, catches the \code{COMM\_FAILURE} system exception
which indicates that communication with the object implementation in
another address space has failed.

All system exceptions inherit from \type{CORBA::SystemException}. With
compilers that properly support RTTI\footnote{Run Time Type
Identification}, a single catch of \code{CORBA::SystemException} will
catch all the different system exceptions thrown by omniORB.

When omniORB detects an internal error that is most likely to be
caused by a bug in the runtime, it raises the exception
\type{omniORB::fatalException}.  When this exception is raised, it is
not sensible to proceed with any operation that involves the ORB's
runtime. It is best to exit the program immediately. The exception
structure carried by \type{omniORB::fatalException} contains the exact
location (the file name and the line number) where the exception is
raised. If this occurs, you are strongly encouraged to file a bug
report and point out the location.

\subsection{Lifetime of a CORBA object}

CORBA objects are either \term{transient} or \term{persistent}. The
majority are transient, meaning that the lifetime of the CORBA object
(as contacted through an object reference) is the same as the lifetime
of its servant object. Persistent objects can live beyond the
destruction of their servant object, the POA they were created in, and
even their process. Persistent objects are, of course, only
contactable when their associated servants are active, or can be
activated by their POA with a servant manager\footnote{The POA itself
can be activated on demand with an adapter activator.}. A reference to
a persistent object can be published, and will remain valid even if
the server process is restarted.

A POA's Lifespan Policy determines whether objects created within it
are transient or persistent. The Root POA has the \code{TRANSIENT}
policy.

An alternative to creating persistent objects is to register object
references in a \term{naming service} and bind them to fixed
pathnames. Clients can bind to the object implementations at runtime
by asking the naming service to resolve the pathnames to the object
references. CORBA defines a standard naming service, which is a
component of the Common Object Services (COS)~\cite{corbaservices},
that can be used for this purpose. The next section describes an
example of how to use the COS Naming Service.

\section{Example 3 --- Using the Naming Service}

In this example, the object implementation uses the Naming
Service~\cite{corbaservices} to pass on the object reference to the
client.  This method is far more practical than using stringified
object references. The full listing of the object implementation
(\file{eg3_impl.cc}) and the client (\file{eg3_clt.cc}) can be found
at the end of this chapter.

The names used by the Naming service consist of a sequence of
\term{name components}. Each name component has an \term{id} and a
\term{kind} field, both of which are strings. All name components
except the last one are bound to a naming context. A naming context is
analogous to a directory in a filing system: it can contain names of
object references or other naming contexts. The last name component is
bound to an object reference.

Sequences of name components can be represented as a flat string,
using `.' to separate the id and kind fields, and `/' to separate name
components from each other\footnote{There are escaping rules to cope
with id and kind fields which contain `.' and `/' characters. See
chapter~\ref{chap:ins} of this manual, and chapter 3 of the CORBA
services specification, as updated for the Interoperable Naming
Service~\cite{inschapters}.}. In our example, the Echo object
reference is bound to the stringified name
`\file{test.my_context/Echo.Object}'.

The kind field is intended to describe the name in a
syntax-independent way. The naming service does not interpret, assign,
or manage these values. However, both the name and the kind attribute
must match for a name lookup to succeed. In this example, the kind
values for \file{test} and \file{Echo} are chosen to be
`\file{my_context}' and `\file{Object}' respectively. This is an
arbitrary choice as there is no standardised set of kind values.



\subsection{Obtaining the Root Context Object Reference}
\label{resolveinit}

The initial contact with the Naming Service can be established via the
\term{root} context. The object reference to the root context is
provided by the ORB and can be obtained by calling
\op{resolve\_initial\_references}. The following code fragment shows
how it is used:

\begin{cxxlisting}
CORBA::ORB_ptr orb = CORBA::ORB_init(argc,argv,"omniORB3");

CORBA::Object_var initServ;
initServ = orb->resolve_initial_references("NameService");

CosNaming::NamingContext_var rootContext;
rootContext = CosNaming::NamingContext::_narrow(initServ);
\end{cxxlisting}

Remember, omniORB constructs its internal list of initial references
at initialisation time using the information provided in the
configuration file \file{omniORB.cfg}, or given on the command
line. If this file is not present, the internal list will be empty and
\op{resolve\_initial\_references} will raise a
\code{CORBA::ORB::\dsc{}InvalidName} exception.

\subsection{The Naming Service Interface}

It is beyond the scope of this chapter to describe in detail the
Naming Service interface. You should consult the CORBA services
specification~\cite{corbaservices} (chapter 3). The code listed in
\file{eg3_impl.cc} and \file{eg3_clt.cc} are good examples of how the
service can be used. Please spend time to study the examples
carefully.


\section{Example 4 --- Using tie implementation templates}

Since 2.6.0, omniORB has supported \term{tie} implementation templates
as an alternative way of providing servant classes. If you use the
\texttt{-Wbtp} option to omniidl, it generates an extra template class
for each interface. This template class can be used to tie a C++ class
to the skeleton class of the interface.

The source code in \file{eg3_tieimpl.cc} at the end of this chapter
illustrates how the template class can be used. The code is almost
identical to \file{eg3_impl.cc} with only a few changes.

Firstly, the servant class \type{Echo\_i} does not inherit from any
stub classes. This is the main benefit of using the template class
because there are applications in which it is difficult to require
every servant class to derive from CORBA classes.

Secondly, the instantiation of a CORBA object now involves creating an
instance of the implementation class \emph{and} an instance of the
template.  Here is the relevant code fragment:

\begin{cxxlisting}
class Echo_i { ... };

Echo_i *myimpl = new Echo_i();
POA_Echo_tie<Echo_i> myecho(myimpl);

PortableServer::ObjectId_var myechoid = poa->activate_object(&myecho);
\end{cxxlisting}


For interface \intf{Echo}, the name of its tie implementation template
is \type{POA\_Echo\_\dsc{}tie}. The template parameter is the servant
class that contains an implementation of each of the operations
defined in the interface. As used above, the tie template takes
ownership of the \type{Echo\_i} instance, and deletes it when the tie
object goes out of scope. The tie constructor has an optional boolean
argument (defaulted to true) which indicates whether or not it should
delete the servant object. For full details of using tie templates,
see section~23.36.7 of the CORBA 2.3 C++ mapping
specification~\cite{corba23-spec}.


\clearpage
\section{Source Listings}

\subsection{eg1.cc}

\begin{cxxlisting}
// eg1.cc - This is the source code of example 1 used in Chapter 2
//          "The Basics" of the omniORB user guide.
//
//          In this example, both the object implementation and the
//          client are in the same process.
//
// Usage: eg1
//

#include <iostream.h>
#include <echo.hh>

// This is the object implementation.

class Echo_i : public POA_Echo,
	       public PortableServer::RefCountServantBase
{
public:
  inline Echo_i() {}
  virtual ~Echo_i() {}
  virtual char* echoString(const char* mesg);
};

char* Echo_i::echoString(const char* mesg)
{
  return CORBA::string_dup(mesg);
}

//////////////////////////////////////////////////////////////////////
// This function acts as a client to the object.

static void hello(Echo_ptr e)
{
  if( CORBA::is_nil(e) ) {
    cerr << "hello: The object reference is nil!\n" << endl;
    return;
  }

  CORBA::String_var src = (const char*) "Hello!";
  // String literals are (char*) rather than (const char*) on some
  // old compilers.  Thus it is essential to cast to (const char*)
  // here to ensure that the string is copied, so that the
  // CORBA::String_var does not attempt to 'delete' the string
  // literal.

  CORBA::String_var dest = e->echoString(src);

  cerr << "I said, \"" << (char*)src << "\"." << endl
       << "The Echo object replied, \"" << (char*)dest <<"\"." << endl;
}

//////////////////////////////////////////////////////////////////////

int main(int argc, char** argv)
{
  try {
    // Initialise the ORB.
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    // Obtain a reference to the root POA.
    CORBA::Object_var obj = orb->resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    // We allocate the object on the heap.  Since this is a reference
    // counted object, it will be deleted by the POA when it is no
    // longer needed.
    Echo_i* myecho = new Echo_i();

    // Activate the object.  This tells the POA that this object is
    // ready to accept requests.
    PortableServer::ObjectId_var myechoid = poa->activate_object(myecho);

    // Obtain a reference to the object.
    Echo_var myechoref = myecho->_this();

    // Decrement the reference count of the object implementation, so
    // that it will be properly cleaned up when the POA has determined
    // that it is no longer needed.
    myecho->_remove_ref();

    // Obtain a POAManager, and tell the POA to start accepting
    // requests on its objects.
    PortableServer::POAManager_var pman = poa->the_POAManager();
    pman->activate();

    // Do the client-side call.
    hello(myechoref);

    // Clean up all the resources.
    orb->destroy();
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to contact the "
         << "object." << endl;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }

  return 0;
}
\end{cxxlisting}


\clearpage
\subsection{eg2\_impl.cc}

\begin{cxxlisting}
// eg2_impl.cc - This is the source code of example 2 used in Chapter 2
//               "The Basics" of the omniORB user guide.
//
//               This is the object implementation.
//
// Usage: eg2_impl
//
//        On startup, the object reference is printed to cerr as a
//        stringified IOR. This string should be used as the argument to 
//        eg2_clt.
//

#include <iostream.h>
#include <echo.hh>

class Echo_i : public POA_Echo,
	       public PortableServer::RefCountServantBase
{
public:
  inline Echo_i() {}
  virtual ~Echo_i() {}
  virtual char* echoString(const char* mesg);
};

char* Echo_i::echoString(const char* mesg)
{
  return CORBA::string_dup(mesg);
}

//////////////////////////////////////////////////////////////////////

int main(int argc, char** argv)
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    CORBA::Object_var obj = orb->resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    Echo_i* myecho = new Echo_i();

    PortableServer::ObjectId_var myechoid = poa->activate_object(myecho);

    // Obtain a reference to the object, and print it out as a
    // stringified IOR.
    obj = myecho->_this();
    CORBA::String_var sior(orb->object_to_string(obj));
    cerr << "'" << (char*)sior << "'" << endl;

    myecho->_remove_ref();

    PortableServer::POAManager_var pman = poa->the_POAManager();
    pman->activate();

    orb->run();
    orb->destroy();
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}
\end{cxxlisting}


\clearpage
\subsection{eg2\_clt.cc}

\begin{cxxlisting}
// eg2_clt.cc - This is the source code of example 2 used in Chapter 2
//              "The Basics" of the omniORB user guide.
//
//              This is the client. The object reference is given as a
//              stringified IOR on the command line.
//
// Usage: eg2_clt <object reference>
//

#include <iostream.h>
#include <echo.hh>

static void hello(Echo_ptr e)
{
  CORBA::String_var src  = (const char*) "Hello!";
  CORBA::String_var dest = e->echoString(src);

  cerr << "I said, \"" << (char*)src << "\"." << endl
       << "The Echo object replied, \"" << (char*)dest <<"\"." << endl;
}

//////////////////////////////////////////////////////////////////////

int main(int argc, char** argv)
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    if( argc != 2 ) {
      cerr << "usage:  eg2_clt <object reference>" << endl;
      return 1;
    }

    CORBA::Object_var obj = orb->string_to_object(argv[1]);
    Echo_var echoref = Echo::_narrow(obj);
    if( CORBA::is_nil(echoref) ) {
      cerr << "Can't narrow reference to type Echo (or it was nil)." << endl;
      return 1;
    }
    hello(echoref);

    orb->destroy();
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to contact the "
         << "object." << endl;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught a CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}
\end{cxxlisting}


\clearpage
\subsection{eg3\_impl.cc}

\begin{cxxlisting}
// eg3_impl.cc - This is the source code of example 3 used in Chapter 2
//               "The Basics" of the omniORB user guide.
//
//               This is the object implementation.
//
// Usage: eg3_impl
//
//        On startup, the object reference is registered with the
//        COS naming service. The client uses the naming service to
//        locate this object.
//
//        The name which the object is bound to is as follows:
//              root  [context]
//               |
//              test  [context] kind [my_context]
//               |
//              Echo  [object]  kind [Object]
//

#include <iostream.h>
#include <echo.hh>


static CORBA::Boolean bindObjectToName(CORBA::ORB_ptr, CORBA::Object_ptr);

class Echo_i : public POA_Echo,
	       public PortableServer::RefCountServantBase
{
public:
  inline Echo_i() {}
  virtual ~Echo_i() {}
  virtual char* echoString(const char* mesg);
};

char* Echo_i::echoString(const char* mesg)
{
  return CORBA::string_dup(mesg);
}

//////////////////////////////////////////////////////////////////////

int
main(int argc, char **argv)
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    CORBA::Object_var obj = orb->resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    Echo_i* myecho = new Echo_i();

    PortableServer::ObjectId_var myechoid = poa->activate_object(myecho);

    // Obtain a reference to the object, and register it in
    // the naming service.
    obj = myecho->_this();
    if( !bindObjectToName(orb, obj) )
      return 1;

    myecho->_remove_ref();

    PortableServer::POAManager_var pman = poa->the_POAManager();
    pman->activate();

    orb->run();
    orb->destroy();
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}

//////////////////////////////////////////////////////////////////////

static CORBA::Boolean
bindObjectToName(CORBA::ORB_ptr orb, CORBA::Object_ptr objref)
{
  CosNaming::NamingContext_var rootContext;

  try {
    // Obtain a reference to the root context of the Name service:
    CORBA::Object_var obj;
    obj = orb->resolve_initial_references("NameService");

    // Narrow the reference returned.
    rootContext = CosNaming::NamingContext::_narrow(obj);
    if( CORBA::is_nil(rootContext) ) {
      cerr << "Failed to narrow the root naming context." << endl;
      return 0;
    }
  }
  catch(CORBA::ORB::InvalidName& ex) {
    // This should not happen!
    cerr << "Service required is invalid [does not exist]." << endl;
    return 0;
  }

  try {
    // Bind a context called "test" to the root context:

    CosNaming::Name contextName;
    contextName.length(1);
    contextName[0].id   = (const char*) "test";       // string copied
    contextName[0].kind = (const char*) "my_context"; // string copied
    // Note on kind: The kind field is used to indicate the type
    // of the object. This is to avoid conventions such as that used
    // by files (name.type -- e.g. test.ps = postscript etc.)

    CosNaming::NamingContext_var testContext;
    try {
      // Bind the context to root.
      testContext = rootContext->bind_new_context(contextName);
    }
    catch(CosNaming::NamingContext::AlreadyBound& ex) {
      // If the context already exists, this exception will be raised.
      // In this case, just resolve the name and assign testContext
      // to the object returned:
      CORBA::Object_var obj;
      obj = rootContext->resolve(contextName);
      testContext = CosNaming::NamingContext::_narrow(obj);
      if( CORBA::is_nil(testContext) ) {
        cerr << "Failed to narrow naming context." << endl;
        return 0;
      }
    }

    // Bind objref with name Echo to the testContext:
    CosNaming::Name objectName;
    objectName.length(1);
    objectName[0].id   = (const char*) "Echo";   // string copied
    objectName[0].kind = (const char*) "Object"; // string copied

    try {
      testContext->bind(objectName, objref);
    }
    catch(CosNaming::NamingContext::AlreadyBound& ex) {
      testContext->rebind(objectName, objref);
    }
    // Note: Using rebind() will overwrite any Object previously
    //       bound to /test/Echo with obj.
    //       Alternatively, bind() can be used, which will raise a
    //       CosNaming::NamingContext::AlreadyBound exception if
    //       the name supplied is already bound to an object.

    // Amendment: When using OrbixNames, it is necessary to first
    // try bind and then rebind, as rebind on it's own will throw
    // a NotFoundexception if the Name has not already been bound.
    // [This is incorrect behaviour -- it should just bind].
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to "
         << "contact the naming service." << endl;
    return 0;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught a CORBA::SystemException while using the "
         << "naming service." << endl;
    return 0;
  }
  return 1;
}
\end{cxxlisting}


\clearpage
\subsection{eg3\_clt.cc}

\begin{cxxlisting}
// eg3_clt.cc - This is the source code of example 3 used in Chapter 2
//              "The Basics" of the omniORB user guide.
//
//              This is the client. It uses the COSS naming service
//              to obtain the object reference.
//
// Usage: eg3_clt
//
//
//        On startup, the client lookup the object reference from the
//        COS naming service.
//
//        The name which the object is bound to is as follows:
//              root  [context]
//               |
//              text  [context] kind [my_context]
//               |
//              Echo  [object]  kind [Object]
//

#include <iostream.h>
#include <echo.hh>

static CORBA::Object_ptr getObjectReference(CORBA::ORB_ptr orb);

static void hello(Echo_ptr e)
{
  if( CORBA::is_nil(e) ) {
    cerr << "hello: The object reference is nil!\n" << endl;
    return;
  }

  CORBA::String_var src  = (const char*) "Hello!";
  CORBA::String_var dest = e->echoString(src);

  cerr << "I said, \"" << (char*)src << "\"." << endl
       << "The Echo object replied, \"" << (char*)dest <<"\"." << endl;
}

//////////////////////////////////////////////////////////////////////

int
main (int argc, char **argv) 
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    CORBA::Object_var obj = getObjectReference(orb);

    Echo_var echoref = Echo::_narrow(obj);
    hello(echoref);

    orb->destroy();
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to "
         << "contact the object." << endl;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}

//////////////////////////////////////////////////////////////////////

static CORBA::Object_ptr
getObjectReference(CORBA::ORB_ptr orb)
{
  CosNaming::NamingContext_var rootContext;
  
  try {
    // Obtain a reference to the root context of the Name service:
    CORBA::Object_var obj;
    obj = orb->resolve_initial_references("NameService");

    // Narrow the reference returned.
    rootContext = CosNaming::NamingContext::_narrow(obj);
    if( CORBA::is_nil(rootContext) ) {
      cerr << "Failed to narrow the root naming context." << endl;
      return CORBA::Object::_nil();
    }
  }
  catch(CORBA::ORB::InvalidName& ex) {
    // This should not happen!
    cerr << "Service required is invalid [does not exist]." << endl;
    return CORBA::Object::_nil();
  }

  // Create a name object, containing the name test/context:
  CosNaming::Name name;
  name.length(2);

  name[0].id   = (const char*) "test";       // string copied
  name[0].kind = (const char*) "my_context"; // string copied
  name[1].id   = (const char*) "Echo";
  name[1].kind = (const char*) "Object";
  // Note on kind: The kind field is used to indicate the type
  // of the object. This is to avoid conventions such as that used
  // by files (name.type -- e.g. test.ps = postscript etc.)

  try {
    // Resolve the name to an object reference.
    return rootContext->resolve(name);
  }
  catch(CosNaming::NamingContext::NotFound& ex) {
    // This exception is thrown if any of the components of the
    // path [contexts or the object] aren't found:
    cerr << "Context not found." << endl;
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to "
         << "contact the naming service." << endl;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught a CORBA::SystemException while using the "
         << "naming service." << endl;
  }
  return CORBA::Object::_nil();
}
\end{cxxlisting}


\clearpage
\subsection{eg3\_tieimpl.cc}

\begin{cxxlisting}
// eg3_tieimpl.cc - This example is similar to eg3_impl.cc except that
//                  the tie implementation skeleton is used.
//
//               This is the object implementation.
//
// Usage: eg3_tieimpl
//
//        On startup, the object reference is registered with the 
//        COS naming service. The client uses the naming service to
//        locate this object.
//
//        The name which the object is bound to is as follows:
//              root  [context]
//               |
//              test  [context] kind [my_context]
//               |
//              Echo  [object]  kind [Object]
//

#include <iostream.h>
#include <echo.hh>

static CORBA::Boolean bindObjectToName(CORBA::ORB_ptr,CORBA::Object_ptr);

// This is the object implementation.  Notice that it does not
// inherit from any stub class.

class Echo_i {
public:
  inline Echo_i() {}
  inline ~Echo_i() {}
  virtual char* echoString(const char* mesg);
};

char* Echo_i::echoString(const char* mesg)
{
  return CORBA::string_dup(mesg);
}

//////////////////////////////////////////////////////////////////////

int main(int argc, char** argv)
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    CORBA::Object_var obj = orb->resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    // Note that the <myecho> object is constructed on the stack here.
    // This is because tie implementations do not inherit from the
    // PortableServer::RefCountServantBase mixin class -- and so are
    // not automatically deleted by the POA.
    //  However, it will delete its implementation (myimpl) when it
    // it itself destroyed (when it goes out of scope).  It is
    // essential however to ensure that such objects are not deleted
    // whilst still activated.
    Echo_i* myimpl = new Echo_i();
    POA_Echo_tie<Echo_i> myecho(myimpl);

    PortableServer::ObjectId_var myechoid = poa->activate_object(&myecho);

    // Obtain a reference to the object, and register it in
    // the naming service.
    obj = myecho._this();
    if( !bindObjectToName(orb, obj) )
      return 1;

    PortableServer::POAManager_var pman = poa->the_POAManager();
    pman->activate();

    orb->run();
    orb->destroy();
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}

//////////////////////////////////////////////////////////////////////

static CORBA::Boolean
bindObjectToName(CORBA::ORB_ptr orb, CORBA::Object_ptr objref)
{
  CosNaming::NamingContext_var rootContext;

  try {
    // Obtain a reference to the root context of the Name service:
    CORBA::Object_var obj;
    obj = orb->resolve_initial_references("NameService");

    // Narrow the reference returned.
    rootContext = CosNaming::NamingContext::_narrow(obj);
    if( CORBA::is_nil(rootContext) ) {
      cerr << "Failed to narrow the root naming context." << endl;
      return 0;
    }
  }
  catch(CORBA::ORB::InvalidName& ex) {
    // This should not happen!
    cerr << "Service required is invalid [does not exist]." << endl;
    return 0;
  }

  try {
    // Bind a context called "test" to the root context:

    CosNaming::Name contextName;
    contextName.length(1);
    contextName[0].id   = (const char*) "test";       // string copied
    contextName[0].kind = (const char*) "my_context"; // string copied
    // Note on kind: The kind field is used to indicate the type
    // of the object. This is to avoid conventions such as that used
    // by files (name.type -- e.g. test.ps = postscript etc.)

    CosNaming::NamingContext_var testContext;
    try {
      // Bind the context to root.
      testContext = rootContext->bind_new_context(contextName);
    }
    catch(CosNaming::NamingContext::AlreadyBound& ex) {
      // If the context already exists, this exception will be raised.
      // In this case, just resolve the name and assign testContext
      // to the object returned:
      CORBA::Object_var obj;
      obj = rootContext->resolve(contextName);
      testContext = CosNaming::NamingContext::_narrow(obj);
      if( CORBA::is_nil(testContext) ) {
        cerr << "Failed to narrow naming context." << endl;
        return 0;
      }
    }

    // Bind objref with name Echo to the testContext:
    CosNaming::Name objectName;
    objectName.length(1);
    objectName[0].id   = (const char*) "Echo";   // string copied
    objectName[0].kind = (const char*) "Object"; // string copied

    try {
      testContext->bind(objectName, objref);
    }
    catch(CosNaming::NamingContext::AlreadyBound& ex) {
      testContext->rebind(objectName, objref);
    }
    // Note: Using rebind() will overwrite any Object previously
    //       bound to /test/Echo with obj.
    //       Alternatively, bind() can be used, which will raise a
    //       CosNaming::NamingContext::AlreadyBound exception if
    //       the name supplied is already bound to an object.

    // Amendment: When using OrbixNames, it is necessary to first
    // try bind and then rebind, as rebind on it's own will throw
    // a NotFoundexception if the Name has not already been bound.
    // [This is incorrect behaviour -- it should just bind].
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to "
         << "contact the naming service." << endl;
    return 0;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught a CORBA::SystemException while using the "
         << "naming service." << endl;
    return 0;
  }
  return 1;
}
\end{cxxlisting}


\clearpage
\subsection{dir.mk}

\begin{makelisting}

CXXSRCS = eg1.cc eg2_impl.cc eg2_clt.cc eg3_impl.cc eg3_clt.cc

DIR_CPPFLAGS = $(CORBA_CPPFLAGS)

CORBA_INTERFACES = echo

ifdef OSF1
ifeq ($(notdir $(CXX)),cxx)
NoTieExample = 1
endif
endif

ifndef NoTieExample
# -Wbtp tells the compiler to generate tie implementation template
OMNIORB_IDL += -Wbtp
eg3_tieimpl = $(patsubst %,$(BinPattern),eg3_tieimpl)
endif

eg1        = $(patsubst %,$(BinPattern),eg1)
eg2_impl   = $(patsubst %,$(BinPattern),eg2_impl)
eg2_clt    = $(patsubst %,$(BinPattern),eg2_clt)
eg3_impl   = $(patsubst %,$(BinPattern),eg3_impl)
eg3_clt    = $(patsubst %,$(BinPattern),eg3_clt)

all:: $(eg1) $(eg2_impl) $(eg2_clt)  $(eg3_impl) $(eg3_clt) $(eg3_tieimpl)

clean::
	$(RM) $(eg1) $(eg2_impl) $(eg2_clt) $(eg3_impl) $(eg3_clt) \
		$(eg3_tieimpl)

export:: $(eg1) $(eg2_impl) $(eg2_clt) $(eg3_impl) $(eg3_clt) $(eg3_tieimpl)
	@(module="echoexamples"; $(ExportExecutable))

$(eg1): eg1.o $(CORBA_STATIC_STUB_OBJS) $(CORBA_LIB_DEPEND)
	@(libs="$(CORBA_LIB_NODYN)"; $(CXXExecutable))

$(eg2_impl): eg2_impl.o $(CORBA_STATIC_STUB_OBJS) $(CORBA_LIB_DEPEND)
	@(libs="$(CORBA_LIB_NODYN)"; $(CXXExecutable))

$(eg2_clt): eg2_clt.o $(CORBA_STATIC_STUB_OBJS) $(CORBA_LIB_DEPEND)
	@(libs="$(CORBA_LIB_NODYN)"; $(CXXExecutable))

$(eg3_impl): eg3_impl.o $(CORBA_STATIC_STUB_OBJS) $(CORBA_LIB_DEPEND)
	@(libs="$(CORBA_LIB_NODYN)"; $(CXXExecutable))

$(eg3_clt): eg3_clt.o $(CORBA_STATIC_STUB_OBJS) $(CORBA_LIB_DEPEND)
	@(libs="$(CORBA_LIB_NODYN)"; $(CXXExecutable))

ifndef NoTieExample
$(eg3_tieimpl): eg3_tieimpl.o $(CORBA_STATIC_STUB_OBJS) $(CORBA_LIB_DEPEND)
	@(libs="$(CORBA_LIB_NODYN)"; $(CXXExecutable))
endif
\end{makelisting}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{C++ language mapping}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Now that you are familiar with the basics, it is important to
familiarise yourself with the standard IDL to C++ language mapping.
The mapping is described in detail in~\cite{corba23-spec}. If you have
not done so, you should obtain a copy of the document and use that as
the programming guide to omniORB.

The specification is not an easy read. The alternative is to use one
of the books on CORBA programming that has begun to appear. For
instance, Henning and Vinoski's `Advanced CORBA Programming with
C++'~\cite{henning1999} includes many example code bits to illustrate
how to use the CORBA 2.3 C++ mapping.

\section{Incompatibilities with pre-2.8.0 releases}

Before 2.8.0, omniORB implemented the CORBA 2.0 C++ mapping. From
2.8.0 onwards, the mapping has been updated to CORBA 2.3.
Unfortunately, to comply with the CORBA 2.3 specification, it has been
necessary to change the semantics of a few APIs in a way that is
incompatible with older omniORB releases. The incompatible changes are
limited to:

\begin{enumerate}
\item The mapping for some out and inout argument types is different.

\item The extraction of string, object reference and typecode from an
Any has different ownership rules.

\item the DII interface now defaults to reporting a system exception
by raising a C++ exception, instead of returning the exception as an
environment value.

\end{enumerate}

The changes are minor and require minimal changes to the application
source code. The C++ compiler will complain about the first change.
\textbf{However, it is not possible to detect the old usage for
changes 2 and 3 at compile time. In particular, unmodified code that
uses the affected Any extraction operators will most certainly cause
runtime errors to occur.}

To smooth the transition from the old usage to the new, an omniORB
configuration variable
\code{omniORB::omniORB\_27\_CompatibleAnyExtraction} can be set to
revert the any extraction operators to the old semantics. More
information can be found in chapter~\ref{ch_any}.


\section{BOA compatibility}
\label{sec:BOAcompat}

If you use the \cmdline{-WbBOA} option to omniidl, it will generate
skeleton code with the same interface as the old omniORB 2 BOA
mapping, as well as code to be used with the POA. Note that since the
major problem with the BOA specification was that server code was not
portable between ORBs, it is unlikely that omniORB 3's BOA
compatibility will help you much if you are moving from a different
BOA-based ORB.

The BOA compatibility permits the majority of BOA code to compile
without difficulty. However, there are a number of constructs which
relied on omniORB 2 implementation details which no longer work.

\begin{itemize}

\item omniORB 2 did not use distinct types for object references and
servants, and often accepted a pointer to a servant when the CORBA
specification says it should only accept an object reference. Such
code will not compile under omniORB 3.

\item The reverse is true for \op{BOA::obj\_is\_ready}. It now only
works when passed a pointer to a servant object, not an object
reference. The more commonly used mechanism of calling
\code{\_obj\_is\_ready(boa)} on the servant object still works as
expected.

\item It used to be the case that the skeleton class for interface
\intf{I} (\type{\_sk\_I}) was derived from class \type{I}. This meant
that the names of any types declared in the interface were available
in the scope of the skeleton class. This is no longer true. If you
have an interface:

\begin{idllisting}
interface I {
  struct S {
    long a,b;
  };
  S op();
};
\end{idllisting}

\noindent then where before the implementation code might have been:

\begin{cxxlisting}
class I_impl : public virtual _sk_I {
  S op();  // _sk_I is derived from I
};
I::S I_impl::op() {
  S ret;
  // ...
}
\end{cxxlisting}

\noindent it is now necessary to fully qualify all uses of \type{S}:

\begin{cxxlisting}
class I_impl : public virtual _sk_I {
  I::S op(); // _sk_I is not derived from I
};
I::S I_impl::op() {
  I::S ret;
  // ...
}
\end{cxxlisting}


\item The proprietary omniORB 2 LifeCycle extensions are no longer
supported. All of the facilities it offered can be implemented with
the POA interfaces, and the \code{omniORB::LOCATION\_FORWARD}
exception (see section~\ref{sec:locationForward}). Code which used the
old interfaces will have to be rewritten.


\end{itemize}






%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Interoperable Naming Service}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{chap:ins}

omniORB 3 supports the Interoperable Naming Service (INS), which will
be part of CORBA 2.4. The following is a summary of the new facilities
described in the INS edited chapters document~\cite{inschapters}.

\section{Object URIs}

As well as accepting IOR-format strings, \op{ORB::string\_to\_object}
now also supports two new Uniform Resource Identifier
(URI)~\cite{rfc2396} formats, which can be used to specify objects in
a convenient human-readable form. The existing IOR-format strings are
now also considered URIs.

\subsection{corbaloc}

\corbauri{corbaloc} URIs allow you to specify object references which
can be contacted by IIOP, or found through
\op{ORB::resolve\_initial\_references}. To specify an IIOP object
reference, you use a URI of the form:

\begin{quote}
\corbauri{corbaloc:iiop:}<\textit{host}>\corbauri{:}<\textit{port}>%
\corbauri{/}<\textit{object key}>
\end{quote}

\noindent for example:

\begin{quote}
\corbauri{corbaloc:iiop:myhost.example.com:1234/MyObjectKey}
\end{quote}

\noindent which specifies an object with key `MyObjectKey' within a
process running on myhost.example.com listening on port 1234. Object
keys containing non-ASCII characters can use the standard URI \%
escapes:

\begin{quote}
\corbauri{corbaloc:iiop:myhost.example.com:1234/My}%
\texttt{\%}%
\corbauri{efObjectKey}
\end{quote}

\noindent denotes an object key with the value 239 (hex ef) in the
third octet.

The protocol name `\corbauri{iiop}' can be abbreviated to the empty
string, so the original URI can be written:

\begin{quote}
\corbauri{corbaloc::myhost.example.com:1234/MyObjectKey}
\end{quote}

\noindent The IANA has assigned port number 2809\footnote{Not 2089 as
printed in \cite{inschapters}!} for use by \corbauri{corbaloc}, so if
the server is listening on that port, you can leave the port number
out.  The following two URIs refer to the same object:

\begin{quote}
\corbauri{corbaloc::myhost.example.com:2809/MyObjectKey}\\
\corbauri{corbaloc::myhost.example.com/MyObjectKey}
\end{quote}

\noindent You can specify an object which is available at more than
one location by separating the locations with commas:

\begin{quote}
\corbauri{corbaloc::myhost.example.com,:localhost:1234/MyObjectKey}
\end{quote}

\noindent Note that you must restate the protocol for each address,
hence the `\corbauri{:}' before `\corbauri{localhost}'. It could
equally have been written `\corbauri{iiop:localhost}'.

You can also specify an IIOP version number, although omniORB only
supports IIOP 1.0 at present:

\begin{quote}
\corbauri{corbaloc::1.2@myhost.example.com/MyObjectKey}
\end{quote}

\vspace{\baselineskip}

\noindent Alternatively, to use \op{resolve\_initial\_references}, you
use a URI of the form:

\begin{quote}
\corbauri{corbaloc:rir:/NameService}
\end{quote}


\subsection{corbaname}
\label{sec:corbaname}

\corbauri{corbaname} URIs cause \op{string\_to\_object} to look-up a
name in a CORBA Naming service. They are an extension of the
\corbauri{corbaloc} syntax:

\begin{quote}
\corbauri{corbaname:}%
<\textit{corbaloc location}>%
\corbauri{/}%
<\textit{object key}>%
\corbauri{#}%
<\textit{stringified name}>
\end{quote}

\noindent for example:

\begin{quote}
\corbauri{corbaname::myhost/NameService#project/example/echo.obj}\\
\corbauri{corbaname:rir:/NameService#project/example/echo.obj}
\end{quote}

\noindent Note that the object found with the
\corbauri{corbaloc}-style portion must be of type
\intf{CosNaming::NamingContext}, or something derived from it. If the
object key (or \corbauri{rir} name) is `\corbauri{NameService}', it
can be left out:

\begin{quote}
\corbauri{corbaname::myhost#project/example/echo.obj}\\
\corbauri{corbaname:rir:#project/example/echo.obj}
\end{quote}

\noindent The stringified name portion can also be left out, in which
case the URI denotes the \intf{CosNaming::NamingContext} which would
have been used for a look-up:

\begin{quote}
\corbauri{corbaname::myhost.example.com}\\
\corbauri{corbaname:rir:}
\end{quote}

\noindent The first of these examples is the easiest way of specifying
the location of a naming service.


\section{Configuring resolve\_initial\_references}
\label{sec:insargs}

The INS adds two new command line arguments which provide a portable
way of configuring \op{ORB::resolve\_initial\_references}:


\subsection{ORBInitRef}

\cmdline{-ORBInitRef} takes an argument of the form
<\textit{ObjectId}>\cmdline{=}<\textit{ObjectURI}>. So, for example,
with command line arguments of:

\begin{quote}
\cmdline{-ORBInitRef NameService=corbaname::myhost.example.com}
\end{quote}

\noindent \code{resolve\_initial\_references("NameService")} will
return a reference to the object with key `NameService' available on
myhost.example.com, port 2809. Since IOR-format strings are considered
URIs, you can also say things like:

\begin{quote}
\cmdline{-ORBInitRef NameService=IOR:00ff...}
\end{quote}


\subsection{ORBDefaultInitRef}

\cmdline{-ORBDefaultInitRef} provides a prefix string which is used to
resolve otherwise unknown names. When
\op{resolve\_initial\_references} is unable to resolve a name which
has been specifically configured (with \cmdline{-ORBInitRef}), it
constructs a string consisting of the default prefix, a `\corbauri{/}'
character, and the name requested.  The string is then fed to
\op{string\_to\_object}. So, for example, with a command line of:

\begin{quote}
\cmdline{-ORBDefaultInitRef corbaloc::myhost.example.com}
\end{quote}

\noindent a call to \code{resolve\_initial\_references("MyService")}
will return the object reference denoted by
`\corbauri{corbaloc::myhost.example.com/MyService}'.

Similarly, a \corbauri{corbaname} prefix can be used to cause
look-ups in the naming service. Note, however, that since a
`\corbauri{/}' character is always added to the prefix, it is
impossible to specify a look-up in the root context of the naming
service---you have to use a sub-context, like:

\begin{quote}
\cmdline{-ORBDefaultInitRef corbaname::myhost.example.com\#services}
\end{quote}


\subsection{omniORB configuration file}

As an extension to the standard facilities of the INS, omniORB
supports configuration file entries named \texttt{ORBInitRef} and
\texttt{ORBDefaultInitRef}. The syntax is identical to the command
line arguments. \file{omniORB.cfg} might contain:

\begin{quote}
\begin{verbatim}
ORBInitRef NameService=corbaname::myhost.example.com
ORBDefaultInitRef corbaname:rir:#services
\end{verbatim}
\end{quote}


\subsection{Resolution order}

With all these options for specifying object references to be returned
by \op{resolve\_\dsc{}initial\_references}, it is important to
understand the order in which the options are tried. The resolution
order, as required by the CORBA specification, is:

\begin{enumerate}

\item Check for special names such as `\texttt{RootPOA}'\footnote{In
fact, a strict reading of the specification says that it should be
possible to override `\texttt{RootPOA}' etc.\ with
\cmdline{-ORBInitRef}, but since POAs are locality constrained that is
ridiculous.}.

\item Resolve with an \cmdline{-ORBInitRef} argument.

\item \label{itm:defaultgotcha} Resolve with the
\cmdline{-ORBDefaultInitRef} prefix, if present.

\item Resolve with an \texttt{ORBInitRef}
(or old-style \texttt{NAMESERVICE}) entry in the configuration file.

\item Resolve with the \texttt{ORBDefaultInitRef} entry in the
configuration file, if present.

\item Resolve with the deprecated \texttt{ORBInitialHost} boot agent.

\end{enumerate}


\noindent This order mostly has the expected consequences---in
particular that command line arguments override entries in the
configuration file.  However, you must be careful with the default
prefixes. Suppose you have configured a `\texttt{NameService}' entry
in the configuration file, and you specify a default prefix on the
command line with:

\begin{quote}
\cmdline{-ORBDefaultInitRef corbaname:rir:\#services}
\end{quote}

\noindent expecting unknown services to be looked up in the configured
naming service. Now, step~\ref{itm:defaultgotcha} above means that
\code{resolve\_initial\_references("MyService")} should be processed
with the steps:

\begin{enumerate}

\item Construct the URI `\corbauri{corbaname:rir:#services/MyService}'
and give it to \op{string\_to\_object}.

\item Resolve the first part of the \corbauri{corbaname} URI by
calling\\\code{resolve\_initial\_references("NameService")}.

\item Construct the URI
`\corbauri{corbaname:rir:#services/NameService}' and give it to
\op{string\_to\_object}.

\item Resolve the first part of the \corbauri{corbaname} URI by
calling\\\code{resolve\_initial\_references("NameService")}.

\item \dots\ and so on for ever\dots

\end{enumerate}


\noindent omniORB detects loops like this and throws either
\code{CORBA::ORB::InvalidName} if the loop started with a call to
\op{resolve\_initial\_references}, or \code{CORBA::\dsc{}BAD\_PARAM}
if it started with a call to \op{string\_to\_object}. To avoid the
problem you must either specify the \texttt{NameService} reference on
the command line, or put the \texttt{DefaultInitRef} in the
configuration file.



\section{omniNames}

\subsection{NamingContextExt}

omniNames now supports the \intf{CosNaming::NamingContextExt}
interface:

\begin{idllisting}
module CosNaming {
  interface NamingContextExt : NamingContext {
    typedef string StringName;
    typedef string Address;
    typedef string URLString;

    StringName  to_string(in Name n)        raises(InvalidName);
    Name        to_name  (in StringName sn) raises(InvalidName);

    exception InvalidAddress {};

    URLString   to_url(in Address addr, in StringName sn)
      raises(InvalidAddress, InvalidName);

    Object      resolve_str(in StringName n)
      raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
  };
};
\end{idllisting}

\op{to\_string} and \op{to\_name} convert from \type{CosNaming::Name}
sequences to flattened strings and vice-versa.  Note that calling
these operations involves remote calls to the naming service, so they
are not particularly efficient. You can use the omniORB specific local
\op{omniURI::nameToString} and \op{omniURI::\dsc{}stringToName}
functions instead.

A \type{CosNaming::Name} is stringified by separating name components
with `\texttt{/}' characters. The \code{kind} and \code{id} fields of
each component are separated by `\texttt{.}' characters. If the
\code{kind} field is empty, the representation has no trailing
`\texttt{.}'; if the \code{id} is empty, the representation starts
with a `\texttt{.}' character; if both \texttt{id} and \texttt{kind}
are empty, the representation is just a `\texttt{.}'. The backslash
`\texttt{\textbackslash}' is used to escape the meaning of
`\texttt{/}', `\texttt{.}' and `\texttt{\textbackslash}' itself.

\op{to\_url} takes a \corbauri{corbaloc} style address and key string
(but without the \corbauri{corbaloc:} part), and a stringified name,
and returns a \corbauri{corbaname} URI (incorrectly called a URL)
string, having properly escaped any invalid characters. The
specification does not make it clear whether or not the address string
should also be escaped by the operation; omniORB does not escape
it. For this reason, it is best to avoid calling \op{to\_url} if the
address part contains escapable characters.  omniORB provides the
equivalent local function \op{omniURI::addrAndNameToURI}.

\op{resolve\_str} is equivalent to calling \op{to\_name} followed by
the inherited \op{resolve} operation. There are no string-based
equivalents of the various bind operations.


\subsection{Use with corbaname}

To make it easy to use omniNames with \corbauri{corbaname} URIs, it
now starts with the default port of 2809, and an object key of
`\texttt{NameService}' for the root naming context. This is only
possible when it is started `fresh', rather than with a log file from
an older omniNames version.

If you have a previous omniNames log, configured to run on a different
port, and with a different object key for its root context, all is not
lost. If the root context's object key is not `\texttt{NameService}',
omniNames creates a forwarding agent with that key. Effectively, this
means that there are two object keys which refer to the root
context---`\texttt{NameService}' and whatever the original key was.

For the port number, there are two options. The first is to run
omniNames with a command line argument like:

\begin{quote}
\cmdline{omniNames -logdir /the/log/dir -ORBpoa\_iiop\_port 2809}
\end{quote}

\noindent This causes it to listen on both port 2809 \emph{and}
whatever port it listened on before. The disadvantage with this is
that the IORs to all naming contexts now contain two IIOP profiles,
one for each port, which, amongst other things, increases the size of
the omniNames log.

The second option is to use omniMapper, as described below.


\section{omniMapper}
\hyphenation{omni-Mapper}

omniMapper is a simple daemon which listens on port 2809 (or any other
port), and redirects IIOP requests for configured object keys to
associated persistent IORs. It can be used to make a naming service
(even an old non-INS aware version of omniNames or other ORB's naming
service) appear on port 2809 with the object key
`\texttt{NameService}'. The same goes for any other service you may
wish to specify, such as an interface repository. omniMapper is
started with a command line of:

\begin{quote}
\cmdline{omniMapper [-port }<\textit{port}>%
\cmdline{] [-config }<\textit{config file}>%
\cmdline{] [-v]}
\end{quote}

\noindent The \cmdline{-port} option allows you to choose a port other
than 2809 to listen on\footnote{You can also play the
\cmdline{-ORBpoa\_iiop\_port} trick to make it listen on more than one
port.}. The \cmdline{-config} option specifies a location for the
configuration file. The default name is \file{/etc/omniMapper.cfg}, or
%BEGIN LATEX
\file{C:\omniMapper.cfg}
%END LATEX
%HEVEA\verb|C:\omniMapper.cfg|
on Windows. omniMapper does not normally print anything; the
\cmdline{-v} option makes it verbose so it prints configuration
information and a record of the redirections it makes, to standard
output.

The configuration file is very simple. Each line contains a string to
be used as an object key, some white space, and an IOR (or any valid
URI) that it will redirect that object key to. Comments should be
prefixed with a `\texttt{\#}' character. For example:

\begin{quote}
\begin{verbatim}
# Example omniMapper.cfg
NameService         IOR:000f...
InterfaceRepository IOR:0100...
\end{verbatim}
\end{quote}

omniMapper can either be run on a single machine, in much the same way
as omniNames, or it can be run on \emph{every} machine, with a common
configuration file. That way, each machine's omniORB configuration
file could contain the line:

\begin{quote}
\begin{verbatim}
ORBDefaultInitRef corbaloc::localhost
\end{verbatim}
\end{quote}



\section{Creating objects with simple object keys}

In normal use, omniORB creates object keys containing various
information including POA names and various non-ASCII characters.
Since object keys are supposed to be opaque, this is not usually a
problem. The INS breaks this opacity and requires servers to create
objects with human-friendly keys.

If you wish to make your objects available with human-friendly URIs,
there are two options. The first is to use omniMapper as described
above, in conjunction with a \code{PERSISTENT} POA. The second is to
create objects with the required keys yourself. You do this with a
special POA with the name `\texttt{omniINSPOA}', acquired from
\op{resolve\_initial\_references}. This POA has the \code{USER\_ID}
and \code{PERSISTENT} policies, and the special property that the
object keys it creates contain only the object ids given to the POA,
and no other data. It is a normal POA in all other respects, so you
can activate/deactivate it, create children, and so on, in the usual
way.





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The IDL compiler}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{chap:omniidl}

omniORB 3 has a brand new IDL compiler, named omniidl. It consists of
a generic front-end parser written in C++, and a number of back-ends
written in Python. omniidl is very strict about IDL validity, so you
may find that it reports errors in IDL which compiles fine with
earlier versions of omniORB, and with other ORBs.

The general form of an omniidl command line is:

\begin{quote} % Not the clearest bit of mark-up ever... :-)
\cmdline{omniidl }[\textit{options}]\cmdline{ -b}%
<\textit{back-end}>\cmdline{ }[\textit{back-end options}]%
\cmdline{ }<\textit{file 1}>\cmdline{ }<\textit{file 2}>%
\cmdline{ }\dots
\end{quote}

\section{Common options}

The following options are common to all back-ends:

\begin{tabbing}
\cmdline{-D}\textit{name}[\cmdline{=}\textit{value}]~~ \= \kill
%HEVEA\\

\cmdline{-D}\textit{name}[\cmdline{=}\textit{value}]
     \> Define \textit{name} for the preprocessor.\\

\cmdline{-U}\textit{name}
     \> Undefine \textit{name} for the preprocessor.\\

\cmdline{-I}\textit{dir}
     \> Include \textit{dir} in the preprocessor search path.\\

\cmdline{-E}
     \> Only run the preprocessor, sending its output to stdout.\\

\cmdline{-Y}\textit{cmd}
     \> Use \textit{cmd} as the preprocessor, rather than the normal C
        preprocessor.\\

\cmdline{-N}
     \> Do not run the preprocessor.\\

\cmdline{-T}
     \> Use a temporary file, not a pipe, for preprocessor output.\\

\cmdline{-Wp}\textit{arg}[,\textit{arg}\dots]
     \> Send arguments to the preprocessor.\\

\cmdline{-b}\textit{back-end}
     \> Run the specified back-end. For the C++ ORB, use \cmdline{-bcxx}.\\

\cmdline{-Wb}\textit{arg}[,\textit{arg}\dots]
     \> Send arguments to the back-end.\\

\cmdline{-nf}
     \> Do not warn about unresolved forward declarations.\\

\cmdline{-k}
     \> Keep comments after declarations, to be used by some back-ends.\\

\cmdline{-K}
     \> Keep comments before declarations, to be used by some back-ends.\\

\cmdline{-C}\textit{dir}
     \> Change directory to \textit{dir} before writing output files.\\

\cmdline{-d}
     \> Dump the parsed IDL then exit, without running a back-end.\\

\cmdline{-p}\textit{dir}
     \> Use \textit{dir} as a path to find omniidl back-ends.\\

\cmdline{-V}
     \> Print version information then exit.\\

\cmdline{-u}
     \> Print usage information.\\

\cmdline{-v}
     \> Verbose: trace compilation stages.\\

\end{tabbing}

\noindent Most of these options are self explanatory, but some are not
so obvious.

\subsection{Preprocessor interactions}

IDL is processed by the C preprocessor before omniidl parses it.
Unlike the old IDL compiler, which used different C preprocessors on
different platforms, omniidl always uses the GNU C preprocessor (which
it builds with the name omnicpp). The \cmdline{-D}, \cmdline{-U}, and
\cmdline{-I} options are just sent to the preprocessor. Note that the
current directory is not on the include search path by default---use
`\cmdline{-I.}' for that. The \cmdline{-Y} option can be used to
specify a different preprocessor to omnicpp. Beware that line
directives inserted by other preprocessors are likely to confuse
omniidl.

\subsubsection{Windows 9x}

The output from the C preprocessor is normally fed to the omniidl
parser through a pipe. On some Windows 98 machines (but not all!)  the
pipe does not work, and the preprocessor output is echoed to the
screen. When this happens, the omniidl parser sees an empty file, and
produces useless stub files with strange long names. To avoid the
problem, use the `\cmdline{-T}' option to create a temporary file
between the two stages.


\subsection{Forward-declared interfaces}

If you have an IDL file like:

\begin{idllisting}
interface I;
interface J {
  attribute I the_I;
};
\end{idllisting}

\noindent then omniidl will normally issue a warning:

{\small
\begin{verbatim}
  test.idl:1: Warning: Forward declared interface `::I' was never
  fully defined
\end{verbatim}
}

\noindent It is illegal to declare such IDL in isolation, but it
\emph{is} valid to define interface \intf{I} in a separate file. If
you have a lot of IDL with this sort of construct, you will drown
under the warning messages. Use the \cmdline{-nf} option to suppress
them.


\subsection{Comments}

By default, omniidl discards comments in the input IDL. However, with
the \cmdline{-k} and \cmdline{-K} options, it preserves the comments
for use by the back-ends. The C++ back-end ignores this information,
but it is relatively easy to write new back-ends which \emph{do} make
use of comments.

The two different options relate to how comments are attached to
declarations within the IDL. Given IDL like:

\begin{idllisting}
interface I {
  void op1();
  // A comment
  void op2();
};
\end{idllisting}

\noindent the \cmdline{-k} flag will attach the comment to \op{op1};
the \cmdline{-K} flag will attach it to \op{op2}.



\section{C++ back-end options}

When you specify the C++ back-end (with \cmdline{-bcxx}), the
following \cmdline{-Wb} options are available. Note that the
\cmdline{-Wb} options must be specified \emph{after} the
\cmdline{-bcxx} option, so omniidl knows which back-end to give the
arguments to.

\begin{tabbing}
\cmdline{-Wbsplice-modules}~~ \= \kill
%HEVEA\\

\cmdline{-Wbh=}\textit{suffix}
     \> Use \textit{suffix} for generated header files. Default
        `\file{.hh}'.\\

\cmdline{-Wbs=}\textit{suffix}
     \> Use \textit{suffix} for generated stub files. Default
        `\file{SK.cc}.'\\

\cmdline{-Wbd=}\textit{suffix}
     \> Use \textit{suffix} for generated dynamic files. Default
        `\file{DynSK.cc}.'\\

\cmdline{-Wba}
     \> Generate stubs for TypeCode and Any.\\

\cmdline{-Wbtp}
     \> Generate `tie' implementation skeletons.\\

\cmdline{-Wbtf}
     \> Generate flattened `tie' implementation skeletons.\\

\cmdline{-Wbsplice-modules}
     \> Splice together multiply-opened modules into one.\\

\cmdline{-Wbexample}
     \> Generate example implementation code.\\

\cmdline{-WbF}
     \> Generate code fragments (for experts only).\\

\cmdline{-WbBOA}
     \> Generate BOA compatible skeletons.\\

\cmdline{-Wbold}
     \> Generate old CORBA 2.1 signatures for skeletons.\\

\cmdline{-Wbold\_prefix}
     \> Map C++ reserved words with prefix `\code{\_}' rather than
        `\code{\_cxx\_}'.\\

\cmdline{-Wbkeep\_inc\_path}
     \> Preserve IDL `\code{\#include}' paths in generated
       	`\code{\#include}' directives.\\

\cmdline{-Wbuse\_quotes}
     \> Use quotes in `\code{\#include}' directives 
        (e.g.\ \code{"foo"} rather than \code{<foo>}.)\\



\end{tabbing}

\noindent Again, most of these are self-explanatory.


\subsection{Module splicing}

On C++ compilers without namespace support, IDL modules map to C++
classes, and so cannot be reopened. For some IDL, it is possible to
`splice' reopened modules on to the first occurrence of the module, so
all module definitions are in a single class. It is possible in this
sort of situation:

\begin{idllisting}
module M1 {
  interface I {};
};
module M2 {
  interface J {
    attribute M1::I ok;
  };
};
module M1 {
  interface K {
    attribute I still_ok;
  };
};
\end{idllisting}

\noindent but not if there are cross-module dependencies:

\begin{idllisting}
module M1 {
  interface I {};
};
module M2 {
  interface J {
    attribute M1::I ok;
  };
};
module M1 {
  interface K {
    attribute M2::J oh_dear;
  };
};
\end{idllisting}

\noindent In both of these cases, the \cmdline{-Wbsplice-modules}
option causes omniidl to put all of the definitions for module
\intf{M1} into a single C++ class. For the first case, this will work
fine. For the second case, class \type{M1::K} will contain a reference
to \type{M2::J}, which has not yet been defined; the C++ compiler will
complain.


\subsection{Flattened tie classes}

Another problem with mapping IDL modules to C++ classes arises with
tie templates. The C++ mapping says that for the interface
\intf{M::I}, the C++ tie template class should be named
\type{POA\_M::I\_tie}. However, since template classes cannot be
declared inside other classes, this naming scheme cannot be used with
compilers without namespace support.

The standard solution is to produce `flattened' tie class names, using
the \cmdline{-Wbtf} command line argument. With that flag, the
template class is declared at global scope with the name
\type{POA\_M\_I\_tie}. i.e.\ all occurrences of `\type{::}' are
replaced by `\type{\_}'.


\subsection{Generating example implementations}

If you use the \cmdline{-Wbexample} flag, omniidl will generate an
example implementation file as well as the stubs and skeletons. For
IDL file \file{foo.idl}, the example code is written to
\file{foo_i.cc}. The example file contains class and method
declarations for the operations of all interfaces in the IDL file,
along with a \op{main} function which creates an instance of each
object. You still have to fill in the operation implementations, of
course.



\section{Examples}

Generate the C++ headers and stubs for a file \file{a.idl}:

\begin{quote}
\cmdline{omniidl -bcxx a.idl}
\end{quote}

\noindent Generate with Any support:

\begin{quote}
\cmdline{omniidl -bcxx -Wba a.idl}
\end{quote}

\noindent Compile two files with Any support:

\begin{quote}
\cmdline{omniidl -bcxx -Wba a.idl b.idl}
\end{quote}

\noindent As above, but also generate Python stubs for the files
(assuming omniORBpy is installed):

\begin{quote}
\cmdline{omniidl -bcxx -Wba -bpython a.idl b.idl}
\end{quote}

\noindent Just check the IDL files for validity, generating no output:

\begin{quote}
\cmdline{omniidl a.idl b.idl}
\end{quote}





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The omniORB API}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{omniORBapi}

In this chapter, we introduce the omniORB API. The purpose of this API
is to provide access points to omniORB specific functionality that is
not covered by the CORBA specification.  Obviously, if you use this
API in your application, that part of your code is not going to be
portable to run unchanged on other vendors' ORBs. To make it easier to
identify omniORB dependent code, this API is defined under the name
space `\code{omniORB}'\footnote{\code{omniORB} is a class name if the
C++ compiler does not support the \code{namespace} keyword.}.

\section{ORB initialisation options}
\label{omniorbapioptions}

\op{CORBA::ORB\_init} accepts the following standard command-line
arguments:

\begin{tabbing}
\cmdline{-ORBclientCallTimeOutPeriod }<\textit{0--max integer}> \=\kill
%HEVEA\\

\cmdline{-ORBid omniORB3} \> The identifier must be `omniORB3'.\\

\cmdline{-ORBInitRef }<\textit{ObjectId}>=<\textit{ObjectURI}>
                          \> See section~\ref{sec:insargs}.\\

\cmdline{-ORBDefaultInitRef }<\textit{Default URI}>
                          \> See section~\ref{sec:insargs}.
\end{tabbing}


\noindent and the following omniORB-specific arguments:

\begin{tabbing}
\cmdline{-ORBclientCallTimeOutPeriod }<\textit{0--max integer}> \=\kill
%HEVEA\\

\cmdline{-ORBtraceLevel }<\textit{level}>\> See section~\ref{rttrace}.\\

\cmdline{-ORBtraceInvocations}           \> See section~\ref{rttrace}.\\

\cmdline{-ORBstrictIIOP}                 \> See section~\ref{sec:strictIIOP}.\\

\cmdline{-ORBtcAliasExpand }<\textit{0 or 1}>
                                         \> See section~\ref{anyOmniORB}.\\

\cmdline{-ORBgiopMaxMsgSize }<\textit{size in bytes}>
                                         \> See section~\ref{giopmsg}.\\

\cmdline{-ORBobjectTableSize }<\textit{number of entries}>
                                         \> See section~\ref{sec:objtable}.\\

\cmdline{-ORBserverName }<\textit{string}>
                                         \> See section~\ref{sec_servername}.\\

\cmdline{-ORBno\_bootstrap\_agent}       \> See section~\ref{bootstrap}.\\

\cmdline{-ORBdiiThrowsSysExceptions }<\textit{0 or 1}>
                                         \> See section~\ref{dii_invoke}.\\

\cmdline{-ORBabortOnInternalError }<\textit{0 or 1}>
                                         \> See section~\ref{sec_fatal}.\\

\cmdline{-ORBverifyObjectExistsAndType }<\textit{0 or 1}>
                                         \> See section~\ref{sec_lcd}.\\

\cmdline{-ORBinConScanPeriod }<\textit{0--max integer}>
                                         \> See section~\ref{sec_shut}.\\

\cmdline{-ORBoutConScanPeriod }<\textit{0--max integer}>
                                         \> See section~\ref{sec_shut}.\\

\cmdline{-ORBclientCallTimeOutPeriod }<\textit{0--max integer}>
                                         \> See section~\ref{sec_shut}.\\

\cmdline{-ORBserverCallTimeOutPeriod }<\textit{0--max integer}>
                                         \> See section~\ref{sec_shut}.\\

\cmdline{-ORBscanGranularity }<\textit{0--max integer}>
                                         \> See section~\ref{sec_shut}.\\

\cmdline{-ORBlcdMode}                    \> See section~\ref{sec_lcd}.\\

\cmdline{-ORBpoa\_iiop\_port }<\textit{port no.}>
                                         \> See section~\ref{sec:nameport}.\\

\cmdline{-ORBpoa\_iiop\_name\_port }<\textit{hostname}[\textit{:port no.]}>
                                         \> See section~\ref{sec:nameport}.\\

\cmdline{-ORBhelp}                     \> Lists all ORB command line options.

\end{tabbing}

\noindent and these two obsolete omniORB-specific arguments:

\begin{tabbing}
\cmdline{-ORBclientCallTimeOutPeriod }<\textit{0--max integer}> \=\kill
%HEVEA\\

\cmdline{-ORBInitialHost }<\textit{string}>
                                         \> See section~\ref{bootstrap}.\\

\cmdline{-ORBInitialPort }<\textit{1--65535}>]
                                         \> See section~\ref{bootstrap}.

\end{tabbing}


\noindent As defined in the CORBA specification, any command-line
arguments understood by the ORB will be removed from \code{argv} when
the initialisation functions return. Therefore, an application is not
required to handle any command-line arguments it does not understand.



\section{Hostname and port}
\label{sec:nameport}

Normally, omniORB lets the operating system pick which port number it
should use to listen for IIOP calls. Alternatively, you can specify a
particular port using \cmdline{-ORBpoa\_iiop\_port}. If you specify
\cmdline{-ORBpoa\_iiop\_port} more than once, omniORB will listen on
all the ports you specify.

By default, the ORB can work out the IP address of the host machine.
This address is recorded in the object references of the local
objects. However, when the host has multiple network interfaces and
multiple IP addresses, it may be desirable for the application to
control what address the ORB should use. This can be done by defining
the environment variable \code{OMNIORB\_USEHOSTNAME} to contain the
preferred host name or IP address in dot-numeric form. Alternatively,
the same can be achieved using the \cmdline{-ORBpoa\_iiop\_name\_port}
option. You can optionally specify a port number too. Again, you can
specify more than one host name by using
\cmdline{-ORBpoa\_iiop\_name\_port} more than once.


\section{Run-time Tracing and Diagnostic Messages}
\label{rttrace}

omniORB can output tracing and diagnostic messages to the standard
error stream. To avoid conflicts between old-style \file{iostream.h}
and new-style \file{iostream}, omniORB uses neither. Some or all of
these messages can be turned {on/off} by setting the variable
\code{omniORB::traceLevel}. The type definition of the variable is:

\begin{cxxlisting}
CORBA::ULong omniORB::traceLevel = 1; // The default value is 1
\end{cxxlisting}

\noindent At the moment, the following trace levels are defined:

\vspace{\baselineskip}

\begin{tabular}{lp{.6\textwidth}}
%HEVEA\\

level 0      & turn off all tracing and informational messages\\
level 1      & informational messages only\\
level 2      & the above plus configuration information\\

level 5      & the above plus notifications when server threads are
               created or communication endpoints are shutdown\\

level 10--20 & the above plus execution and exception traces\\

level 25     & the above plus hex dumps of all data sent and received
               by the ORB via its network connections.\\
\end{tabular}

\vspace{\baselineskip}

\noindent The variable can be changed by assignment inside your
applications. It can also be changed by specifying the command-line
option: \cmdline{-ORBtraceLevel }<\textit{level}>. For instance:

\begin{verbatim}
$ eg2_impl -ORBtraceLevel 5
\end{verbatim}

%$ To fix Emacs' syntax highlighting

New in omniORB 3, you can also trace operation invocations by setting
\code{omniORB::traceInvocations} to true, or with the
\cmdline{-ORBtraceInvocations} command line argument.



\section{Server Name}
\label{sec_servername}

Applications can optionally specify a name to identify the server
process. At the moment, this name is only used by the host-based
access control module. See section~\ref{sec_accept} for details. The
name is stored in the variable \code{omniORB::serverName}.

\begin{cxxlisting}
CORBA::String_var omniORB::serverName;
\end{cxxlisting}

\noindent The variable can be changed by assignment inside your
applications. It can also be changed by specifying the command-line
option: \cmdline{-ORBserverName }<\textit{string}>.
 

\section{GIOP Message Size}
\label{giopmsg}

omniORB sets a limit on the GIOP message size that can be sent or
received. The value can be obtained by calling:

\begin{cxxlisting}
size_t omniORB::MaxMessageSize();
\end{cxxlisting}

\noindent and can be changed by:

\begin{cxxlisting}
void omniORB::MaxMessageSize(size_t newvalue);
\end{cxxlisting}

\noindent or by the command-line option \cmdline{-ORBgiopMaxMsgSize}.
The exact value is somewhat arbitrary. The reason such a limit exists
is to provide some way to protect the server side from resource
exhaustion. Think about the case when the server receives a rogue
GIOP(IIOP) request message that contains a sequence length field set
to 2$^{31}$. With a reasonable message size limit, the server can
reject this rogue message straight away.


\section{Object table size}
\label{sec:objtable}

omniORB uses a hash table to store the mapping from object keys to
servant objects. Normally, it dynamically re-sizes the hash table when
it becomes too full or too empty. This is the most efficient trade-off
between performance and memory usage. However, since all POA
operations which add or remove objects from the table can (very
occasionally) cause the object table to resize, the time spent in POA
operations is much less predictable than if the table size was fixed.

To prevent omniORB from resizing its object table, set the variable
\code{omniORB::\dsc{}objectTableSize} to the number of hash table
entries you require \emph{before} calling \op{CORBA::\dsc{}ORB\_init}.
Alternatively, use the \cmdline{-ORBobjectTableSize} argument. Note
that omniORB uses an open hash table so you can have any number of
objects active, no matter what size table you specify. If you have
many more active objects than hash table entries, object look-up
performance will become linear with the number of objects.


\section{POA request holding timeout}

POAs can be put into the \term{holding} state, which means that
incoming requests are queued until the POA is set to a different
state. Normally, queued requests are held for ever (or until the
client times out as described in section~\ref{sec_shut}). If you set
\code{omniORB::poaHoldRequestTimeout} to a non-zero time in seconds,
held requests will be cancelled after that time. When requests are
cancelled in this way, the caller is sent a \code{TRANSIENT}
exception.



\section{Obsolete Initial Object Reference Bootstrapping}
\label{bootstrap}

Starting from 2.6.0, but superseded by the Interoperable Naming
Service in omniORB 3, a mechanism is available for the ORB runtime to
obtain the initial object references to CORBA services. The bootstrap
service is a special object with the object key `INIT' and the
following interface\footnote{This interface was first defined by Sun's
NEO and is in used in Sun's JavaIDL.}:

\begin{idllisting}
  // IDL
  module CORBA {
    interface InitialReferences {
      Object get(in ORB::ObjectId id);
      // returns the initial object reference of the service
      // identified by <id>. For example the id for the
      // Naming service is "NameService".

      ORB::ObjectIdList list();
      // returns the list of service ids that this agent knows
   };
 };
\end{idllisting}

By default, all omniORB servers contain an instance of this object and
are able to respond to remote invocations. To prevent the ORB from
instantiating this object, the command-line option
\cmdline{-ORBno\_bootstrap\_agent} should be specified.

In particular, the Naming Service omniNames is able to respond to a
query through this interface and return the object reference of its
root context. In effect, the bootstrap agent provides a level of
indirection.  All omniORB clients still have to be supplied with the
address of the bootstrap agent. However, the information is much
easier to specify than a stringified IOR!  Another advantage of this
approach is that it is completely compatible with JavaIDL. This makes
it possible for programs written for JavaIDL to share a Naming
Service with omniORB.

The address of the bootstrap agent is given by the
\texttt{ORBInitialHost} and \texttt{ORBInitialPort} parameter in the
omniORB configuration file (section~\ref{setup}). The parameters can
also be specified as command-line options
(section~\ref{omniorbapioptions}). The parameter
\texttt{ORBInitialPort} is optional. If it is not specified, port
number 900 will be used.

During initialisation, the ORB reads the parameters in the omniORB
configuration file. If the parameter \texttt{NAMESERVICE} is
specified, the stringified IOR is used as the object reference of the
root naming context. If the parameter is absent and the parameter
\texttt{ORBInitialHost} is present, the ORB contacts the bootstrap
agent at the address specified to obtain the root naming context when
the application calls \op{resolve\_initial\_references}. If neither is
present, \op{resolve\_\dsc{}initial\_references} returns a nil object
reference. Finally, the command line argument
\cmdline{-ORBInitialHost} overrides any parameters in the
configuration file. The ORB always contacts the bootstrap agent at the
address specified to obtain the root naming context.

Now we are ready to describe a simple way to set up omniNames.

\begin{enumerate}
\item Start omniNames for the first time on a machine (e.g. wobble):

{\tt \$ omniNames -start 1234}

\item Add to omniORB.cfg:

{\tt ORBInitialHost wobble}

{\tt ORBInitialPort 1234}

\item All omniORB applications will now be able to contact omniNames.

Alternatively, the command line options can be used, for example:

{\tt \$ eg3\_impl -ORBInitialHost wobble -ORBInitialPort 1234 \&}

{\tt \$ eg3\_clt -ORBInitialHost wobble -ORBInitialPort 1234}

\end{enumerate}




\section{GIOP Lowest Common Denominator Mode}
\label{sec_lcd}
\label{sec:strictIIOP}

Sometimes, to cope with bugs in another ORB, it is necessary to
disable various GIOP and IIOP features in order to achieve
interoperability. If the command line option \cmdline{-ORBlcdMode} is
present or the function \op{omniORB::enableLcdMode} is called, the ORB
enters the so-called `lowest common denominator mode'. It bends over
backwards to cope with bugs in the ORB at the other end. This is
purely a transitional measure. The long term solution is to report the
bugs to the other vendors and ask them to fix them expediently.

In some (sloppy) IIOP implementations, the message size value in the
IIOP header can be larger than the actual body size, i.e.\ there is
garbage at the end. As the spec does not say the message size must
match the body size exactly, this is not a clear violation of the
spec. omniORB's default policy is to expect incoming messages to be
formatted properly. Any messages that have garbage at the end will be
rejected.

\cmdline{-ORBlcdMode} and \op{omniORB::enableLcdMode} set omniORB to
silently skip the unread part of such invalid messages. Alternatively,
you can just change this policy with the \cmdline{-ORBstrictIIOP 0}
command line, or by setting \code{omniORB::\dsc{}strictIIOP} to zero.
The problem with doing this is that the header message size may
actually be garbage, caused by a bug in the sender's code. The
receiving thread may block forever as it tries to read more data from
the connection. In this case the sender won't send any more as it
thinks it has marshalled in all the data.

By default, omniORB uses the GIOP LOCATE\_REQUEST message to verify
the existence of an object prior to the first invocation. If another
vendor's ORB is known not to be able to handle this GIOP message, set
the variable \code{omniORB::\dsc{}verifyObjectExistsAndType} to 0 to
disable this feature, and hence achieve interoperability. The command
line option \cmdline{-ORBverifyObjectExistsAndType} has the same
effect.


\section{GIOP Requesting Principal field}

In versions 1.0 and 1.1 of the GIOP specification, request messages
contain a `principal' field which was intended to identify the client.
The meaning of the principal field was never specified, and its use is
now deprecated. The field is not present in GIOP 1.2. omniORB normally
uses the string `\texttt{nobody}' in the principal field. However,
some systems (e.g.\ the GNOME desktop environment) use the principal
field as an authentication mechanism, so omniORB allows you to
configure the principal by setting the \envvar{OMNIORB_PRINCIPAL}
environment variable.


\section{Trapping omniORB Internal Errors}
\label{sec_fatal}

\begin{cxxlisting}
class fatalException {
public:
    const char *file() const;
    int line() const;
    const char *errmsg() const;
};
\end{cxxlisting}

When omniORB detects an internal problem that is most likely to be
caused by a bug in the runtime, it raises the exception
\type{omniORB::fatalException}.  When this exception is raised, it is
not sensible to proceed with any operation that involves the ORB's
runtime. It is best to exit the program immediately. The exception
structure carried by \type{omniORB::fatalException} contains the exact
location (the file name and the line number) where the exception is
raised. You are strongly encouraged to file a bug report and point out
the location.

It may help to cause a core-dump and look at the stack trace to locate
where the exception was thrown. This can be done by setting the
variable \code{omniORB::\dsc{}abortOnInternalError} to 1. The variable
can also be set via the command line option
\cmdline{-ORBabortOnInternalError}.

\mbox{}



\section{System Exception Handlers}

By default, all system exceptions which are raised during an operation
invocation, with the exception of \code{CORBA::TRANSIENT}, are
propagated to the application code. Some applications may prefer to
trap these exceptions within the proxy objects so that the application
logic does not have to deal with the error condition. For example,
when a \code{CORBA::COMM\_FAILURE} is received, an application may
just want to retry the invocation until it finally succeeds. This
approach is useful for objects that are persistent and their
operations are idempotent.

omniORB provides a set of functions to install exception handlers.
Once they are installed, proxy objects will call these handlers when
the associated system exceptions are raised by the ORB runtime.
Handlers can be installed for \code{CORBA::\dsc{}TRANSIENT},
\code{CORBA::COMM\_FAILURE} and \code{CORBA::SystemException}.  This
last handler covers all system exceptions other than the two covered
by the first two handlers. An exception handler can be installed for
individual proxy objects, or it can be installed for all proxy objects
in the address space.


\subsection{CORBA::TRANSIENT handlers}

When a \code{CORBA::TRANSIENT} exception is raised by the ORB runtime,
the default behaviour of the proxy objects is to retry indefinitely
until the operation succeeds. Successive retries will be delayed
progressively by multiples of
\code{omniORB::\dsc{}defaultTransientRetryDelayIncrement}. The delay
will be limited to the maximum specified by
\code{omniORB::defaultTransientRetryDelayMaximum}. The unit of both
values are in seconds.

The ORB runtime will raise \code{CORBA::TRANSIENT} under the following
conditions:

\begin{enumerate}

\item When a \emph{cached} network connection is broken while an
operation invocation is in progress. The ORB will try to open a new
connection at the next invocation.

\item When the proxy object has been redirected by a location forward
message by the remote object to a new location and the object at the
new location cannot be contacted. In addition to the
\code{CORBA::TRANSIENT} exception, the proxy object also resets its
internal state so that the next invocation will be directed at the
original location of the remote object.

\item When the remote object reports \code{CORBA::TRANSIENT}.

\end{enumerate}

Applications can override the default behaviour by installing their
own exception handler. The API to do so is summarised below:

\begin{cxxlisting}
class omniORB {
public:
  
typedef CORBA::Boolean (*transientExceptionHandler_t)(void* cookie,
                                                CORBA::ULong n_retries,
                                                const CORBA::TRANSIENT& ex);

static void installTransientExceptionHandler(void* cookie,
                                             transientExceptionHandler_t fn);

static void installTransientExceptionHandler(CORBA::Object_ptr obj,
                                             void* cookie,
                                             transientExceptionHandler_t fn);
  
static CORBA::ULong defaultTransientRetryDelayIncrement;
static CORBA::ULong defaultTransientRetryDelayMaximum;
}
\end{cxxlisting}

The overloaded function \op{installTransientExceptionHandler} can be
used to install the exception handlers for \code{CORBA::TRANSIENT}.
Two forms are available: the first form installs an exception handler
for all object references except for those which have an exception
handler installed by the second form, which takes an additional
argument to identify the target object reference. The argument
\code{cookie} is an opaque pointer which will be passed on by the ORB
when it calls the exception handler.

An exception handler will be called by proxy objects with three
arguments. The \code{cookie} is the opaque pointer registered by
\op{installTransientExceptionHandler}. The argument \code{n\_retries}
is the number of times the proxy has called this handler for the same
invocation. The argument \code{ex} is the value of the exception
caught.  The exception handler is expected to do whatever is
appropriate and returns a boolean value. If the return value is
TRUE(1), the proxy object retries the operation. If the return value
is FALSE(0), the \code{CORBA::TRANSIENT} exception is propagated into
the application code.

The following sample code installs a simple exception handler for all
objects and for a specific object:

\begin{cxxlisting}
CORBA::Boolean my_transient_handler1 (void* cookie,
                                      CORBA::ULong retries,
                                      const CORBA::TRANSIENT& ex)
{
   cerr << "transient handler 1 called." << endl;
   return 1;           // retry immediately.
}
 
CORBA::Boolean my_transient_handler2 (void* cookie,
                                      CORBA::ULong retries,
                                      const CORBA::TRANSIENT& ex)
{
   cerr << "transient handler 2 called." << endl;
   return 1;           // retry immediately.
}


static Echo_ptr myobj;

void installhandlers()
{
   omniORB::installTransientExceptionHandler(0,my_transient_handler1);
   // All proxy objects will call my_transient_handler1 from now on.

   omniORB::installTransientExceptionHandler(myobj,0,my_transient_handler2);
   // The proxy object of myobj will call my_transient_handler2 from now on.
}
\end{cxxlisting}


\subsection{CORBA::COMM\_FAILURE}

When the ORB runtime fails to establish a network connection to the
remote object and none of the conditions listed above for raising a
\code{CORBA::TRANSIENT} is applicable, it raises a
\code{CORBA::COMM\_FAILURE} exception.

The default behaviour of the proxy objects is to propagate this
exception to the application. Applications can override the default
behaviour by installing their own exception handlers. The API to do so
is summarised below:

\begin{cxxlisting}
class omniORB {
public:

typedef CORBA::Boolean (*commFailureExceptionHandler_t)(void* cookie,
                                                CORBA::ULong n_retries,
                                                const CORBA::COMM_FAILURE& ex);

static void installCommFailureExceptionHandler(void* cookie,
                                             commFailureExceptionHandler_t fn);

static void installCommFailureExceptionHandler(CORBA::Object_ptr obj,
                                             void* cookie,
                                             commFailureExceptionHandler_t
                                             fn);
}
\end{cxxlisting}

The functions are equivalent to their counterparts for
\code{CORBA::TRANSIENT}.


\subsection{CORBA::SystemException}

To report an error condition, the ORB runtime may raise other system
exceptions. If the exception is neither \code{CORBA::TRANISENT} nor
\code{CORBA::COMM\_FAILURE}, the default behaviour of the proxy
objects is to propagate this exception to the application.
Applications can override the default behaviour by installing their
own exception handlers. The API to do so is summarised below:


\begin{cxxlisting}
class omniORB {
public:

typedef CORBA::Boolean (*systemExceptionHandler_t)(void* cookie,
                                            CORBA::ULong n_retries,
                                            const CORBA::SystemException& ex);

static void installSystemExceptionHandler(void* cookie,
                                          systemExceptionHandler_t fn);

static void installSystemExceptionHandler(CORBA::Object_ptr obj,
                                          void* cookie,
                                          systemExceptionHandler_t fn);
}
\end{cxxlisting}

The functions are equivalent to their counterparts for
\code{CORBA::TRANSIENT}.



\section{Location forwarding}
\label{sec:locationForward}

Any CORBA operation invocation can return a \code{LOCATION\_FORWARD}
message to the caller, indicating that it should retry the invocation
on a new object reference. The standard allows ServantManagers to
trigger \code{LOCATION\_FORWARD}s by raising the
\code{PortableServer::ForwardRequest} exception, but it does not
provide a similar mechanism for normal servants. omniORB provides the
\code{omniORB::LOCATION\_FORWARD} exception for this purpose. It can
be thrown by any operation implementation.

\begin{cxxlisting}
class LOCATION_FORWARD {
public:
  LOCATION_FORWARD(CORBA::Object_ptr objref);
};
\end{cxxlisting}

\noindent The exception object consumes the object reference it is
passed.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Interface Type Checking}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{ch_intf}

This chapter describes the mechanism used by omniORB to ensure type
safety when object references are exchanged across the network. This
mechanism is handled completely within the ORB. There is no
programming interface visible at the application level. However, for
the sake of diagnosing the problem when there is a type violation, it
is useful to understand the underlying mechanism in order to interpret
the error conditions reported by the ORB.

\section{Introduction}

In GIOP/IIOP, an object reference is encoded as an Interoperable
Object Reference (IOR) when it is sent across a network connection.
The IOR contains a Repository ID (RepoId) and one or more
communication profiles. The communication profiles describe where and
how the object can be contacted. The RepoId is a string which uniquely
identifies the IDL interface of the object.

Unless the \code{ID} pragma is specified in the IDL, the ORB generates
the RepoId string in the so-called OMG IDL Format\footnote{For further
details of the repository ID formats, see section 10.6 in the CORBA
2.3 specification.}. For instance, the RepoId for the \intf{Echo}
interface used in the examples of chapter~\ref{ch_basic} is
\texttt{IDL:Echo:1.0}.

When interface inheritance is used in the IDL, the ORB always sends the
RepoId of the most derived interface. For example:

\begin{idllisting}
   // IDL
   interface A {
     ...
   };
   interface B : A {
     ...
   };
   interface C {
      void op(in A arg);
   };
\end{idllisting}

\begin{cxxlisting}
   // C++
   C_ptr server;
   B_ptr objB;
   A_ptr objA = objB;
   server->op(objA);  // Send B as A
\end{cxxlisting}

In the example, the operation \op{C::op} accepts an object reference
of type \type{A}. The real type of the reference passed to \op{C::op}
is \type{B}, which inherits from \type{A}. In this case, the RepoId of
\type{B}, and not that of \type{A}, is sent across the network.

The GIOP/IIOP specification allows an ORB to send a null string in the
RepoId field of an IOR. It is up to the receiving end to work out the
real type of the object. omniORB never sends out null strings as
RepoId. However, it may receive null RepoId from other ORBs. In that
case, it will use the mechanism described below to ensure type safety.

\section{Basic Interface Type Checking}
\label{sec_intf}

The ORB is provided with the interface information by the stubs via
the \type{proxyObjectFactory} class. For an interface \intf{A}, the
stub of \intf{A} contains a \type{\_pof\_A} class. This class is
derived from the \type{proxyObjectFactory} class. The
\type{proxyObjectFactory} is an abstract class which contains 3
functions of interest:

\begin{cxxlisting}
class proxyObjectFactory {
public:

  const char *irRepoId() const;

  virtual CORBA::Boolean is_a(const char *base_repoId) const = 0;
       
  virtual CORBA::Object_ptr newObjRef(const char* mostDerivedTypeId,
                                      IOP::TaggedProfileList* profiles,
                                      omniIdentity* id,
                                      omniLocalIdentity* lid) = 0;
};
\end{cxxlisting}

\begin{itemize}
\item \op{irRepoId} returns the RepoId of the interface.
\item \op{is\_a} returns true(1) if the argument is the RepoId of the
interface itself or it is that of its base interfaces.

\item \op{newObjRef} returns an object reference based on the
information supplied in the arguments.
\end{itemize}

A single instance of every \type{\_pof\_*} is instantiated at runtime.
The instances are entered into a list inside the ORB. The list
constitutes all the interface information known to the ORB.

When the ORB receives an IOR from the network, it unmarshals and
extracts the RepoId from the IOR. At this point, the ORB has two
pieces of information in hand:

\begin{enumerate}
\item The RepoId of the object reference received from the network.
\item The RepoId the ORB is expecting. This comes from the unmarshal
      function that tells the ORB to receive the object reference.
\end{enumerate}

Using the RepoId received, the ORB searches its proxyObjectFactory
list for an exact match. If there is an exact match, all is well
because the runtime can use the \op{is\_a} method of the proxyFactory
to check if the expected RepoId is the same as the received RepoId or
if it is one of its base interfaces. If the answer is positive, the
IOR passes the type checking test and the ORB can proceed to create an
object reference in its own address space to represent the IOR.

However, the ORB may fail to find a match in its proxyObjectFactory
list. This means that the ORB has no local knowledge of the RepoId.
There are three possible causes:

\begin{enumerate}
\item The remote end is another ORB and it sends a null string as the RepoId.
\item The ORB is expecting an object reference of interface A. The remote
      end sends the RepoId of B which is an interface that inherits from A.
      The stubs of A are linked into the executable but the stubs of B are
      not.
\item The remote end has sent a duff IOR.
\end{enumerate}

To handle this situation, the ORB must find out the type information
dynamically. This is explained in the next section.

\section{Interface Inheritance}

When the ORB receives an IOR of interface type B when it expects the
type to be A, it must find out if B inherits from A. When the ORB has
no local knowledge of the type B, it must work out the type of B
dynamically.

The CORBA specification defines an Interface Repository (IR) from
which IDL interfaces can be queried dynamically. In the above
situation, the ORB could contact the IR to find out the type of B.
However, this approach assumes that an IR is always available and
contains the up-to-date information of all the interfaces used in the
domain. This assumption may not be valid in many applications.

An alternative is to use the \op{\_is\_a} operation to work out the
actual type of an object. This approach is simpler and more robust
than the previous one because no 3rd party is involved.

\begin{cxxlisting}
class Object{
    CORBA::Boolean _is_a(const char* type_id);
};
\end{cxxlisting}

The \op{\_is\_a} operation is part of the \intf{CORBA::Object}
interface and must be implemented by every object. The input argument
is a RepoId. The function returns true(1) if the object is really an
instance of that type, including if that type is a base type of the
most derived type of that object.

In the situation above, the ORB would invoke the \op{\_is\_a}
operation on the object and ask if the object is of type A
\emph{before} it processes any application invocation on the object.

Notice that the \op{\_is\_a} call is \emph{not} performed when the IOR
is unmarshalled. It is performed just prior to the first application
invocation on the object. This leads to some interesting failure modes
if B reports that it is not an A. Consider the following example:

\begin{idllisting}
// IDL
interface A { ... };
interface B : A { ... };
interface D { ... };
interface C {
  A      op1();
  Object op2();
};
\end{idllisting}

\lstset{labelstep=1,gobble=4}
\begin{cxxlisting}
 1  // C++
 2  C_ptr objC;
 3  A_ptr objA;
 4  CORBA::Object_ptr objR;
 5
 6  objA =  objC->op1();
 7  (void) objA->_non_existent();
 8
 9  objR =  objC->op2();
10  objA =  A::_narrow(objR);
\end{cxxlisting}
\lstset{labelstep=0,gobble=0}

\noindent If the stubs of A,B,C,D are linked into the executable and:

\begin{description}
\item[Case 1] \op{C::op1} and \op{C::op2} return a B. Lines 6--10
complete successfully. The remote object is only contacted at line 7.

\item[Case 2] \op{C::op1} and \op{C::op2} return a D. This condition
only occurs if the runtime of the remote end is buggy. The ORB raises
a CORBA::Marshal exception at line 1 because it knows it has received
an interface of the wrong type.
\end{description}

\noindent If only the stubs of A are linked into the executable and:

\begin{description}
\item[Case 1] \op{C::op1} and \op{C::op2} return a B. Lines 6--10
complete successfully. When lines 7 and 10 are executed, the object is
contacted to ask if it is an A.

\item[Case 2] \op{C::op1} and \op{C::op2} return a D. This condition
only occurs if the runtime of the remote end is buggy. Line 6
completes and no exception is raised. At line 7, the object is
contacted to ask if it is an A. If the answer is no, a
\code{CORBA::INV\_OBJREF} exception is raised. The application will
also see a \code{CORBA::INV\_OBJREF} at line 10.
\end{description}









%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Connection Management}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{ch_conn}


This chapter describes how omniORB manages network connections.

\section{Background}

In CORBA, the ORB is the `middleware' that allows a client to invoke
an operation on an object without regard to its implementation or
location. In order to invoke an operation on an object, a client needs
to `bind' to the object by acquiring its object reference. Such a
reference may be obtained as the result of an operation on another
object (such as a naming service) or by conversion from a stringified
representation. If the object is in a different address space, the
binding process involves the ORB building a proxy object in the
client's address space. The ORB arranges for invocations on the proxy
object to be transparently mapped to equivalent invocations on the
implementation object.

For the sake of interoperability, CORBA mandates that all ORBs should
support IIOP as the means to communicate remote invocations over a
TCP/IP connection. IIOP is asymmetric with respect to the roles of the
parties at the two ends of a connection. At one end is the client
which can only initiate remote invocations. At the other end is the
server which can only receive remote invocations.

Notice that in CORBA, as in most distributed systems, remote bindings
are established implicitly without application intervention. This
provides the illusion that all objects are local, a property known as
`location transparency'. CORBA does not specify when such bindings
should be established or how they should be multiplexed over the
underlying network connections. Instead, ORBs are free to implement
implicit binding by a variety of means.

The rest of this chapter describes how omniORB manages network
connections and the programming interface to fine tune the management
policy.

\section{The Model}

omniORB is designed from the ground up to be fully multi-threaded. The
objective is to maximise the degree of concurrency and at the same
time eliminate any unnecessary thread overhead. Another objective is
to minimise the interference by the activities of other threads on the
progress of a remote invocation. In other words, thread `cross-talk'
should be minimised within the ORB. To achieve these objectives, the
degree of multiplexing at every level is kept to a minimum.

On the client side of a connection, the thread that invokes on a proxy
object drives the IIOP protocol directly and blocks on the connection
to receive the reply. On the server side, a dedicated thread blocks on
the connection. When it receives a request, it performs the up-call to
the object and sends the reply when the up-call returns. There is no
thread switching along the call chain.

With this design, there is at most one call in-flight at any time on a
connection. If there is only one connection, concurrent invocations to
the same remote address space would have to be serialised. To
eliminate this limitation, omniORB implements a dynamic
policy---multiple connections to the same remote address space are
created on demand and cached when there are concurrent invocations in
progress.

To be more precise, a network connection to another address space is
only established when a remote invocation is about to be made.
Therefore, there may be one or more object references in one address
space that refer to objects in a different address space but unless
the application invokes on these objects, no network connection is
made. The maximum number of connections opened to another address
space is 5 by default. Since 2.6.0, this parameter can be changed by
setting the variable \code{omniORB::maxTcpConnectionPerServer}
\emph{before} calling \op{ORB\_init}.

It is wasteful to leave a connection open when it has been left unused
for a considerable time. Too many idle connections could block out new
connections to a server when it runs out of spare communication
channels. For example, most Unix platforms have a limit on the number
of file handles a process can open. 64 is the usual default limit. The
value can be increased to a maximum of a thousand or more by changing
the `ulimit' in the shell.

\section{Idle Connection Shutdown and Remote Call Timeout}
\label{sec_shut}

Inside the ORB, a thread is dedicated to scan for idle connections.
The thread looks after both the outgoing connections and the incoming
connections.

When a connection is idle for a period of time, the connection is
shutdown. Similarly, if a remote call has not completed within a
defined period of time, the connection is shutdown and the ORB will
return \code{COMM\_FAILURE} to the client.

How often the internal thread scans the connections is determined by
the value of the \emph{scan granularity}. This value is defaulted to 5
seconds and can be changed using the command-line option
\texttt{-ORBscanGranularity} or using the
\code{omniORB::\dsc{}scanGranularity} call. Notice that this value
determines the precision the ORB is able to keep to the value of the
idle connection or remote call timeout.

How long the ORB will wait before it shuts down an idle connection is
determined by the idleConnectionPeriods. There are separate values for
incoming and outgoing connections. The default values are 180 and 120
seconds for incoming and outgoing connections respectively. These
values can be changed using the command-line options
\texttt{-ORBinConScanPeriod} and \texttt{-ORBoutConScanPeriod}. They
can also be controlled by the
\op{omniORB::idleConnectionScanPeriod} call.

Similarly, how long the ORB will wait for a remote call to complete is
determined by the parameter clientCallTimeOutPeriod for the client
side and the serverCallTimeOutPeroid for the server side. By default
calls will not timeout on either the client or server side.

The timeouts can be changed using the
\op{omniORB::callTimeOutPeriod} call, or with the command line
options \texttt{-ORBclientCallTimeOutPeriod} and
\texttt{-ORBserverCallTimeOutPeriod}.

The APIs are documented in \file{include/omniORB3/omniORB.h}.


\begin{cxxlisting}
class omniORB {
public:

  static void scanGranularity(CORBA::ULong sec);

  static CORBA::ULong scanGranularity();

  enum   idleConnType { idleIncoming, idleOutgoing };

  static void idleConnectionScanPeriod(idleConnType direction, CORBA::ULong sec);

  static CORBA::ULong idleConnectionScanPeriod(idleConnType direction);

  enum   callTimeOutType { clientSide, serverSide };

  static void callTimeOutPeriod(callTimeOutType direction, CORBA::ULong sec);

  static CORBA::ULong callTimeOutPeriod(callTimeOutType direction);
};
\end{cxxlisting}

The scan can be disabled completely by setting the scan granularity to
0.

\section{Interoperability Considerations}

The IIOP specification allows both the client and the server to
shutdown a connection unilaterally. When one end is about to shutdown
a connection, it should send a closeConnection message to the other
end. It should also make sure that the message will reach the other
end before it proceeds to shutdown the connection.

The client should distinguish between an orderly and an abnormal
connection shutdown. When a client receives a closeConnection message
before the connection is closed, the condition is an orderly shutdown.
If the message is not received, the condition is an abnormal shutdown.
In an abnormal shutdown, the ORB should raise a \code{COMM\_FAILURE}
exception whereas in an orderly shutdown, the ORB should \emph{not}
raise an exception and should try to re-establish a new connection
transparently.

omniORB implements these semantics completely. However, it is known
that some ORBs are not (yet) able to distinguish between an orderly
and an abnormal shutdown. Usually this is manifested as the client in
these ORBs seeing a \code{COMM\_FAILURE} occasionally when connected
to an omniORB server. The work-around is either to catch the exception
in the application code and retry, or to turn off the idle connection
shutdown inside the omniORB server.


\section{Connection Acceptance}
\label{sec_accept}

omniORB provides the hook to implement a connection acceptance policy.
Inside the ORB runtime, a thread is dedicated to receive new
connections. When the thread is given the handle of a new connection
by the operating system, it calls the policy module to decide if the
connection can be accepted. If the answer is yes, the ORB will start
serving requests coming in from that connection. Otherwise, the
connection is shutdown immediately.

There can be a number of policy module implementations. The basic one
is a dummy module which just accepts every connection.

In addition, a host-based access control module is available on Unix
platforms. The module uses the IP address of the client to decide if
the connection can be accepted. The module is implemented using
\emph{tcp\_wrappers 7.6}. The access control policy can be defined as
rules in two access control files: \file{hosts.allow} and
\file{hosts.deny}. The syntax of the rules is described in the manual
page \file{hosts_access(5)} which can be found in
appendix~\ref{apx:hostsaccess}. The syntax defines a simple access
control language that is based on client (host name/address, user
name), and server (process name, host name/address) patterns. When
searching for a match on the server process name, the ORB uses the
value of \code{omniORB::serverName}. \op{ORB\_init} uses the argument
\code{argv[0]} to set the default value of this variable. This can be
overridden by the application with the \texttt{-ORBserverName
}<\textit{string}> command line argument

The default location of the access control files is \file{/etc}. This
can be overridden by the extra options in \file{omniORB.cfg}. For
instance:

{\small
\begin{verbatim}
# omniORB configuration file - extra options

GATEKEEPER_ALLOWFILE   /project/omni/var/hosts.allow

GATEKEEPER_DENYFILE    /project/omni/var/hosts.deny

\end{verbatim}
}

As each policy module is implemented as a separate library, the choice
of policy module is determined at program linkage time. For instance,
if the host-based access control module is in use:

{\small
\begin{verbatim}
% eg1 -ORBtraceLevel 2
omniORB gateKeeper is tcpwrapGK 1.0 - based on tcp_wrappers_7.6 
I said,"Hello!". The Object said,"Hello!"
\end{verbatim}
}

\noindent Whereas if the dummy module is in use:

{\small
\begin{verbatim}
% eg1 -ORBtraceLevel 2
omniORB gateKeeper is not installed. All incoming are accepted.
I said,"Hello!". The Object said,"Hello!"
\end{verbatim}
}





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Type Any and TypeCode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{ch_any}

The CORBA specification provides for a type that can hold the value of
any OMG IDL type. This type is known as type Any. The OMG also
specifies a pseudo-object, TypeCode, that can encode a description of
any type specifiable in OMG IDL.

In this chapter, an example demonstrating the use of type Any is
presented.  This is followed by sections describing the behaviour of
type Any and TypeCode in omniORB.  For further information on type
Any, refer to the C++ Mapping section of the CORBA 2.3
specification~\cite{corba23-spec}, and for more information on
TypeCode, refer to the Interface Repository chapter in the CORBA core
section of the CORBA 2.3 specification.


\begin{statement}
\centerline{\textbf{Warning}}

Since 2.8.0, omniORB has been updated to CORBA 2.3. In order to comply
with the 2.3 specification, it is necessary to change the semantics of
\emph{the extraction of string, object reference and typecode from an
Any}. The memory of the extracted values of these types now belongs to
the Any value. The storage is freed when the Any value is deallocated.
Previously the extracted value was a copy and the application was
responsible for releasing the storage. It is not possible to detect
the old usage at compile time. In particular, unmodified code that
uses the affected Any extraction operators will most certainly cause
runtime errors to occur.  To smooth the transition from the old usage
to the new, an ORB configuration variable
\code{omniORB::omniORB\_27\_CompatibleAnyExtraction} can be set to
revert the any extraction operators to the old semantics.

\end{statement}


\section{Example using type Any}

Before going through this example, you should make sure that you have
read and understood the examples in chapter~\ref{ch_basic}.  The
source code for this example is included in the omniORB distribution,
in the directory \file{src/examples/anyExample}. A listing of the
source code is provided at the end of this chapter.

\subsection{Type Any in IDL}
Type Any allows one to delay the decision on the type used in an
operation until run-time. To use type any in IDL, use the keyword
\code{any}, as in the following example:

\begin{idllisting}
// IDL

interface anyExample {
  any testOp(in any mesg);
};
\end{idllisting}


The operation \op{testOp()} in this example can now take any value
expressible in OMG IDL as an argument, and can also return any type
expressible in OMG IDL.

Type Any is mapped into C++ as the type \type{CORBA::Any}. When passed
as an argument or as a result of an operation, the following rules
apply:

\mbox{}

{\small
\begin{tabular}{llll}
{\bf In }                & {\bf InOut }       & {\bf Out }           & 
{\bf Return }                                                   \\ \hline
{\tt const CORBA::Any\& }& {\tt CORBA::Any\& }& {\tt CORBA::Any*\& } & 
{\tt CORBA::Any* }
\end{tabular}
}

\mbox{}

So, the above IDL would map to the following C++:

\begin{cxxlisting}
// C++

class anyExample_i : public virtual _sk_anyExample {
public:
  anyExample_i() { }
  virtual ~anyExample_i() { }
  virtual CORBA::Any* testOp(const CORBA::Any& a);
};
\end{cxxlisting}


\subsection{Inserting and Extracting Basic Types from an Any}

The question now arises as to how values are inserted into and removed
from an Any. This is achieved using two overloaded operators:
\code{<{}<=} and \code{>{}>=}.

To insert a value into an Any, the \code{<{}<=} operator is used, as
in this example:

\begin{cxxlisting}
// C++
CORBA::Any an_any;
CORBA::Long l = 100;
an_any <<= l;
\end{cxxlisting}


Note that the overloaded \code{<{}<=} operator has a return type of
\type{void}.

To extract a value, the \code{>{}>=} operator is used, as in this
example (where the Any contains a long):

\begin{cxxlisting}
// C++
CORBA::Long l;
an_any >>= l;

cout << "This is a long: " << l << endl;
\end{cxxlisting}


The overloaded \code{>{}>=} operator returns a \type{CORBA::Boolean}.
If an attempt is made to extract a value from an Any when it contains
a different type of value (e.g.\ an attempt to extract a long from an
Any containing a double), the overloaded \code{>{}>=} operator will
return False; otherwise it will return True. Thus, a common tactic to
extract values from an Any is as follows:

\begin{cxxlisting}
// C++
CORBA::Long l;
CORBA::Double d;
const char* str;     // From CORBA 2.3 onwards, uses const char*
                     // instead of char*. 

if (an_any >>= l) {
    cout << "Long: " << l << endl;
}
else if (an_any >>= d) {
    cout << "Double: " << d << endl;
}
else if (an_any >>= str) {
    cout << "String: " << str << endl;
    // Since 2.8.0 the storage of the extracted string is still
    // owned by the any.
    // In pre-omniORB 2.8.0 releases, the string returned is a copy.
}
else {
    cout << "Unknown value." << endl;
}
\end{cxxlisting}


\subsection{Inserting and Extracting Constructed Types from an Any}

It is also possible to insert and extract constructed types and object
references from an Any. omniidl will generate insertion and extraction
operators for the constructed type. Note that it is necessary to
specify the \texttt{-WBa} command-line flag when running omniidl in
order to generate these operators. The following example illustrates
the use of constructed types with type Any:

\begin{idllisting}
// IDL
struct testStruct {
  long l;
  short s;
};

interface anyExample {
  any testOp(in any mesg);
};
\end{idllisting}

Upon compiling the above IDL with \texttt{omniidl -bcxx -Wba}, the
following overloaded operators are generated:

\begin{enumerate}
\item \verb|void operator<<=(CORBA::Any&, const testStruct&)|
\item \verb|void operator<<=(CORBA::Any&, testStruct*)|
\item \verb|CORBA::Boolean operator>>=(const CORBA::Any&,|\\
      \verb|const testStruct*&)|
\end{enumerate}

Operators of this form are generated for all constructed types, and
for interfaces.

The first operator, \emph{(1)}, copies the constructed type, and
inserts it into the Any. The second operator, \emph{(2)}, inserts the
constructed type into the Any, and then manages it. Note that if the
second operator is used, the Any consumes the constructed type, and
the caller should not use the pointer to access the data after
insertion. The following is an example of how to insert a value into
an Any using operator \emph{(1)}:

\begin{cxxlisting}
// C++
CORBA::Any an_any;

testStruct t;
t.l = 456;
t.s = 8;

an_any <<= t;
\end{cxxlisting}


The third operator, \emph{(3)}, is used to extract the constructed
type from the Any, and can be used as follows:

\begin{cxxlisting}
const testStruct* tp;   // From CORBA 2.3 onwards, use 
                        // const testStruct* instead of testStruct*

if (an_any >>= tp) {
    cout << "testStruct: l: " << tp->l << endl;
    cout << "            s: " << tp->s << endl;
}
else {
    cout << "Unknown value contained in Any." << endl;
}
\end{cxxlisting}

As with basic types, if an attempt is made to extract a type from an
Any that does not contain a value of that type, the extraction
operator returns False. If the Any does contain that type, the
extraction operator returns True. If the extraction is successful, the
caller's pointer will point to memory managed by the Any. The caller
must not delete or otherwise change this storage, and should not use
this storage after the contents of the Any are replaced (either by
insertion or assignment), or after the Any has been destroyed. In
particular, management of the pointer should not be assigned to a
\type{\_var} type.

If the extraction fails, the caller's pointer will be set to point to
null.

Note that there are special rules for inserting and extracting arrays
(using the \type{\_forany} types), and for inserting and extracting
bounded strings, booleans, chars, and octets. Please refer to the C++
Mapping chapter of the CORBA 2.3 specification~\cite{corba23-spec} for
further information.


\begin{statement}
\centerline{\textbf{Warning}}

In pre-omniORB 2.8.0 releases, it was unclear in the CORBA
specification whether or not object references should be managed by an
Any.  The omniORB implementation leaves management of an extracted
object reference to the caller. Therefore, the programmer should
release object references and TypeCodes that have been extracted from
an Any. The same also applies to string extraction. CORBA 2.3 has
clarified this issue and decreed that the management of an extracted
object reference still belongs to the Any!  Since 2.8.0, the omniORB
implementation conforms to the CORBA 2.3 specification. For backward
compatibility, the runtime variable
\code{omniORB::omniORB\_27\_CompatibleAnyExtraction} can be set to 1
to get back the old behaviour. Notice that this should be used as a
transitional measure and in the long run, applications should be
written to use the new behaviour.

\end{statement}


\section{Type Any in omniORB}
\label{anyOmniORB}

This section contains some notes on the use and behaviour of type Any
in omniORB.

\paragraph*{Generating Insertion and Extraction Operators.}
To generate type Any insertion and extraction operators for
constructed types and interfaces, the \texttt{-Wba} command line flag
should be specified when running omniidl.

\paragraph*{TypeCode comparison when extracting from an Any.}
When an attempt is made to extract a type from an Any, the TypeCode of
the type is checked for \emph{equivalence} with the TypeCode of the
type stored by the Any. The \op{equivalent} test in the TypeCode
interface is used for this purpose\footnote{In pre-omniORB 2.8.0
releases, omniORB performs an equality test and will ignore any alias
TypeCodes (\code{tk\_alias}) when making this comparison. The
semantics is similar to the \op{equivalent} test in the TypeCode
interface of CORBA 2.3.}.

Examples:

\begin{idllisting}
// IDL 1
typedef double Double1;

struct Test1 {
  Double1 a;
};
\end{idllisting}

\begin{idllisting}
// IDL 2
typedef double Double2;

struct Test1 {
  Double2 a;
};
\end{idllisting}
    
If an attempt is made to extract the type \type{Test1} defined in IDL
1 from an Any containing the \type{Test1} defined in IDL 2, this will
succeed (and vice-versa), as the two types differ only by an alias.

\paragraph*{Top-level aliases.}
When a type is inserted into an Any, the Any stores both the value of
the type and the TypeCode for that type. The treatment of top-level
aliases from omniORB 2.8.0 onwards is different from pre-omniORB 2.8.0
releases.

In pre-omniORB 2.8.0 releases, if there are any top-level
\code{tk\_alias} TypeCodes in the TypeCode, they will be removed from
the TypeCode stored in the Any. Note that this does not affect the
\code{\_tc\_} TypeCode generated to represent the type (see section on
TypeCode, below). This behaviour is necessary, as two types that
differ only by a top-level alias can use the same insertion and
extraction operators. If the \code{tk\_alias} is not removed, one of
the types could be transmitted with an incorrect \code{tk\_alias}
TypeCode. Example:

\begin{idllisting}
// IDL 3
typedef sequence<double> seqDouble1;
typedef sequence<double> seqDouble2;
typedef seqDouble2       seqDouble3;
\end{idllisting}

If either \type{seqDouble1} or \type{seqDouble2} is inserted into an
Any, the TypeCode stored in the Any will be for a
\code{sequence<double>}, and not for an alias to a
\code{sequence<double>}.

From omniORB 2.8.0 onwards, there are two changes. Firstly, in the
example, \type{seqDouble1} and \type{seqDouble2} are now distinct
types and therefore each has its own set of C++ operators for Any
insertion and extraction. Secondly, the top level aliases are not
removed. For example, if \type{seqDouble3} is inserted into an Any,
the insertion operator for \type{seqDouble2} is invoked (because
\type{seqDouble3} is just a C++ typedef of
\type{seqDouble2}). Therefore, the TypeCode in the Any would be that
of seqDouble2. If this is not desirable, one can use the new member
function `\code{void type(TypeCode\_ptr)}' of the Any interface to
explicitly set the TypeCode to the correct one.


\paragraph*{Removing aliases from TypeCodes.}
Some ORBs (such as Orbix) will not accept TypeCodes containing
\code{tk\_alias} TypeCodes. When using type Any while interoperating
with these ORBs, it is necessary to remove \code{tk\_alias} TypeCodes
from throughout the TypeCode representing a constructed type.

To remove all \code{tk\_alias} TypeCodes from TypeCodes stored in
Anys, supply the \texttt{-ORBtcAliasExpand 1} command-line flag when
running an omniORB executable. There will be some (small) performance
penalty when inserting values into an Any.

Note that the \code{\_tc\_} TypeCodes generated for all constructed
types will contain the complete TypeCode for the type (including any
\code{tk\_alias} TypeCodes), regardless of whether the
\texttt{-ORBtcAliasExpand} flag is set to 1 or not.

\paragraph*{Recursive TypeCodes.}
omniORB (as of version 2.7) supports recursive TypeCodes. This means
that types such as the following can be inserted or extracted from an
Any:

\begin{idllisting}
// IDL 4
struct Test4 {
  sequence<Test4> a;
};
\end{idllisting}

\paragraph*{Type-unsafe construction and insertion.}
If using the type-unsafe Any constructor, or the
\op{CORBA::Any::replace} member function, ensure that the value
returned by the \op{CORBA::Any::value} member function and the
TypeCode returned by the \op{CORBA::Any::type} member function are
used as arguments to the constructor or function. Using other values
or TypeCodes may result in a mismatch, and is undefined behaviour.

Note that a non-CORBA 2 function,

\begin{cxxlisting}
CORBA::ULong CORBA::Any::NP_length() const
\end{cxxlisting}

is supplied. This member function returns the length of the value
returned by the \op{CORBA::Any::value} member function. It may be
necessary to use this function if the Any's value is to be stored in a
file.

\paragraph*{Threads and type Any.}
Inserting and extracting simultaneously from the same Any (in 2
different threads) is undefined behaviour.

Extracting simultaneously from the same Any (in 2 or more different
threads) also leads to undefined behaviour.  It was decided not to
protect the Any with a mutex, as this condition should rarely arise,
and adding a mutex would lead to performance penalties.


\section{TypeCode in omniORB}

This section contains some notes on the use and behaviour of TypeCode
in omniORB

\paragraph*{TypeCodes in IDL.}

When using TypeCodes in IDL, note that they are defined in the CORBA
scope.  Therefore, \type{CORBA::TypeCode} should be used. Example:

\begin{idllisting}
// IDL 5
struct Test5 {
  long length;
  CORBA::TypeCode desc;
};
\end{idllisting}

\paragraph*{orb.idl}

Inclusion of the file \file{orb.idl} in IDL using
\type{CORBA::TypeCode} is optional.  An empty \file{orb.idl} file is
provided for compatibility purposes.

\paragraph*{Generating TypeCodes for constructed types.}

To generate a TypeCode for constructed types, specify the
\texttt{-Wba} command-line flag when running omniidl. This will
generate a \code{\_tc\_} TypeCode describing the type, at the same
scope as the type (as per the CORBA 2.3 specification). Example:

\begin{idllisting}
// IDL 6
struct Test6 {
  double a;
  sequence<long> b;
};
\end{idllisting}

A TypeCode, \code{\_tc\_Test6}, will be generated to describe the
struct \type{Test6}. The operations defined in the TypeCode interface
(see section 10.7 of the CORBA 2.3 specification~\cite{corba23-spec})
can be used to query the TypeCode about the type it represents.


\paragraph*{TypeCode equality.}

The behaviour of \op{CORBA::TypeCode::equal} member function from
omniORB 2.8.0 onwards is different from pre-omniORB 2.8.0 releases.
In summary, the pre-omniORB 2.8.0 is close to the semantics of the new
\op{CORBA::TypeCode::equivalent} member function. Details are as
follows:

The \op{CORBA::TypeCode::equal()} member function will now return true
only if the two TypeCodes are \emph{exactly} the same.
\code{tk\_alias} TypeCodes are included in this comparison, unlike the
comparison made when values are extracted from an Any (see section on
Any, above).

In pre-omniORB 2.8.0 releases, equality test would ignore the optional
fields when one of the fields in the two typecodes is empty. For
example, if one of the TypeCodes being checked is a \code{tk\_struct},
\code{tk\_union}, \code{tk\_enum}, or \code{tk\_alias}, and has an
empty repository ID parameter, then the repository ID parameter will
be ignored when checking for equality.  Similarly, if the \code{name}
or \code{member\_name} parameters of a TypeCode are empty strings,
they will be ignored for equality checking purposes. This is because a
CORBA 2 ORB does not have to include these parameters in a TypeCode
(see the Interoperability section of the CORBA 2
specification~\cite{corba2-spec}). Note that these (optional)
parameters are included in TypeCodes generated by omniORB.

Since CORBA 2.3, the issue of TypeCode equality has been clarified.
There is now a new member \op{CORBA::TypeCode::equivalent} which
provides the semantics of the \op{CORBA::TypeCode::equal} as
implemented in omniORB releases prior to 2.8.0. So from omniORB 2.8.0
onwards, the \op{CORBA::TypeCode::\dsc{}equal} function has been
changed to enforce strict equality.  The pre-2.8.0 behaviour can be
obtained with \op{equivalent}.


\clearpage

\section{Source Listing}

\subsection{anyExample\_impl.cc}

\begin{cxxlisting}
// anyExample_impl.cc - This is the source code of the example used in
//                      Chapter 9 "Type Any and TypeCode" of the omniORB
//                      users guide.
//
//                      This is the object implementation.
//
// Usage: anyExample_impl
//
//        On startup, the object reference is printed to cerr as a
//        stringified IOR. This string should be used as the argument to 
//        anyExample_clt.
//

#include <iostream.h>
#include <anyExample.hh>

class anyExample_i : public POA_anyExample {
public:
  inline anyExample_i() {}
  virtual ~anyExample_i() {}
  virtual CORBA::Any* testOp(const CORBA::Any& a);
};

CORBA::Any* anyExample_i::testOp(const CORBA::Any& a)
{
  cout << "Any received, containing: " << endl;

#ifndef NO_FLOAT
  CORBA::Double d;
#endif

  CORBA::Long l;
  const char* str;

  testStruct* tp;

  if (a >>= l) {
    cout << "Long: " << l << endl;
  }
#ifndef NO_FLOAT
  else if (a >>= d) {
    cout << "Double: " << d << endl;
  }
#endif
  else if (a >>= str) {
    cout << "String: " << str << endl;
  }
  else if (a >>= tp) {
    cout << "testStruct: l: " << tp->l << endl;
    cout << "            s: " << tp->s << endl;
  }
  else {
    cout << "Unknown value." << endl;
  }

  CORBA::Any* ap = new CORBA::Any;

  *ap <<= (CORBA::ULong) 314;

  cout << "Returning Any containing: ULong: 314\n" << endl;
  return ap;
}

//////////////////////////////////////////////////////////////////////

int main(int argc, char** argv)
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    CORBA::Object_var obj = orb->resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    anyExample_i* myobj = new anyExample_i();

    PortableServer::ObjectId_var myobjid = poa->activate_object(myobj);

    obj = myobj->_this();
    CORBA::String_var sior(orb->object_to_string(obj));
    cerr << "'" << (char*)sior << "'" << endl;

    myobj->_remove_ref();

    PortableServer::POAManager_var pman = poa->the_POAManager();
    pman->activate();

    orb->run();
    orb->destroy();
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}
\end{cxxlisting}


\clearpage

\subsection{anyExample\_clt.cc}

\begin{cxxlisting}
// anyExample_clt.cc -  This is the source code of the example used in 
//                      Chapter 9 "Type Any and TypeCode" of the omniORB 
//                      users guide.
//
//                      This is the client.
//
// Usage: anyExample_clt <object reference>
//

#include <iostream.h>
#include <anyExample.hh>

static void invokeOp(anyExample_ptr& tobj, const CORBA::Any& a)
{
  CORBA::Any_var bp;

  cout << "Invoking operation." << endl;
  bp = tobj->testOp(a);

  cout << "Operation completed. Returned Any: ";
  CORBA::ULong ul;

  if (bp >>= ul) {
    cout << "ULong: " << ul << "\n" << endl;
  }
  else {
    cout << "Unknown value." << "\n" << endl;
  }
}

static void hello(anyExample_ptr tobj)
{
  CORBA::Any a;

  // Sending Long
  CORBA::Long l = 100;
  a <<= l;
  cout << "Sending Any containing Long: " << l << endl; 
  invokeOp(tobj,a);
    
  // Sending Double
#ifndef NO_FLOAT
  CORBA::Double d = 1.2345;
  a <<= d;
  cout << "Sending Any containing Double: " << d << endl; 
  invokeOp(tobj,a);
#endif
  
  // Sending String
  const char* str = "Hello";
  a <<= str;
  cout << "Sending Any containing String: " << str << endl;
  invokeOp(tobj,a);
    
  // Sending testStruct  [Struct defined in IDL]
  testStruct t;
  t.l = 456;
  t.s = 8;
  a <<= t;
  cout << "Sending Any containing testStruct: l: " << t.l << endl;
  cout << "                                   s: " << t.s << endl;
  invokeOp(tobj,a);
}

//////////////////////////////////////////////////////////////////////

int main(int argc, char** argv)
{
  try {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");

    if( argc != 2 ) {
      cerr << "usage:  anyExample_clt <object reference>" << endl;
      return 1;
    }

    CORBA::Object_var obj = orb->string_to_object(argv[1]);
    anyExample_var ref = anyExample::_narrow(obj);
    if( CORBA::is_nil(ref) ) {
      cerr << "Can't narrow reference to type anyExample (or it was nil)."
	   << endl;
      return 1;
    }
    hello(ref);

    orb->destroy();
  }
  catch(CORBA::COMM_FAILURE& ex) {
    cerr << "Caught system exception COMM_FAILURE -- unable to contact the "
         << "object." << endl;
  }
  catch(CORBA::SystemException&) {
    cerr << "Caught a CORBA::SystemException." << endl;
  }
  catch(CORBA::Exception&) {
    cerr << "Caught CORBA::Exception." << endl;
  }
  catch(omniORB::fatalException& fe) {
    cerr << "Caught omniORB::fatalException:" << endl;
    cerr << "  file: " << fe.file() << endl;
    cerr << "  line: " << fe.line() << endl;
    cerr << "  mesg: " << fe.errmsg() << endl;
  }
  catch(...) {
    cerr << "Caught unknown exception." << endl;
  }
  return 0;
}
\end{cxxlisting}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Dynamic Management of Any Values}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\hyphenation{Dyn-Any}

In CORBA specification 2.2, a new facility---\term{DynAny} was
introduced. Previously, it was not possible to insert or extract
constructed and other complex types from an Any without using the stub
code generated by an idl compiler for these types. This makes it
impossible to write generic servers (bridges, event channels
supporting filtering, etc.) because these servers can not have static
knowledge of all the possible data types that they have to handle.

To fill this gap, the DynAny facility is defined to enable traversal
of the data value associated with an Any at runtime and extraction of
its constituents. This facility also enables the construction of an
Any at runtime, without having static knowledge of its types.

This chapter describes how DynAny may be used. For completeness, you
should also read the DynAny specification defined in Chapter 9 of the
CORBA 2.3 specification. Where possible, the implementation in omniORB
adheres closely to the specification. However, there are areas in the
specification that are ambiguous or lacking in details. A number of
these issues are currently opened with the ORB revision task force.
Until the issues are resolved, it is possible that a different
implementation may choose to interpret the specification differently.
This chapter provides clarifications to the specification, explains
the interpretation used and offers some advice and warnings on
potential portability problems.

Notice that the DynAny interface has been changed in CORBA 2.3,
particularly with the addition of the support for the IDL type
\type{valuetype}.  Future releases of omniORB will be updated to
implement the interface as defined in CORBA 2.3.

\section{C++ mapping}

\begin{cxxlisting}
// namespace CORBA

class ORB {
public:
  ...

  class InconsistentTypeCode : public UserException { ... };

  DynAny_ptr create_dyn_any(const Any& value);

  DynAny_ptr create_basic_dyn_any(TypeCode_ptr tc);

  DynStruct_ptr create_dyn_struct(TypeCode_ptr tc);

  DynSequence_ptr create_dyn_sequence(TypeCode_ptr tc);

  DynArray_ptr create_dyn_array(TypeCode_ptr tc);

  DynUnion_ptr create_dyn_union(TypeCode_ptr tc);

  DynEnum_ptr create_dyn_enum(TypeCode_ptr tc);

};

typedef DynAny* DynAny_ptr;
class DynAny_var { ... };

class DynAny {
public:    

  class Invalid : public UserException { ... };
  class InvalidValue : public UserException { ... };
  class TypeMismatch : public UserException { ... };
  class InvalidSeq : public UserException { ... };

  typedef _CORBA_Unbounded_Sequence__Octet OctetSeq;

  TypeCode_ptr type() const;

  void assign(DynAny_ptr dyn_any) throw(Invalid,SystemException);
  void from_any(const Any& value) throw(Invalid,SystemException);
  Any* to_any() throw(Invalid,SystemException);
  void destroy();
  DynAny_ptr copy();

  DynAny_ptr current_component();
  Boolean next();
  Boolean seek(Long index);
  void rewind();

  void insert_boolean(Boolean value) throw(InvalidValue,SystemException);
  void insert_octet(Octet value) throw(InvalidValue,SystemException);
  void insert_char(Char value) throw(InvalidValue,SystemException);
  void insert_short(Short value) throw(InvalidValue,SystemException);
  void insert_ushort(UShort value) throw(InvalidValue,SystemException);
  void insert_long(Long value) throw(InvalidValue,SystemException);
  void insert_ulong(ULong value) throw(InvalidValue,SystemException);
  void insert_float(Float value) throw(InvalidValue,SystemException);
  void insert_double(Double value) throw(InvalidValue,SystemException);
  void insert_string(const char* value) throw(InvalidValue,SystemException);
  void insert_reference(Object_ptr v) throw(InvalidValue,SystemException);
  void insert_typecode(TypeCode_ptr v) throw(InvalidValue,SystemException);
  void insert_any(const Any& value) throw(InvalidValue,SystemException);

  Boolean get_boolean() throw(TypeMismatch,SystemException);
  Octet get_octet() throw(TypeMismatch,SystemException);
  Char get_char() throw(TypeMismatch,SystemException);
  Short get_short() throw(TypeMismatch,SystemException);
  UShort get_ushort() throw(TypeMismatch,SystemException);
  Long get_long() throw(TypeMismatch,SystemException);
  ULong get_ulong() throw(TypeMismatch,SystemException);
  Float get_float() throw(TypeMismatch,SystemException);
  Double get_double() throw(TypeMismatch,SystemException);
  char* get_string() throw(TypeMismatch,SystemException);
  Object_ptr get_reference() throw(TypeMismatch,SystemException);
  TypeCode_ptr get_typecode() throw(TypeMismatch,SystemException);
  Any* get_any() throw(TypeMismatch,SystemException);

  static DynAny_ptr _duplicate(DynAny_ptr);
  static DynAny_ptr _narrow(DynAny_ptr);
  static DynAny_ptr _nil();
};

// DynFixed is not supported.

typedef DynEnum* DynEnum_ptr;
class DynEnum_var { ... };

class DynEnum :  public DynAny {
public:

  char* value_as_string();
  void value_as_string(const char* value);
  ULong value_as_ulong();
  void value_as_ulong(ULong value);

  static DynEnum_ptr _duplicate(DynEnum_ptr);
  static DynEnum_ptr _narrow(DynAny_ptr);
  static DynEnum_ptr _nil();
};

typedef char* FieldName;
typedef String_var FieldName_var;

struct NameValuePair {
  String_member id;
  Any value;
};

typedef _CORBA_ConstrType_Variable_Var<NameValuePair> NameValuePair_var;
typedef _CORBA_Unbounded_Sequence<NameValuePair > NameValuePairSeq;

typedef DynStruct* DynStruct_ptr;
class DynStruct_var { ... };

class DynStruct :  public DynAny {
public:

  char*  current_member_name();
  TCKind current_member_kind();
  NameValuePairSeq* get_members();
  void set_members(const NameValuePairSeq& NVSeqVal)
                   throw(InvalidSeq,SystemException);

  static DynStruct_ptr _duplicate(DynStruct_ptr);
  static DynStruct_ptr _narrow(DynAny_ptr);
  static DynStruct_ptr _nil();
};

typedef DynUnion* DynUnion_ptr;
class DynUnion_var { ... };

class DynUnion :  public DynAny {
public:

  Boolean set_as_default();
  void set_as_default(Boolean value);
  DynAny_ptr discriminator();
  TCKind discriminator_kind();
  DynAny_ptr member();
  char*  member_name();
  void member_name(const char* value);
  TCKind member_kind();

  static DynUnion_ptr _duplicate(DynUnion_ptr);
  static DynUnion_ptr _narrow(DynAny_ptr);
  static DynUnion_ptr _nil();
};

typedef _CORBA_Unbounded_Sequence<Any > AnySeq;

typedef DynSequence* DynSequence_ptr;
class DynSequence_var { ... };

class DynSequence :  public DynAny {
public:

  ULong length();
  void length (ULong value);
  AnySeq* get_elements();
  void set_elements(const AnySeq& value) throw(InvalidValue,SystemException);

  static DynSequence_ptr _duplicate(DynSequence_ptr);
  static DynSequence_ptr _narrow(DynAny_ptr);
  static DynSequence_ptr _nil();
};

typedef DynArray* DynArray_ptr;
class DynArray_var { ... };

class DynArray : public DynAny {
public:

  AnySeq* get_elements();
  void set_elements(const AnySeq& value) throw(InvalidValue,SystemException);

  static DynArray_ptr _duplicate(DynArray_ptr);
  static DynArray_ptr _narrow(DynAny_ptr);
  static DynArray_ptr _nil();
};
\end{cxxlisting}

\section{The DynAny Interface}
\label{dynany}

\subsection{Example: extract data values from an Any}

If an Any contains a value of one of the basic data types, its value
can be extracted using the pre-defined operators in the Any interface.
When the value is a struct or other non-basic types, one can use the
DynAny interface to extract its constituent values.

In this section, we use a struct as an example to illustrate how the
DynAny interface can be used.

The example struct is as follows:

\begin{idllisting}
// IDL
struct exampleStruct1 {
  string s;
  double d;
  long   l;
};
\end{idllisting}

To create a DynAny from an Any value, one uses the
\op{create\_dyn\_any} method:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
  
Any v;
...       // Initialise v to contain a value of type exampleStruct1.
  
CORBA::DynAny_var dv = orb->create_dyn_any(v);
\end{cxxlisting}

Like CORBA object and pseudo object references, a \type{DynAny\_ptr}
can be managed by a \type{\_var} type (\type{DynAny\_var}) which will
release the \type{DynAny\_ptr} automatically when the variable goes
out of scope.

\subsubsection{Iterate through the components}
\label{dynanyiterate}

Once the DynAny object is created, we can use the DynAny interface to
extract the individual components in \type{exampleStruct1}. The DynAny
interface provides a number of functions to extract and insert
component values. These functions are defined to operate on the
component identified by the \term{current component} pointer.

A \term{current component} pointer is an internal state of a DynAny
object. When a DynAny object is created, the pointer is initialised
to point to the first component of the any value.

The pointer can be advanced to the next component with the \op{next}
operation. The function returns FALSE (0) if there are no more
components.  Otherwise it returns TRUE (1). When the any value in the
DynAny object contains only one component, the \op{next()} operation
always returns FALSE(0).

Another way of adjusting the pointer is the \op{seek} operation. The
function returns FALSE (0) if there is no component at the specified
index. Otherwise it returns TRUE (1). The index value of the first
component is zero. Therefore, a \code{seek(0)} call rewinds the
pointer to the first component, this is also equivalent to a call to
the \op{rewind} operation.

For completeness, we should also mention here the
\op{current\_component} operation. This operation causes the DynAny
object to return a reference to another DynAny object that can be used
to access the current component. It is possible that the current
component pointer is not pointing to a valid component, for instance,
the \op{next} operation has been invoked and there is no more
component. Under this circumstance, the \op{current\_component}
operation returns a nil DynAny object reference\footnote{Testing a nil
DynAny object with CORBA::is\_nil() returns TRUE(1). The CORBA 2.2
specification does not specify what is the return value of this
function when the current component pointer is invalid. To ensure
portability, it is best to avoid calling \op{current\_component} under
this condition.}. For components which are just basic data types,
calling \op{current\_component} is an overkill because we can just use
the basic type extraction and insertion functions directly.

\subsubsection{Extract basic type components}

In our example, the component values can be extracted as follows:

\begin{cxxlisting}
CORBA::String_var s = dv->get_string();
CORBA::Double     d = dv->get_double();
CORBA::Long       l = dv->get_long();
\end{cxxlisting}

Each get basic type operation has the side-effect of advancing the
current component pointer. For instance:

\begin{cxxlisting}
CORBA::String_var s = dv->get_string();
\end{cxxlisting}

is equivalent to:

\begin{cxxlisting}
CORBA::DynAny_var temp = dv->current_component();
CORBA::String_var s = temp->get_string();
dv->next();
\end{cxxlisting}

The get operations ensure that the current component is of the same
type as requested. Otherwise, the object throws a \code{TypeMismatch}
exception. If the current component pointer is invalid when a get
operation is called, the object also throws a \code{TypeMismatch}
exception\footnote{The CORBA 2.2 specification does not define the
behavior of this error condition. To ensure portability, it is best to
avoid calling the get operations when the current component pointer is
known to be invalid.}.

To repeatedly access the components, one can use the \op{rewind} or
\op{seek} operations to manipulate the current component pointer. For
instance, to access the \code{d} member in \type{exampleStruct1}
directly:

\begin{cxxlisting}
dv->seek(1);       // position current component to member d.
CORBA::Double d = dv->get_double();
\end{cxxlisting}

\subsubsection{Extract complex components}

When a component is not one of the basic data types, it is not
possible to extract its value using the get operations. Instead, a
DynAny object has to be created from which the component is accessed.

Consider this example:

\begin{idllisting}
// IDL
struct exampleStruct2 {
  string m1;
  exampleStruct1 m2;
};
\end{idllisting}

In order to extract the data members within \code{m2} (of type
\type{exampleStruct1}), we use \op{current\_component} as follows:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
Any v;
...       // Initialise v to contain a value of type exampleStruct2.

CORBA::DynAny_var dv = orb->create_dyn_any(v);

CORBA::String_var m1 = dv->get_string();  // extract member m1
CORBA::DynAny_var dm = dv->current_component(); // DynAny reference to m2
CORBA::String_var s = dm->get_string();   // m2.s
CORBA::Double     d = dm->get_double();   // m2.d
CORBA::Long       l = dm->get_long();     // m2.l
\end{cxxlisting}


\subsubsection{Clean-up}
Now we finish off this example with a description on destroying DynAny
objects. There are two points to remember:

\begin{enumerate}
\item A DynAny reference (\type{DynAny\_ptr}) is like any CORBA object
or psuedo object reference and should be handled in the same way. In
particular, one has to call the \op{CORBA::release} operation to
indicate that a DynAny reference will no longer be accessed. In the
example, this is done automatically by \type{DynAny\_var}.

\item A DynAny object and its references are separate entities, just
as a CORBA object implementation and its object references are
different entities. While \op{CORBA::release} will release any
resources associated with a \type{DynAny\_\dsc{}ptr}, one has to
separately destroy the DynAny object to avoid any memory leak. This is
done by calling the \op{destroy()} operation.
\end{enumerate}

In the example, the DynAny object can be destroyed as follows:

\begin{cxxlisting}
// C++
...
CORBA::DynAny_var dv = orb->create_dyn_any(v);
...
dv->destroy();

// From now on, one should not invoke any operation in dv.
// Otherwise the behaviour is undefined.
\end{cxxlisting}


\subsection{Example: insert data values into an Any}

Using the DynAny interface, one can create an Any value from scratch.
In this example, we are going to create an Any containing a value of
the \type{exampleStruct1} type.

First, we have to create a DynAny to store the value using one of the
\op{create\_\dsc{}dyn} functions. Because \type{exampleStruct1} is a
struct, we use the \op{create\_\dsc{}dyn\_\dsc{}struct} operation.

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.

// create the TypeCode for exampleStruct.
StructMemberSeq tc_members;
tc_members.length(3);
tc_members[0].name = (const char*)"s";
tc_members[0].type = CORBA::TypeCode::_duplicate(CORBA::_tc_string);
tc_members[0].type_def = CORBA::IDLType::_nil();
tc_members[1].name = (const char*)"d";
tc_members[1].type = CORBA::TypeCode::_duplicate(CORBA::_tc_double);
tc_members[1].type_def = CORBA::IDLType::_nil();
tc_members[2].name = (const char*)"l";
tc_members[2].type = CORBA::TypeCode::_duplicate(CORBA::_tc_long);
tc_members[2].type_def = CORBA::IDLType::_nil();
CORBA::TypeCode_var tc = orb->create_struct_tc("IDL:exampleStruct1:1.0",
                                               "exampleStruct1",
                                               tc_members);

// create the DynAny object to represent the any value
CORBA::DynAny_var dv = orb->create_dyn_struct(tc);
\end{cxxlisting}


\subsubsection{Insert basic type components}

Once the DynAny object is created, we can use the DynAny interface to
insert the components. The DynAny interface provides a number of
insert operations to insert basic types into the any value. In our
example, the component values can be inserted as follows:

\begin{cxxlisting}
CORBA::String_var s = (const char*)"Hello";
CORBA::Double     d = 3.1416;
CORBA::Long       l = 1;

dv->insert_string(s);
dv->insert_double(d);
dv->insert_long(l);
\end{cxxlisting}

Each insert basic type operation has the side-effect of advancing the
current component pointer. For instance:

\begin{cxxlisting}
dv->insert_string(s);
\end{cxxlisting}

is equivalent to:

\begin{cxxlisting}
CORBA::DynAny_var temp = dv->current_component();
temp->insert_string(s);
dv->next();
\end{cxxlisting}

The insert operations ensure that the current component is of the same
type as the inserted value. Otherwise, the object throws an
\code{InvalidValue} exception. If the current component pointer is
invalid when an insert operation is called, the object also throws a
\code{InvalidValue} exception\footnote{The CORBA 2.2 specification
does not define the behavior of this error condition. To ensure
portability, it is best to avoid calling the insert operations when
the current component pointer is known to be invalid.}.

Sometimes, one may just want to modify one component in an Any
value. For instance, one may just want to change the value of the
double member in \type{exampleStruct1}. This can be done as follows:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.

Any v;
...       // Initialise v to contain a value of type exampleStruct1.

CORBA::Double d = 6.28;

CORBA::DynAny_var dv = orb->create_dyn_any(v);

dv->seek(1);
dv->insert_double(d);    // Change the value of the member d.
\end{cxxlisting}

Finally, the any value can be obtained from the DynAny object using
the \op{to\_any} operation:

\begin{cxxlisting}
CORBA::Any_var v = dv->to_any();    // Obtain the any value.
\end{cxxlisting}


\subsubsection{Insert complex components}

When a component is not one of the basic data types, it is not
possible to insert its value using the insert operations. Instead, a
DynAny object has to be created through which the component can be
inserted.

In our example, one can insert component values into
\type{exampleStruct2} as follows:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
  
CORBA::TypeCode_var tc;
// create the TypeCode for exampleStruct2.
...
// create the DynAny object to represent the any value
CORBA::DynAny_var dv = orb->create_dyn_struct(tc);
  
CORBA::String_var m1  = (const char*)"Greetings";
CORBA::String_var m2s = (const char*)"Hello";
CORBA::Double     m2d = 3.1416;
CORBA::Long       m2l = 1;
  
dv->insert_string(m1);   // insert member m1
CORBA::DynAny_var dm = dv->current_component(); // DynAny reference to m2
dm->insert_string(m2s);  // insert member m2.s
dm->insert_double(m2d);  // insert member m2.d
dm->insert_long(m2l);    // insert member m2.l
  
CORBA::Any_var v = dv->to_any();  // obtain the any value
  
dv->destroy();          // destroy the DynAny object.
                        // No operation should be invoked on dv
                        // from this point on except CORBA::release.
\end{cxxlisting}


In addition to the DynAny interface, a number of derived interfaces
are defined. These interfaces are specialisation of the DynAny
interface to facilitate the handling of any values containing
non-basic types: struct, sequence, array, enum and union\footnote{In
the CORBA 2.2 specification, the DynFixed interface is defined to
handle the fixed data type. This is not supported in this
implementation.}. The next few sections will provide more details on
these interfaces.

\section{The DynStruct Interface}

When a DynAny object is created through the \op{create\_dyn\_any}
operation and the any value contains a struct type, a \type{DynStruct}
object is created. The DynAny reference returned can be narrowed to a
\type{DynStruct} reference using the \op{CORBA::DynStruct::\_narrow}
operation.

In the previous example, the components are extracted using the get
operations. Alternatively, the DynStruct interface provides an
additional operation (\op{get\_members}) to return all the components
in a single call. The returned value is a sequence of name value
pairs. The member name is given in the name field and its value is
returned as an Any value.  For example, an alternative way to extract
the components in the previous example is as follows:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
Any v;
...       // Initialise v to contain a value of type exampleStruct1.
CORBA::DynAny_var dv = orb->create_dyn_any(v);
  
CORBA::DynStruct_var ds = CORBA::DynStruct::_narrow(dv);
  
CORBA::NameValuePairSeq* sq = ds->get_members();
  
char*         s;
CORBA::Double d;
CORBA::Long   l;
  
(*sq)[0].value >>= s;        // 1st element contains member s
(*sq)[1].value >>= d;        // 2nd element contains member d
(*sq)[2].value >>= l;        // 3rd element contains member l
\end{cxxlisting}


Similarly, the DynStruct interface provides an additional operation
(\op{set\_members}) to insert all the components in a single call. The
following is an alternative way to insert the components of the type
\type{exampleStruct1} into an Any value:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
  
CORBA::TypeCode_var tc;
// create the TypeCode for exampleStruct1.
...
// create the DynAny object to represent the any value
CORBA::DynAny_var dv = orb->create_dyn_struct(tc);
  
CORBA::String_var s = (const char*)"Hello";
CORBA::Double     d = 3.1416;
CORBA::Long       l = 1;
  
CORBA::NameValuePairSeq sq;
sq.length(3);
sq[0].id = (const char*)"s";
sq[0].value <<= CORBA::Any::from_string(s,0); 
                               // 1st element contains member s
sq[1].id = (const char*)"d";
sq[1].value <<= d;             // 2nd element contains member d
sq[2].id = (const char*)"l";
sq[2].value <<= l;             // 3rd element contains member l
  
dv->set_members(sq);    
\end{cxxlisting}

Notice that the name-value pairs in the argument to \op{set\_members}
must match the members of the struct exactly or the object would throw
the \code{InvalidSeq} exception.

In addition to the \op{current\_component} operation, the DynStruct
interface provides two operations: \op{current\_member\_name} and
\op{current\_member\_\dsc{}kind}, to return information about the
current component.

\section{The DynSequence Interface}

Like struct values, sequence values can be traversed using the
operations introduced in section~\ref{dynany}. The first sequence
element can be accessed as the first DynAny component, the second
sequence element as the second DynAny component and so on.

To extract component values from an Any containing a sequence, the
length of the sequence can be obtained using the get length operation
in the DynSequence interface. Here is an example to extract the
components of a sequence of long:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
Any v;
...       // Initialise v to contain a value of a sequence of long
CORBA::DynAny_var dv = orb->create_dyn_any(v);
  
CORBA::DynSequence_var ds = CORBA::DynSequence::_narrow(dv);
CORBA::ULong len = ds->length();     // extract the length of the sequence
CORBA::ULong index;
for (index = 0; index < len; index++) {
  CORBA::Long v = ds->get_long();
  cerr << "[" << index << "] = " << v << endl;
}
\end{cxxlisting}

Conversely, the set length operation is provided to set the length of
the sequence. Here is an example to insert the components of a
sequence of long:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
  
CORBA::TypeCode_var tc;
// create the TypeCode for a sequence of long.
...
// create the DynAny object to represent the any value
CORBA::DynSequence_var ds = orb->create_dyn_sequence(tc);
  
CORBA::ULong len = 3;
  
ds->length(len);             // set the length of the sequence
  
CORBA::ULong index;
for (index = 0; index < len; index++) {
  ds->insert_long(index);    // insert a sequence element
}
\end{cxxlisting}

Similar to the DynStruct interface, the \op{get\_elements} operation
is provided to return all the sequence elements and the
\op{set\_elements} operation is provided to insert all the sequence
elements.

\section{The DynArray Interface}

Array values are handled by the DynArray interface. The DynArray
interface is the same as the DynSequence interface except that the
former does not provide the set length and get length operations.

\section{The DynEnum Interface}

Enum values are handled by the DynEnum interface. A DynEnum object
contains a single component which is the enum value. This value cannot
be extracted or inserted using the get and insert operations of the
DynAny interface. Instead, two pairs of operations are provided to
handle this value.

The \op{value\_as\_string} operation allows the enum value to be
extracted or inserted as a string. The \op{value\_as\_ulong} operation
allows the enum value to be extracted or inserted as an unsigned long.


\section{The DynUnion Interface}

Union values are handled by the DynUnion interface. Unfortunately, the
CORBA 2.2 specification does not define the DynUnion interface in
sufficient details to nail down its intended usage\footnote{This
interface is currently an open issue with the ORB revision task
force.}. In this section, we try to fill in the gaps and describe a
sensible way to use the DynUnion interface. Where necessary, the
semantics of the operations is clarified. It is possible that the
behavior of this interface in another ORB is different from this
implementation. Where appropriate, we give warnings on usage that
might cause problems with portability.

In relation to the current component pointer
(section~\ref{dynanyiterate}), a DynUnion object contains two
components. The first component (with the index value equals 0) is the
discriminator value, the second one is the member value.  Therefore,
one can use the \op{seek} and \op{current\_component} operations to
obtain a reference to the DynAny objects that handle the two
components. However, it is better to use the operations defined in the
DynUnion interface to manipulate these components as the semantics of
the operations is easier to understand.

\subsection{Three Categories of Union}
\label{dynunioncat}

Before we continue, it is important to understand that unions can be
classified into the following categories:

\begin{enumerate}
\item One that has a default branch defined in the IDL. This will be
called \term{explicit default union} in the rest of this section.
\item One that has no default branch and not all the possible values
of the discriminator type are covered by the branch labels in the IDL.
This will be called \term{implicit default union}.
\item One that has no default branch but all the possible values of
the discriminator type are covered. This will be called \term{no
default union}.
\end{enumerate}

Of the three categories, the implicit default union is interesting
because by definition if the discriminator value is not equal to any
of the branch labels, the union has \emph{no} member. That is, the
union value consists solely of the discriminator value.

\subsection{Example: extract data values from a union}

\subsubsection{Explicit default union}

Consider a union of the following type:

\begin{idllisting}
// IDL
union exampleUnion1 switch(boolean) {
case TRUE: long l;
default:   double d; 
};
\end{idllisting}

The most straightforward way to extract the member value is as
follows:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
  
Any v;
...       // Initialise v to contain a value of type exampleUnion1.
  
CORBA::DynAny_var dv = orb->create_dyn_any(v);
CORBA::DynUnion_var du = CORBA::DynUnion::_narrow(dv);
  
CORBA::String_var di = du->member_name();
CORBA::DynAny_var dm = du->member();
  
if (strcmp((const char*)di,"l") == 0) {
  // branch label is TRUE
  CORBA::Long v = dm->get_long();
  cerr << "l = " << v << endl;
}
  
if (strcmp((const char*)di,"d") == 0) {
  // Is default branch
  CORBA::Double v = dm->get_double();
  cerr << "d = " << v << endl;
}
\end{cxxlisting}

In the example, the operation \op{member\_name} is used to determine
which branch the union has been instantiated. The operation
\op{member} is used to obtain a reference to the DynAny object that
handles the member.

Alternatively, the branch can be determined by reading the
discriminator value:

\begin{cxxlisting}
// C++
CORBA::DynAny_var di = du->discriminator();
CORBA::DynAny_var dm = du->member();
  
CORBA::Boolean di_v = di->get_boolean();
  
switch (di_v) {
case 1:
  CORBA::Long v = dm->get_long();
  cerr << "l = " << v << endl;
  break;
default:
  CORBA::Double v = dm->get_double();
  cerr << "d = " << v << endl;
}
\end{cxxlisting}

The operation \op{discriminator} is used to obtain the value of the
discriminator.

Finally, the third way to determine the branch is to test if the
default is selected:

\begin{cxxlisting}
// C++
switch (dv->set_as_default()) {
case 1:
  CORBA::Double v = dm->get_double();
  cerr << "d = " << v << endl;
  break;
default:
  CORBA::Long v = dm->get_long();
  cerr << "l = " << v << endl;
}
\end{cxxlisting}

The operation \op{set\_as\_default()} returns TRUE (1) if the
discriminator has been assigned a valid default value.


\subsubsection{Implicit default union}

Consider a union of the following type:

\begin{idllisting}
// IDL
union exampleUnion2 switch(long) {
case 1: long l;
case 2: double d; 
};
\end{idllisting}

This example is similar to the previous one but there is no default
branch.  The description above also applies to this example. However,
the discriminator may be set to neither 1 nor 2. Under this condition,
the implicit default is selected and the union value contains the
discriminator only!

When the discriminator contains an implicit default value, one might
ask what is the value returned by the \op{member\_name} and
\op{member} operation. Since there is no member in the union value,
omniORB returns a null string and a nil DynAny reference respectively.
This behavior is not specified in the CORBA 2.2 specification. To
ensure that your application is portable, it is best to avoid calling
these operations when the DynUnion object might contain an implicit
default value.

\subsubsection{No default union}

This is the last union category. For instance:

\begin{idllisting}
// IDL
union exampleUnion3 switch(boolean) {
case TRUE: long l;
case FALSE: double d; 
};
\end{idllisting}

In this example, all the possible values of the discriminator are used
as union labels. There is no default branch. The only difference
between this category and the explicit default union is that the
\op{set\_as\_default} operation always returns FALSE (0).


\subsection{Example: insert data values into a union}

Writing into a union involves selecting the union branch with the
appropriate discriminator value and then writing the member value.
There are three ways to set the discriminator value:

\begin{enumerate}

\item Use the \op{member\_name()} write operation to specify the union
branch by specifying the union member directly. This operation has the
side effect of setting the discriminator to the label value of the
branch.

\item Write the label value of a union branch into the DynAny object
that handles the discriminator.

\item If the union has a default branch, either explicitly or
implicitly, use the \op{set\_\dsc{}as\_default()} write operation to
set the discriminator to a valid default value.

\end{enumerate}

The following example shows the three ways of writing into a union:

\begin{cxxlisting}
// C++
CORBA::ORB_ptr orb;  // orb initialised by CORBA::ORB_init.
  
CORBA::TypeCode_var tc;
// create the TypeCode for exampleUnion1.
...
// create the DynAny object to represent the any value
CORBA::DynUnion_var dv = orb->create_dyn_union(tc);
  
CORBA::Any_var v;
DynAny_ptr dm;
  
// Use member_name to select the union branch
dv->member_name("l");
dm = dv->member();
dm->insert_long(10);
v = dv->to_any();          // transfer to an Any
CORBA::release(dm);

// Setting the discriminator value to select the union branch
CORBA::DynAny_var di = dv->discriminator();
di->insert_boolean(1);     // set discriminator to label TRUE
dm = dv->member();
dm->insert_long(20);
v = dv->to_any();          // transfer to an Any
CORBA::release(dm);

// Use set_as_default to select the default union branch
dv->set_as_default(1);
dm = dv->member();
dm->insert_double(3.14);
v = dv->to_any();          // transfer to an Any
CORBA::release(dm);

dv->destroy();
\end{cxxlisting}


\subsubsection{Ambiguous usage}

\begin{enumerate}

\item When the discriminator is set to a different value, a different
member branch is selected. Suppose the application has previously
obtained a DynAny reference to a union member when it changes the
discriminator value. As a result of the value change, the union is now
instantiated to another union branch, i.e.\ a call to the \op{member}
operation will now return a reference to a different DynAny object. If
the application continues to access the DynAny object of the old union
member, the behavior of the ORB under this condition is not defined by
the CORBA 2.2 specification. With omniORB, the DynAny object of the
old union member is detached from the union when a new union branch is
selected. Therefore reading or writing this object will not have any
relation to the current value of the union. To avoid this ambiguity,
the reference to the old union member should be released before a
different union branch is selected.

\item The write operation \op{set\_as\_default} takes a boolean
argument. It is ambiguous to call this function with the argument set
to FALSE (0). With omniORB, such a call will be silently ignored.

\item It is also ambiguous to pass the value TRUE (1) to the
\op{set\_as\_default} operation when the union is a no default union
(\ref{dynunioncat}). With omniORB, such a call will be silently
ignored.

\item When the discriminator value is not set, calling the \op{member}
operation is ambiguous. With omniORB, such a call will return a nil
DynAny reference. Similarly, a call to the \op{member\_kind} operation
under this condition will return \code{tk\_null}.

\end{enumerate}

To ensure portability, it is best to avoid using the DynUnion
interface and not to rely on the ORB to behave as omniORB does under
these ambiguous conditions.

\section{Duplicate DynAny References}

Like any CORBA object and psuedo object references, a DynAny reference
can be duplicated using the \op{\_duplicate()} operations. When an
application has obtained multiple DynAny references to the same DynAny
object, it should be noted that a change made to the object by
invoking on one reference is also visible through the other
references. In particular, if a call through one reference has caused
the current component pointer to be changed, subsequent calls through
other references will operate on the new current component pointer.


\section{Other Operations}

The following is a short summary of the other operations in the DynAny
interface which have not been covered in previous sections:

\begin{description}
\item[\op{assign}] initialises a DynAny object with another DynAny
object. The two objects must have the same typecode.

\item[\op{from\_any}] initialises a DynAny object from the value in an
any. The typecode in the two objects must be the same.

\item[\op{copy}] creates a new DynAny object whose value is a deep
copy of the current object.

\item[\op{type}] returns the typecode associated with the DynAny
object.

\end{description}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The Dynamic Invocation Interface}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The Dynamic Invocation Interface (or DII) allows applications to
invoke operations on CORBA objects about which they have no static
information. That is to say the application has not been linked with
stub code which performs the remote operation invocation. Thus using
the DII applications may invoke operations on \emph{any} CORBA object,
possibly determining the object's interface dynamically by using an
Interface Repository.
% ?? Ref IR section?

This chapter presents an overview of the Dynamic Invocation Interface.
A toy example use of the DII can be found in the omniORB distribution
in the \file{src/examples/dii} directory.  The DII makes extensive use
of the type Any, so ensure that you have read chapter~\ref{ch_any}.
For more information refer to the Dynamic Invocation Interface and C++
Mapping sections of the CORBA specification~\cite{corba23-spec}.


\section{Overview}

To invoke an operation on a CORBA object an application needs an
object reference, the name of the operation and a list of the
parameters. In addition the application must know whether the
operation is one-way, what user-defined exceptions it may throw, any
user-context strings which must be supplied, a `context' to take these
values from and the type of the returned value. This information is
given by the IDL interface declaration, and so is normally made
available to the application via the stub code. In the DII this
information is encapsulated in the \type{CORBA::Request}
pseudo-object.

To perform an operation invocation the application must obtain an
instance of a \type{Request} object, supply the information listed
above and call one of the methods to actually make the invocation. If
the invocation causes an exception to be thrown then this may be
retrieved and inspected, or the return value on success.


\section{Pseudo Objects}

The DII defines a number of psuedo-object types, all defined in the
\code{CORBA} namespace. These objects behave in many ways like CORBA
objects. They should only be accessed by reference (through
\type{foo\_ptr} or \type{foo\_var}), may not be instantiated directly
and should be released by calling \op{CORBA::release}\footnote{if not
managed by a \type{\_var} type.}.  A nil reference should only be
represented by \code{foo::\_nil()}.

These pseudo objects, although defined in pseudo-IDL in the
specification do not follow the normal mapping for CORBA objects. In
particular the memory management rules are different---see the CORBA
2.3 specification~\cite{corba23-spec} for more details. New instances
of these objects may only be created by the ORB. A number of methods
are defined in \type{CORBA::ORB} to do this.


\subsection{Request}

A \type{Request} encapsulates a single operation invocation. It may
\emph{not} be re-used---even for another call with the same arguments.

\begin{cxxlisting}
class Request {
public:
  virtual Object_ptr        target() const;
  virtual const char*       operation() const;
  virtual NVList_ptr        arguments();
  virtual NamedValue_ptr    result();
  virtual Environment_ptr   env();
  virtual ExceptionList_ptr exceptions();
  virtual ContextList_ptr   contexts();
  virtual Context_ptr       ctxt() const;
  virtual void              ctx(Context_ptr);

  virtual Any& add_in_arg();
  virtual Any& add_in_arg(const char* name);
  virtual Any& add_inout_arg();
  virtual Any& add_inout_arg(const char* name);
  virtual Any& add_out_arg();
  virtual Any& add_out_arg(const char* name);

  virtual void set_return_type(TypeCode_ptr tc);
  virtual Any& return_value();

  virtual Status  invoke();
  virtual Status  send_oneway();
  virtual Status  send_deferred();
  virtual Status  get_response();
  virtual Boolean poll_response();

  static Request_ptr _duplicate(Request_ptr);
  static Request_ptr _nil();
};
\end{cxxlisting}


\subsection{NamedValue}

A pair consisting of a string and a value---encapsulated in an Any.
The name is optional. This type is used to encapsulate parameters and
returned values.

\begin{cxxlisting}
class NamedValue {
public:
  virtual const char* name() const;
  // Retains ownership of return value.

  virtual Any* value() const;
  // Retains ownership of return value.

  virtual Flags flags() const;

  static NamedValue_ptr _duplicate(NamedValue_ptr);
  static NamedValue_ptr _nil();
};
\end{cxxlisting}


\subsection{NVList}

A list of \type{NamedValue} objects.

\begin{cxxlisting}
class NVList {
public:
  virtual ULong count() const;
  virtual NamedValue_ptr add(Flags);
  virtual NamedValue_ptr add_item(const char*, Flags);
  virtual NamedValue_ptr add_value(const char*, const Any&, Flags);
  virtual NamedValue_ptr add_item_consume(char*,Flags);
  virtual NamedValue_ptr add_value_consume(char*, Any*, Flags);
  virtual NamedValue_ptr item(ULong index);
  virtual Status remove (ULong);

  static NVList_ptr _duplicate(NVList_ptr);
  static NVList_ptr _nil();
};
\end{cxxlisting}


\subsection{Context}

Represents a set of context strings.

\begin{cxxlisting}
class Context {
public:
  virtual const char* context_name() const;
  virtual CORBA::Context_ptr parent() const;
  virtual CORBA::Status create_child(const char*, Context_out);
  virtual CORBA::Status set_one_value(const char*, const CORBA::Any&);
  virtual CORBA::Status set_values(CORBA::NVList_ptr);
  virtual CORBA::Status delete_values(const char*);
  virtual CORBA::Status get_values(const char* start_scope,
                                   CORBA::Flags op_flags,
                                   const char* pattern,
                                   CORBA::NVList_out values);
  // Throws BAD_CONTEXT if <start_scope> is not found.
  // Returns a nil NVList in <values> if no matches are found.

  static Context_ptr _duplicate(Context_ptr);
  static Context_ptr _nil();
};
\end{cxxlisting}


\subsection{ContextList}

A \type{ContextList} is a list of strings, and is used to specify
which strings from the `context' should be sent with an operation.

\begin{cxxlisting}
class ContextList {
public:
  virtual ULong count() const;
  virtual void add(const char* ctxt);
  virtual void add_consume(char* ctxt);
  // consumes ctxt

  virtual const char* item(ULong index);
  // retains ownership of return value

  virtual Status remove(ULong index);

  static ContextList_ptr _duplicate(ContextList_ptr);
  static ContextList_ptr _nil();
};
\end{cxxlisting}



\subsection{ExceptionList}

\type{ExceptionList}s contain a list of TypeCodes---and are used to
specify which user-defined exceptions an operation may throw.

\begin{cxxlisting}
class ExceptionList {
public:
  virtual ULong count() const;
  virtual void add(TypeCode_ptr tc);
  virtual void add_consume(TypeCode_ptr tc);
  // Consumes <tc>.

  virtual TypeCode_ptr item(ULong index);
  // Retains ownership of return value.

  virtual Status remove(ULong index);

  static ExceptionList_ptr _duplicate(ExceptionList_ptr);
  static ExceptionList_ptr _nil();
};
\end{cxxlisting}



\subsection{UnknownUserException}

When a user-defined exception is thrown by an operation it is
unmarshalled into a value of type Any. This is encapsulated in an
\type{UnknownUserException}. This type follows all the usual rules for
user-defined exceptions---it is not a pseudo object, and its resources
may be released by using \code{delete}.

\begin{cxxlisting}
class UnknownUserException : public UserException {
public:
  UnknownUserException(Any* ex);
  // Consumes <ex> which MUST be a UserException.

  virtual ~UnknownUserException();

  Any& exception();

  virtual void _raise();
  static const UnknownUserException* _downcast(const Exception*);
  static UnknownUserException* _downcast(Exception*);
  static UnknownUserException* _narrow(Exception*); 
  // _narrow is a deprecated function from CORBA 2.2, 
  // use _downcast instead.
};
\end{cxxlisting}



\subsection{Environment}

An \type{Environment} is used to hold an instance of a system
exception or an \type{UnknownUserException}.

\begin{cxxlisting}
class Environment {
  virtual void exception(Exception*);
  virtual Exception* exception() const;
  virtual void clear();

  static Environment_ptr _duplicate(Environment_ptr);
  static Environment_ptr _nil();
};
\end{cxxlisting}



\section{Creating Requests}

\type{CORBA::Object} defines three methods which may be used to create
a \type{Request} object which may be used to perform a single
operation invocation on that object:

\begin{cxxlisting}
class Object {
  ...
  Status _create_request(Context_ptr ctx,
                         const char* operation,
                         NVList_ptr arg_list,
                         NamedValue_ptr result,
                         Request_out request,
                         Flags req_flags);

  Status _create_request(Context_ptr ctx,
                         const char* operation,
                         NVList_ptr arg_list,
                         NamedValue_ptr result,
                         ExceptionList_ptr exceptions,
                         ContextList_ptr ctxlist,
                         Request_out request,
                         Flags req_flags);

  Request_ptr _request(const char* operation);
  ...
};
\end{cxxlisting}


\code{operation} is the name of the operation---which is the same as
the name given in IDL. To access attributes the name should be
prefixed by \code{\_get\_} or \code{\_set\_}.

In the first two cases above the list of parameters may be supplied.
If the parameters are not supplied in these cases, or \op{\_request}
is used then the parameters (if any) may be specified using the
\op{add\_*\_arg} methods on the \type{Request}. You must use one
method or the other---not a mixture of the two. For
\emph{in}/\emph{inout} arguments the value must be initialised, for
\emph{out} arguments only the type need be given.  Similarly the type
of the result may be specified by passing a \type{NamedValue} which
contains an Any which has been initialised to contain a value of that
type, or it may be specified using the \op{set\_return\_type} method
of \type{Request}.

When using \op{\_create\_request}, the management of any pseudo-object
references passed in remains the responsibility of the
application. That is, the values are not consumed---and must be
released using \op{CORBA::release}. The CORBA specification is unclear
about when these values may be released, so to be sure of portability
do not release them until after the request has been released.  Values
which are not needed need not be supplied---so if no parameters are
specified then it defaults to an empty parameter list. If no result
type is specified then it defaults to void. A \type{Context} need only
be given if a non-empty \type{ContextList} is specified. The
\code{req\_flags} argument is not used in the C++ mapping.


\subsection{Examples}

An operation might be specified in IDL as:

\begin{idllisting}
short anOpn(in string a);
\end{idllisting}

\noindent An operation invocation may be created as follows:

\begin{cxxlisting}
CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB3");
...
CORBA::NVList_var args;
orb->create_list(1, args);
*(args->add(CORBA::ARG_IN)->value()) <<= (const char*) "Hello World!";

CORBA::NamedValue_var result;
orb->create_named_value(result);
result->value()->replace(CORBA::_tc_short, 0);

CORBA::Request_var req = obj->_create_request(CORBA::Context::_nil(),
                                        "anOpn", args, result, 0);
\end{cxxlisting}

\noindent or alternatively and much more concisely:

\begin{cxxlisting}
CORBA::Request_var req = obj->_request("anOpn");
req->add_in_arg() <<= (const char*) "Hello World!";
req->set_return_type(CORBA::_tc_short);
\end{cxxlisting}


\section{Invoking Operations}
\label{dii_invoke}

Once the \type{Request} object has been properly constructed, the
operation may be invoked by calling one of the following methods on
the request object:

\paragraph{\op{invoke}}

blocks until the request has completed. The application should then
test to see if an exception was raised. Since the CORBA spec is not
clear about whether or not system exceptions should be thrown from
this method, a runtime configuration variable is supplied so that you
can specify the behavior:

\begin{cxxlisting}
namespace omniORB {
  ...
  CORBA::Boolean diiThrowsSysExceptions;
  ...
};
\end{cxxlisting}

If this is FALSE, and the application should call the \op{env} method
of the request to retrieve an exception (it returns 0 (nil) if no
exception was generated). If it is TRUE then system exceptions will be
thrown out of \op{invoke}. User-defined exceptions are always passed
via \op{env}, which will return a pointer to a
\type{CORBA::UnknownUserException}.  The application can determine
which type of exception was returned by \op{env()} by calling the
\op{\_narrow} method defined for each exception type.

\begin{statement}
\centerline{\textbf{Warning}}

In pre-omniORB 2.8.0 releases, the default value of
\code{diiThrowsSysExceptions} is FALSE. From omniORB 2.8.0 onwards,
the default value is TRUE.

\end{statement}

After determining that no exception was thrown the application may
retrieve any returned values by calling \op{return\_value} and
\op{arguments}.

\paragraph{\op{send\_oneway}}

has the same semantics as a \emph{oneway} IDL operation. It is
important to note that oneway operations have at-most-once semantics,
and it is not guaranteed that they will not block. Any operation may
be invoked `oneway' using the DII, even if it was not declared as
`oneway' in IDL. A system exception may be generated, in which case it
will either be thrown or may be retrieved using \op{env} depending on
\code{diiThrowsSysExceptions} as above.

\paragraph{\op{send\_deferred}}

initiates the invocation, and then returns without waiting for the
result. At some point in the future the application must retrieve the
result of the operation---but other than testing for completion of the
operation the application must not call any of the request's methods
in the meantime.

\begin{itemize}
\item \op{get\_response} blocks until the reply is received.
\item \op{poll\_response} returns TRUE if the reply has been received,
      and FALSE if not. It does not block.
\end{itemize}

Once \op{poll\_response} has returned TRUE, or \op{get\_response} has
been called and returned, the application may test for an exception
and retrieve returned values as above. If
\code{diiThrowsSysExceptions} is true, then a system exception may be
thrown from \op{get\_response}.  From omniORB 2.8.0 onwards,
\op{poll\_response} will raise a system exception if one has occurred
during the invocation. Previously, \op{poll\_response} would not raise
an exception, so if polling, the application also had to call another
method to give the request an opportunity to raise the exception. This
could be one of the methods to retrieve values from the request, or
\op{get\_response}.


\section{Multiple Requests}

The following methods are provided by the ORB to enable multiple requests to
be invoked asynchronously.

\begin{cxxlisting}
namespace CORBA {
  ...
  class ORB {
  public:
    ...
    Status send_multiple_requests_oneway(const RequestSeq&);
    Status send_multiple_requests_deferred(const RequestSeq&);
    Boolean poll_next_response();
    Status get_next_response(Request_out);
    ...
  };
  ...
};
\end{cxxlisting}

\paragraph{\op{send\_multiple\_requests\_oneway}}

is used to invoke a number of oneway requests. An attempt will be made
to invoke each of the requests, even if one or more of the early
requests fails.  The application may check for failure of any of the
requests by testing the request's \op{env} method. System exceptions
are never raised by this method.

\paragraph{\op{send\_multiple\_requests\_deferred}}

will initiate an invocation of each of the given requests, and return
without waiting for the reply.  At some point in the future the
application must retrieve the reply by calling
\op{get\_next\_response}, which returns a completed request.  If no
requests have yet completed it will block.  This method never throws
exceptions---the request's \op{env} method must be used to determine
if an exception was generated. If not then any returned values may
then be queried.

\op{poll\_next\_response} returns TRUE if there are any completed
requests, and FALSE otherwise, without blocking. If this returns true
then the next call to \op{get\_next\_response} will not block.
However, if another thread may also be calling
\op{get\_next\_response} then it could retrieve the completed message
first---in which case this thread might block.

There are no guarantee as to the order in which replies will be
received.  If multiple threads are using this interface then it is not
even guaranteed that a thread will receive replies to the requests it
sent. Any thread may receive replies to requests sent by any other
thread. It is legal to call \op{get\_next\_response} even if no
requests have yet been invoked---in which case the calling thread
blocks until another thread invokes a request and the reply is
received.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The Dynamic Skeleton Interface}
\label{chap:dsi}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The Dynamic Skeleton Interface (or DSI) allows applications to provide
implementations of the operations on CORBA objects without static
knowledge of the object's interface. It is the server-side equivalent
of the Dynamic Invocation Interface.

This chapter presents the Dynamic Skeleton Interface and explains how
to use it.  A toy example use of the DSI can be found in the omniORB
distribution in the \file{src/examples/dsi} directory.  For further
information refer to the Dynamic Skeleton Interface and C++ Mapping
sections of the CORBA 2.3 specification.

The DSI interface has changed in CORBA 2.3. omniORB 3 uses the new
mapping, but since the mapping depends on
\type{PortableServer::Current}, which is not yet implemented, not all
facilities are available. This chapter describes an approach to
building DSI servers which works with omniORB 3.

\section{Overview}

When an ORB receives an invocation request, the information includes
the object reference and the name of the operation. Typically this
information is used by the ORB to select a servant object and call
into the implementation of the operation (which knows how to unmarshal
the parameters etc.).  The Dynamic Skeleton Interface however makes
this information directly available to the application---so that it
can implement the operation (or pass it on to another server) without
static knowledge of the interface. In fact it is not even necessary
for the server to always implement the same interface on any
particular object!

To provide an implementation for one or more objects an application
must sub-class \type{PortableServer::DynamicImplementation} and
override the method \op{invoke}.  An instance of this class is
registered with a POA and is assigned an object reference (see below).
When the ORB receives a request for that object the \op{invoke} method
is called and will be passed a \type{CORBA::ServerRequest} object
which provides:

\begin{itemize}
\item the operation name
\item context strings
\item access to the parameters
\item a way to set the returned values
\item a way to throw user-defined exceptions.
\end{itemize}


\section{DSI Types}

\subsection{PortableServer::DynamicImplementation}

This class must be sub-classed by the application to provide an
implementation for DSI objects. The method \op{invoke} will be called
for each operation invocation.

\begin{cxxlisting}
namespace PortableServer {
  ...

  class DynamicImplementation : public virtual ServantBase {
  public:
    virtual ~DynamicImplementation();

    CORBA::Object_ptr _this();
    // Must only be called from within invoke(). Caller must release
    // the reference returned.

    virtual void invoke(CORBA::ServerRequest_ptr request) = 0;
    virtual char* _primary_interface(const ObjectId& oid, POA_ptr poa) = 0;

    virtual CORBA::Boolean _is_a(const char* logical_type_id);
    // The default implementation uses _primary_interface(),
    // but may be overridden by subclasses.
  };
  ...
};
\end{cxxlisting}


\subsection{ServerRequest}

A \type{ServerRequest} object provides the interface between a dynamic
implementation and the ORB.

\begin{cxxlisting}
namespace CORBA {
  ...

  class ServerRequest {
  public:
    virtual const char* operation() = 0;
    virtual void        arguments(NVList_ptr& parameters) = 0;
    virtual Context_ptr ctx() = 0;
    virtual void        set_result(const Any& value) = 0;
    virtual void        set_exception(const Any& value) = 0;

  protected:
    inline ServerRequest() {}
    virtual ~ServerRequest();
  };
  ...
};
\end{cxxlisting}


\section{Creating Dynamic Implementations}

The application must override the \op{invoke} method of
\type{DynamicImplementation} to provide an implementation for DSI
objects.  This method must behave as follows:

\begin{itemize}
\item It may be called concurrently by multiple threads of execution,
and so must be thread-safe.

\item It may not throw any exceptions. Both user-defined and system
exceptions are passed in a value of type Any via a call to
\op{ServerRequest::set\_\dsc{}exception}.

\item The operations on the \type{ServerRequest} object must be
carried out in the correct order, as described below.
\end{itemize}


\subsection{Operations on the ServerRequest}

\op{operation} will return the name of the operation, and may be
called at any time. For attribute access the operation name is the IDL
name of the attribute, prefixed by \texttt{\_get\_} or
\texttt{\_set\_}. If the operation name is not recognised a
\code{CORBA::\dsc{}BAD\_OPERATION} exception should be passed back
through \op{set\_exception}. This will allow the ORB to then see if it
is one of the standard object operations.

Firstly \op{arguments} must be called passing a
\type{CORBA::NVList}\footnote{obtained by calling
\op{CORBA::ORB::create\_list}} which must be initialised to contain
the type and mode of the parameters.  The ORB consumes this value and
will release it when the operation is complete. At this point any
\emph{in}/\emph{inout} arguments will be unmarshalled, and when this
operation returns, their values will be in the \type{NVList}. The
application may set the value of \emph{inout}/\emph{out} arguments by
modifying this parameter list.

If the operation has user-context information, then \op{ctx} must be
called after \op{arguments} to retrieve it.

\op{set\_result} must then be called exactly once if the operation has
a non-void return value (unless an exception is thrown). The value
passed should be an Any allocated with \code{new}, and will be freed
by the ORB.

At any point in the above sequence \op{set\_exception} may be called
to set a user-defined exception or a system exception. If this happens
then no further operations should be invoked on the
\type{ServerRequest} object, and the \op{invoke} method should return.

Within the \op{invoke} method \op{\_this} may be called to obtain the
object reference. This method may not be used at any other time.


\section{Registering Dynamic Objects}

To use a \type{DynamicImplementation} servant, a CORBA object must be
created and associated with it, just as for any other servant. Dynamic
servants can also be created on demand by Servant Managers, just like
static servants.


\section{Example}

This implementation of \op{DynamicImplementation::invoke} is taken
from an example which can be found in the omniORB distribution. The
\op{echoString} operation is declared in IDL as:

\begin{idllisting}
string echoString(in string mesg);
\end{idllisting}



\noindent Here is the Dynamic Implementation Routine:

\begin{cxxlisting}
void
MyDynImpl::invoke(CORBA::ServerRequest_ptr request)
{
  try {
    if( strcmp(request->operation(), "echoString") )
      throw CORBA::BAD_OPERATION(0, CORBA::COMPLETED_NO);

    CORBA::NVList_ptr args;
    orb->create_list(0, args);
    CORBA::Any a;
    a.replace(CORBA::_tc_string, 0);
    args->add_value("", a, CORBA::ARG_IN);

    request->arguments(args);

    const char* mesg;
    *(args->item(0)->value()) >>= mesg;

    CORBA::Any* result = new CORBA::Any();
    *result <<= CORBA::Any::from_string(mesg, 0);
    request->set_result(*result);
  }
  catch(CORBA::SystemException& ex){
    CORBA::Any a;
    a <<= ex;
    request->set_exception(a);
  }
  catch(...){
    cout << "echo_dsiimpl: MyDynImpl::invoke - caught an unknown exception."
	 << endl;
    CORBA::Any a;
    a <<= CORBA::UNKNOWN(0, CORBA::COMPLETED_NO);
    request->set_exception(a);
  }
}
\end{cxxlisting}





\appendix
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{hosts\_access(5)}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{apx:hostsaccess}

\subsection*{DESCRIPTION}

This manual page describes a simple access control language that is
based on client (host name/address, user name), and server (process
name, host name/address) patterns.  Examples are given at the end. The
impatient reader is encouraged to skip to the EXAMPLES section for a
quick introduction.

An extended version of the access control language is described in the
hosts\_\dsc{}options(5) document. The extensions are turned on at
program build time by building with -DPROCESS\_OPTIONS.

In the following text, \term{daemon} is the process name of a network
daemon process, and \term{client} is the name and/or address of a host
requesting service. Network daemon process names are specified in the
inetd configuration file.

\subsection*{ACCESS CONTROL FILES}

The access control software consults two files. The search stops
at the first match:

\begin{itemize}
\item Access will be granted when a (daemon,client) pair matches an
entry in the \file{/etc/hosts.allow} file.

\item Otherwise, access will be denied when a (daemon,client) pair
matches an entry in the \file{/etc/hosts.deny} file.

\item Otherwise, access will be granted.

\end{itemize}

A non-existing access control file is treated as if it were an empty
file. Thus, access control can be turned off by providing no access
control files.

\subsection*{ACCESS CONTROL RULES}

Each access control file consists of zero or more lines of text.
These lines are processed in order of appearance. The search
terminates when a match is found.

\begin{itemize}

\item A newline character is ignored when it is preceded by a
backslash character. This permits you to break up long lines so that
they are easier to edit.

\item Blank lines or lines that begin with a \texttt{\#} character are
ignored.  This permits you to insert comments and whitespace so that
the tables are easier to read.

\item All other lines should satisfy the following format, things
between [] being optional: \texttt{daemon\_list : client\_list [ :
shell\_command ] }

\end{itemize}

\texttt{daemon\_list} is a list of one or more daemon process names
(argv[0] values) or wildcards (see below).  

\texttt{client\_list} is a list of one or more host names, host
addresses, patterns or wildcards (see below) that will be matched
against the client host name or address.

The more complex forms \texttt{daemon@host} and \texttt{user@host} are
explained in the sections on server endpoint patterns and on client
username lookups, respectively.

List elements should be separated by blanks and/or commas.  

With the exception of NIS (YP) netgroup lookups, all access control
checks are case insensitive.

\subsection*{PATTERNS}

The access control language implements the following patterns:

\begin{itemize}

\item A string that begins with a \texttt{.} character. A host name is
matched if the last components of its name match the specified
pattern.  For example, the pattern \texttt{.tue.nl} matches the host
name \texttt{wzv.win.tue.nl}.

\item A string that ends with a \texttt{.} character. A host address
is matched if its first numeric fields match the given string.  For
example, the pattern \texttt{131.155.} matches the address of (almost)
every host on the Eindhoven University network (\texttt{131.155.x.x}).

\item A string that begins with an \texttt{\@} character is treated as
an NIS (formerly YP) netgroup name. A host name is matched if it is a
host member of the specified netgroup. Netgroup matches are not
supported for daemon process names or for client user names.

\item An expression of the form \texttt{n.n.n.n/m.m.m.m} is
interpreted as a `net/mask' pair. A host address is matched if `net'
is equal to the bitwise AND of the address and the `mask'. For
example, the net/mask pattern
\texttt{131.155.72.0/\dsc{}255.255.254.0} matches every address in the
range \texttt{131.155.72.0} to \texttt{131.155.73.255}.

\end{itemize}

\subsection*{WILDCARDS}

The access control language supports explicit wildcards:

\begin{description}
\item[\tt ALL]\mbox{}\\
The universal wildcard, always matches.

\item[\tt LOCAL]\mbox{}\\
Matches any host whose name does not contain a dot
character.

\item[\tt UNKNOWN]\mbox{}\\
Matches any user whose name is unknown, and matches
any host whose name or address are unknown.  This pattern should be
used with care: host names may be unavailable due to temporary name
server problems. A network address will be unavailable when the
software cannot figure out what type of network it is talking to.

\item[\tt KNOWN]\mbox{}\\
Matches any user whose name is known, and matches any
host whose name and address are known. This pattern should be used
with care: host names may be unavailable due to temporary name server
problems.  A network address will be unavailable when the software
cannot figure out what type of network it is talking to.

\item[\tt PARANOID]\mbox{}\\
Matches any host whose name does not match its
address.  When tcpd is built with -DPARANOID (default mode), it drops
requests from such clients even before looking at the access control
tables.  Build without -DPARANOID when you want more control over such
requests.

\end{description}

\subsection*{OPERATORS}

\begin{description}

\item[\tt EXCEPT]\mbox{}\\
Intended use is of the form: \texttt{list\_1} \texttt{EXCEPT}
\texttt{list\_2}; this construct matches anything that matches
\texttt{list\_1} unless it matches \texttt{list\_2}.  The
\texttt{EXCEPT} operator can be used in \texttt{daemon\_lists} and in
\texttt{client\_lists}. The \texttt{EXCEPT} operator can be nested: if
the control language would permit the use of parentheses, \texttt{a
EXCEPT b EXCEPT c} would parse as \texttt{(a EXCEPT (b EXCEPT c))}.

\end{description}

\subsection*{SHELL COMMANDS}

If the first-matched access control rule contains a shell command,
that command is subjected to \texttt{\%<letter>} substitutions (see
next section).  The result is executed by a /bin/sh child process with
standard input, output and error connected to /dev/null.  Specify an
\texttt{\&} at the end of the command if you do not want to wait until
it has completed.

Shell commands should not rely on the PATH setting of the inetd.
Instead, they should use absolute path names, or they should begin
with an explicit \texttt{PATH=\dsc{}whatever} statement.

The hosts\_options(5) document describes an alternative language that
uses the shell command field in a different and incompatible way.

\subsection*{\% EXPANSIONS}

The following expansions are available within shell commands:

\begin{itemize}

\item[\tt \%a (\%A)] The client (server) host address.
\item[\tt \%c] Client information: user@host, user@address, a host
name, or just an address, depending on how much information is
available.
\item[\tt \%d] The daemon process name (argv[0] value).
\item[\tt \%h (\%H)]
The client (server) host name or address, if the host name is
unavailable.
\item[\tt \%n (\%N)] The client (server) host name (or "unknown" or
"paranoid").
\item[\tt \%p] The daemon process id.
\item[\tt \%s] Server information: daemon@host, daemon@address, or
just a daemon name, depending on how much information is available.
\item [\tt \%u] The client user name (or "unknown").
\item [\tt \%\%] Expands to a single \texttt{\%} character.

\end{itemize}

Characters in \% expansions that may confuse the shell are replaced by
underscores.

\subsection*{SERVER ENDPOINT PATTERNS}

In order to distinguish clients by the network address that they
connect to, use patterns of the form:

\texttt{process\_name@host\_pattern : client\_list ... }

Patterns like these can be used when the machine has different
internet addresses with different internet hostnames.  Service
providers can use this facility to offer FTP, GOPHER or WWW archives
with internet names that may even belong to different
organisations. See also the `twist' option in the hosts\_options(5)
document. Some systems (Solaris, FreeBSD) can have more than one
internet address on one physical interface; with other systems you may
have to resort to SLIP or PPP pseudo interfaces that live in a
dedicated network address space. The \texttt{host\_pattern} obeys
the same syntax rules as host names and addresses in
\texttt{client\_list} context. Usually, server endpoint information is
available only with connection-oriented services.


\subsection*{CLIENT USERNAME LOOKUP}

When the client host supports the RFC 931 protocol or one of its
descendants (TAP, IDENT, RFC 1413) the wrapper programs can retrieve
additional information about the owner of a connection. Client
username information, when available, is logged together with the
client host name, and can be used to match patterns like:

\texttt{daemon\_list : ... user\_pattern@host\_pattern ...}

The daemon wrappers can be configured at compile time to perform
rule-driven username lookups (default) or to always interrogate the
client host.  In the case of rule-driven username lookups, the above
rule would cause username lookup only when both the
\texttt{daemon\_list} and the \texttt{host\_pattern} match.

A user pattern has the same syntax as a daemon process pattern, so the
same wildcards apply (netgroup membership is not supported).  One
should not get carried away with username lookups, though.

\begin{itemize}

\item The client username information cannot be trusted when it is
needed most, i.e. when the client system has been compromised.  In
general, ALL and (UN)KNOWN are the only user name patterns that make
sense.

\item Username lookups are possible only with TCP-based services, and
only when the client host runs a suitable daemon; in all other cases
the result is `unknown'.

\item A well-known UNIX kernel bug may cause loss of service when
username lookups are blocked by a firewall. The wrapper README
document describes a procedure to find out if your kernel has this
bug.

\item Username lookups may cause noticeable delays for non-UNIX users.
The default timeout for username lookups is 10 seconds: too short to
cope with slow networks, but long enough to irritate PC users.

\end{itemize}

Selective username lookups can alleviate the last problem. For
example, a rule like:

\texttt{daemon\_list : @pcnetgroup ALL@ALL }

would match members of the pc netgroup without doing username lookups,
but would perform username lookups with all other systems.

\subsection*{DETECTING ADDRESS SPOOFING ATTACKS}

A flaw in the sequence number generator of many TCP/IP implementations
allows intruders to easily impersonate trusted hosts and to break in
via, for example, the remote shell service.  The IDENT (RFC931 etc.)
service can be used to detect such and other host address spoofing
attacks.

Before accepting a client request, the wrappers can use the IDENT
service to find out that the client did not send the request at all.
When the client host provides IDENT service, a negative IDENT lookup
result (the client matches \texttt{UNKNOWN@host}) is strong evidence
of a host spoofing attack.

A positive IDENT lookup result (the client matches
\texttt{KNOWN@host}) is less trustworthy. It is possible for an
intruder to spoof both the client connection and the IDENT lookup,
although doing so is much harder than spoofing just a client
connection. It may also be that the client's IDENT server is lying.

Note: IDENT lookups don't work with UDP services. 

\subsection*{EXAMPLES}

The language is flexible enough that different types of access control
policy can be expressed with a minimum of fuss. Although the language
uses two access control tables, the most common policies can be
implemented with one of the tables being trivial or even empty.

When reading the examples below it is important to realise that the
allow table is scanned before the deny table, that the search
terminates when a match is found, and that access is granted when no
match is found at all.

The examples use host and domain names. They can be improved by
including address and/or network/netmask information, to reduce the
impact of temporary name server lookup failures.

\subsection*{MOSTLY CLOSED}

In this case, access is denied by default. Only explicitly authorised
hosts are permitted access.

The default policy (no access) is implemented with a trivial deny
file:

{\small
\begin{verbatim}
/etc/hosts.deny:
    ALL: ALL
\end{verbatim}
}

This denies all service to all hosts, unless they are permitted access
by entries in the allow file.

The explicitly authorised hosts are listed in the allow file.  For
example:

{\small
\begin{verbatim}
/etc/hosts.allow:
   ALL: LOCAL @some_netgroup
   ALL: .foobar.edu EXCEPT terminalserver.foobar.edu
\end{verbatim}
}

The first rule permits access from hosts in the local domain (no .  in
the host name) and from members of the \texttt{some\_netgroup}
netgroup.  The second rule permits access from all hosts in the
\texttt{foobar.edu} domain (notice the leading dot), with the
exception of \texttt{terminalserver.foobar.edu}.

\subsection*{MOSTLY OPEN}

Here, access is granted by default; only explicitly specified hosts
are refused service.

The default policy (access granted) makes the allow file redundant so
that it can be omitted.  The explicitly non-authorised hosts are
listed in the deny file. For example:

{\small
\begin{verbatim}
/etc/hosts.deny:
   ALL: some.host.name, .some.domain
   ALL EXCEPT in.fingerd: other.host.name, .other.domain
\end{verbatim}
}

The first rule denies some hosts and domains all services; the second
rule still permits finger requests from other hosts and domains.


\subsection*{BOOBY TRAPS}

The next example permits tftp requests from hosts in the local domain
(notice the leading dot).  Requests from any other hosts are denied.
Instead of the requested file, a finger probe is sent to the offending
host. The result is mailed to the superuser.

{\small
\begin{verbatim}
/etc/hosts.allow:
   in.tftpd: LOCAL, .my.domain

/etc/hosts.deny:
   in.tftpd: ALL: (/some/where/safe\_finger -l @%h | \
       /usr/ucb/mail -s %d-%h root) &
\end{verbatim}
}

The \texttt{safe\_finger} command comes with the tcpd wrapper and
should be installed in a suitable place. It limits possible damage
from data sent by the remote finger server.  It gives better
protection than the standard finger command.

The expansion of the \%h (client host) and \%d (service name)
sequences is described in the section on shell commands.

Warning: do not booby-trap your finger daemon, unless you are prepared
for infinite finger loops.

On network firewall systems this trick can be carried even further.
The typical network firewall only provides a limited set of services
to the outer world. All other services can be "bugged" just like the
above tftp example. The result is an excellent early-warning system.

\subsection*{DIAGNOSTICS}

An error is reported when a syntax error is found in a host access
control rule; when the length of an access control rule exceeds the
capacity of an internal buffer; when an access control rule is not
terminated by a newline character; when the result of %<letter>
expansion would overflow an internal buffer; when a system call fails
that shouldn\'t.  All problems are reported via the syslog daemon.


\subsection*{FILES}

\noindent \file{/etc/hosts.allow}, (daemon,client) pairs that are granted access.

\noindent \file{/etc/hosts.deny}, (daemon,client) pairs that are denied access.

\subsection*{SEE ALSO}

\noindent tcpd(8) tcp/ip daemon wrapper program.

\noindent tcpdchk(8), tcpdmatch(8), test programs.

\subsection*{BUGS}

If a name server lookup times out, the host name will not be available
to the access control software, even though the host is registered.

Domain name server lookups are case insensitive; NIS (formerly YP)
netgroup lookups are case sensitive.

\subsection*{AUTHOR}

Wietse Venema (wietse@wzv.win.tue.nl)\\
Department of Mathematics and Computing Science\\
Eindhoven University of Technology\\
Den Dolech 2, P.O. Box 513,\\
5600 MB Eindhoven, The Netherlands\\


\backmatter

\bibliography{omniORB}

\end{document}




\endinput

%
%
% The following is obsolete material from the old omniORB 2 manual.
% It's left here in case it's useful.
%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{The Basic Object Adaptor (BOA)}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This chapter describes the BOA implementation in omniORB. The CORBA
specification defines the Basic Object Adaptor as the entity that
mediates between object implementations and the ORB. Unfortunately,
the BOA specification is incomplete and does not address the
multi-threading issues appropriately. The end result is that different
ORB vendors implement different extensions to their BOAs. Worse, the
implementation of the operations defined in the specification are
different in different ORBs. Recently, a new Object Adaptor
specification (the Portable Object Adaptor- POA) has been adopted and
will replace the BOA as the standard Object Adaptor in CORBA. The new
specification recognises the compatibility problems of BOA and
recommends that all BOAs should be considered propriety extensions.
omniORB will support POA in future releases. Until then, you have to
use the BOA to attach object implementations to the ORB.

The rest of this chapter describes the interface of the BOA in detail. It
is important to recognise that the interface described below is omniORB
specific and hence the code using this interface is unlikely to be portable
to other ORBs.

Unless it is stated otherwise, the term ``object'' will be used below to
refer to object implementations. This should not be confused with ``object
references'' which are handles held by clients.

\section{BOA Initialisation}

It takes two steps to put the BOA into service. The BOA has to be
initialised using {\tt BOA\_init} and activated using {\tt
impl\_is\_ready}.


\noindent {\tt BOA\_init} is a member of the {\tt CORBA::ORB} class. Its signature is:

{\small
\begin{verbatim}
BOA_ptr BOA_init(int & argc,
                 char ** argv,
                 const char * boa_identifier);
\end{verbatim}
}

\noindent Typically, it is used in the startup code as follows:

{\small
\begin{verbatim}
CORBA::ORB_ptr orb = CORBA::ORB_init(argc,argv,"omniORB2");   // line 1
CORBA::BOA_ptr boa = orb->BOA_init(argc,argv,"omniORB2_BOA"); // line 2
\end{verbatim}
}

The {\tt argv} parameters may contain BOA options. These options will be
removed from the {\tt argv} list when {\tt BOA\_init} returns. Other
parameters in {\tt argv} will remain. The supported options are:

\begin{description}

\item[-BOAiiop\_port {\tt <port number (0-65535)>}] Use the port number to receive
IIOP requests. This option can be specified multiple times in the command
line and the BOA would be initialised to listen on all of the ports.

\item[-BOAid {\tt <id (string)>}] If this option is used the id must be
``omniORB2\_BOA''. 

\item[-BOAiiop\_name\_port {\tt <hostname{[:port number]}>}] Similar to {\tt
{-BOAiiop\_port}}, this options tells the BOA the hostname and optionally the port number to use.

\end{description}

If the third argument of {\tt BOA\_init} is non-nil, it must be the string
constant ``omniORB2\_BOA''. If the argument is nil, -BOAid must be present
in {\tt argv}.

If there is any problem in the initialisation process, a {\tt
CORBA::INITIALIZE} exception would be raised.

To register an object with the BOA, the method
{\tt \_obj\_is\_ready} should be called with the return value of {\tt
BOA\_init} as the argument.

{\tt BOA\_init} is thread-safe. It can be called multiple times and the
same {\tt BOA\_ptr} will be returned. However, only the {\tt argv} in the
first call will be scanned, the argument is ignored in subsequent calls.

{\tt BOA\_init} returns a pseudo object of type {\tt
CORBA::BOA\_ptr}. Similar to {\tt CORBA::Object\_ptr}, the pointer can be
managed using {\tt CORBA::BOA\_var}, {\tt BOA::\_duplicate} and {\tt
CORBA::release}. The pointer can be tested using {\tt CORBA::is\_nil} which
returns true if the pointer is equivalent to the return value of {\tt
BOA::\_nil}. 

After {\tt BOA\_init} is called, objects can be registered. However,
incoming IIOP requests would not be despatched until {\tt impl\_is\_ready}
is called.

{\small
\begin{verbatim}
class BOA {
public:
   impl_is_ready(CORBA::ImplementationDef_ptr p = 0,
                 CORBA::Boolean NonBlocking = 0);
};
\end{verbatim}
}

One of the common pitfall in using the BOA is to forget to call
impl\_is\_ready. Until this call returns, there is no thread listening on
the port from which IIOP requests are received. The remote client may hang
because of this.

When {\tt impl\_is\_ready} is called with no argument. The calling thread
would be blocked indefinitely in the function until {\tt impl\_shutdown}
(see below) is called. The thread that is calling {\tt impl\_is\_ready}
is not used by the BOA to perform its internal functions. The BOA has its
own set of threads to process incoming requests and general
housekeeping. Therefore, it is not necessary to have a thread blocked in
the call if it can be put into use elsewhere. For example, the main thread
may call {\tt impl\_is\_ready} once in non-blocking mode (see below) and
then enter the event loop to handle the GUI frontend.

If non-blocking behaviour is needed, the {\tt NonBlocking} argument should be
set to 1. For instance, if you creates a callback object, you might call
impl\_is\_ready in non-blocking mode to tell the BOA to start receiving
IIOP requests before sending the callback object to the remote object. The
first argument {\tt ImplementationDef\_ptr} is ignored by the BOA. Just set
the argument to nil.

{\tt impl\_is\_ready} is thread safe and can be called multiple
times. Multiple threads can be blocked in {\tt impl\_is\_ready}.

\section{Object Registration}

Once the BOA is initialised, objects can be registered. The
purpose of object registration is to let the BOA know of the existence of
the object and to dispatch requests for the object as upcalls into the
object. 

To register an object, the {\tt \_obj\_is\_ready} function should be
called. {\tt \_obj\_is\_ready} is a member function of the implementation
skeleton class. The function should be called only once for each object.
The call should be made only after the object is fully initialised.

The member function {\tt obj\_is\_ready} of the BOA may also be used to
register an object. However, this function has been superseded by {\tt
\_obj\_is\_ready} and should not be used in new application code.

\section{Object Disposal}

Once an object is registered, it is under the
management of the BOA. To remove the object from the BOA and to delete it
(when it is safe to do so), the {\tt \_dispose} function should be called.
{\tt \_dispose} is a member function of the implementation skeleton class.
The function should be called only once for each object.

Notice the asymmetry in object instantiation and destruction. To instantiate
an object, the application code has to call the {\bf new}
operator. To remove the object, the application should never
call the delete operator on the object directly.

At the time the {\tt \_dispose} call is made, there may be other threads
invoking on the object, the BOA ensures that all these calls are completed
before removing the object from its internal tables and calling the
{\bf delete} operator.

Internally, the BOA keeps a reference count on each object. Initially, the
reference count is 0. After a call to {\tt \_obj\_is\_ready}, the reference
count is 1. The BOA increases the reference count by 1 before
an upcall into the object is made. The count is decreased by 1 when the
upcall returns.  {\tt \_dispose} decreases the reference count by 1, if
the reference count is 0, the delete operator is called. If the count is
non-zero, the object is marked as disposed. The object will be deleted when
the reference count eventually goes to zero.

The reference count is also increased by 1 for each object reference held
in the same address space. Hence, the {\bf delete} operator will not be
called when there are outstanding object references in the same address
space. To ensure that an object is deleted, all its object references in
the same address space should be released using {\tt CORBA::release}.

Unlike colocated object references, references held by clients in other
address spaces would not prevent the deletion of objects. If these clients
invoke on the object after it is disposed, the system exception INV\_OBJREF
would be raised. The difference in semantics is an undesirable side-effect
of the current BOA implementation. In future, colocated references will
have the same semantics as remote references, i.e. their presence will not
delay the deletion of the objects.

Instead of {\tt \_dispose}, it may be useful to have a method to deactivate
the object but not deleting it. This feature is not supported in the
current BOA implementation.

\section{BOA Shutdown}

The BOA can be withdrawn from service using member functions {\tt
impl\_shutdown} and {\tt destroy}.

{\small
\begin{verbatim}
class BOA {
public:
   void impl_shutdown();
   void destroy();
};
\end{verbatim}
}

{\tt impl\_shutdown} and {\tt destroy} are the inverse of {\tt
impl\_is\_ready} and {\tt BOA\_init} respectively.

{\tt impl\_shutdown} deactivates the BOA. When the call returns, all the
internal threads and network connections will be shutdown. Any thread
blocking in {\tt impl\_is\_ready} would be unblocked. After the call, no
request from other address spaces will be processed. In other words, the
BOA will be in the same state as it was in before {\tt impl\_is\_ready} was
called. For example, a remote client may hang if it tries to connect to the
server after {\tt impl\_shutdown} was called because no thread is listening
on the IIOP port. 

{\tt impl\_shutdown} does not wait for incoming requests to complete before
it closes the network connections. The remote clients will see the network
connections shutdown and the replies may not  reach them even if the
upcalls have been completed. Therefore, if the application is to define an
operation in an IDL interface to shutdown the BOA,  the operation should be
defined as an oneway operation.

{\tt impl\_shutdown} is thread-safe and can be called multiple times. The
call is silently ignored if the BOA has already been shutdown. After {\tt
impl\_shutdown} is called, the BOA can be reactivated by another call to
{\tt impl\_is\_ready}.

It should be noted that {\tt impl\_shutdown} does not affect outgoing
network connections. That is, clients in the same address space will
still be able to make calls to objects in other address spaces.

While remote requests are not delivered after {\tt impl\_shutdown} is
called, the current implementation does not stop colocated clients from
calling the objects. In future, colocated clients will exhibit the same
behaviour as remote clients.

{\tt destroy} permanently removed the BOA. This function will call {\tt
impl\_shutdown} implicitly if it has not been called. When this call
returns, the IIOP port(s) held by the BOA will be freed. Remote clients
will see their requests refused by the operating system when they try to
open a connection to the IIOP port(s). 

After {\tt destroy} is called, the BOA should not be used. If there is any
objects still registered with the BOA, the objects should not be invoked
afterwards. The objects are not disposed. Invoking on the objects after
{\tt destroy} would result in undefined behaviour. Initialisation of
another BOA using {\tt BOA\_init} is not supported. The behaviour of {\tt
BOA\_init} after this call is undefined.

\section{Unsupported functions}

The following member functions are not implemented. Calling these functions
do not have any effect.

\begin{itemize}
\item {\tt Object\_ptr create(...)}
\item {\tt ReferenceData* get\_id(Object\_ptr)}
\item {\tt Principal\_ptr get\_principal(Object\_ptr,Environment\_ptr)}
\item {\tt void change\_implementation(Object\_ptr, ImplementationDef\_ptr)}
\item {\tt void deactivate\_impl(ImplementationDef\_ptr)}
\item {\tt void deactivate\_obj(Object\_ptr)}
\end{itemize}


\section{Loading Objects On Demand}
\label{load_on_demand}

Since 2.5.0, there is limited support for loading objects on demand. 
An application can register a handler for loading objects dynamically. The
handler should have the signature {\tt omniORB::loader::mapKeyToObject\_t}:

{\small
\begin{verbatim}
  namespace omniORB {
    ...
    class loader {
    public:
      typedef CORBA::Object_ptr (*mapKeyToObject_t) (const objectKey& key);
      static void set(mapKeyToObject_t NewKeyToObject);
    };
  };
\end{verbatim}
}


When the ORB cannot locate the target object in this address space, it
calls the handler with the object key of the target. The handler is expected
to instantiate the object, either in this address space or in another
address space, and returns the object reference to the newly instantiated
object. The ORB will then reply with a LOCATION\_FORWARD message to instruct
the client to retry using the object reference returned by the handler.
When the handler returns, the ORB assumes ownership of the returned
value. It will call CORBA::release() on the returned value when it has
finished with it.
                                                                      
The handler may be called concurrently by multi-threads. Hence it  
must be thread-safe.                                               
                                                                      
If the handler cannot load the target object, it should return     
CORBA::Object::\_nil(). The object will be treated as non-existing. 
                                                                      
The application registers the handler with the ORB at runtime      
using omniORB::loader::set(). This function is not thread-safe.    
Calling this function again will replace the old handler with      
the new one.                                                       




\section{Object Keys}

omniORB uses a data type {\tt omniORB::objectKey} to uniquely
identify each object implementation. This is an opaque data type and 
can only be manipulated by the following functions:

{\small
\begin{verbatim}
void omniORB::generateNewKey(omniORB::objectKey &k);
\end{verbatim}
}

{\tt omniORB::generateNewKey} returns a new {\tt objectKey}. The return
value is guaranteed to be unique among the keys generated during this program
run. On the platforms that have a realtime clock and unique process
identifiers, a stronger assertion can be made, i.e. the keys are guaranteed
to be unique among all keys ever generated on the same machine.

{\small
\begin{verbatim}
const unsigned int omniORB::hash_table_size;
int omniORB::hash(omniORB::objectKey& k);
\end{verbatim}
}

{\tt omniORB::hash} returns the hash value of an {\tt objectKey}. The value
returned by this function is always between 0 and {\tt
omniORB:hash\_table\_size - 1} inclusively.

{\small
\begin{verbatim}
omniORB::objectKey omniORB::nullkey();
\end{verbatim}
}

{\tt omniORB::nullkey} always returns the same {\tt objectKey} value. This
key is guaranteed to hash to 0.

{\small
\begin{verbatim}
int operator==(const omniORB::objectKey &k1,const omniORB::objectKey &k2);
int operator!=(const omniORB::objectKey &k1,const omniORB::objectKey &k2);
\end{verbatim}
}

{\tt ObjectKeys} can be tested for equality using the overloaded {\tt
operator==} and {\tt operator!=}.

{\small
\begin{verbatim}
omniORB::seqOctets*
omniORB::keyToOctetSequence(const omniORB::objectKey &k1);

omniORB::objectKey
omniORB::octetSequenceToKey(const omniORB::seqOctets& seq);
\end{verbatim}
}

{\tt omniORB::keyToOctetSequence} takes an {\tt objectKey} and returns its
externalised representation in the form of a sequence of octets. The same
sequence can be converted back to an {\tt objectKey} using {\tt
omniORB::octetSequenceToKey}. If the supplied sequence is not an {\tt
objectKey}, {\tt omniORB::octetSequenceToKey} raises a {\tt CORBA::MARSHAL}
exception.





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Proxy Objects}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

When a client acquires a reference to an object in another address
space, omniORB creates a local representation of the object and
returns a pointer to this object as its object reference. The local
representation is known as the proxy object.

The proxy object maps each IDL operation into a method to deliver
invocations to the remote object. The method implements argument
marshalling using the ORB runtime. When the ORB runtime detects an
error condition, it may raise a system exception. These exceptions
will normally be propagated by the proxy object to the application
code. However, there may be applications that prefer to have the
system exceptions trapped in the proxy object. For these applications,
it is possible to install exception handlers for individual proxy
objects or all proxy objects. The API to do this is explained in this
chapter.

As described in section~\ref{sec_intf}, proxy objects are created by
instances of the \type{proxyObjectFactory} class. For each IDL
interface A, the stubs of A contains a derived class of
\type{proxyObjectFactory} (\type{\_pof\_A}). This derived class is
responsible for creating proxy objects for A. This process is
completely transparent to the application. However, there may be
applications that require greater control on the creation of proxy
objects or even want to change the behavior of the proxy objects. To
cater for this requirement, applications can override the default
proxyObjectFactories and install their own versions of
proxyObjectFactories. The way to do this is explained in this chapter.




\section{Proxy Object Factories}

This section describes how an application can control the creation or
change the behaviour of proxy objects.


\subsection{Background}

For each interface A, its stub contains a proxy factory class
\type{\_pof\_A}. This class is derived from \type{proxyObjectFactory}
and implements three virtual functions:

\begin{cxxlisting}
class proxyObjectFactory {
public:

  const char *irRepoId() const;

  virtual CORBA::Boolean is_a(const char *base_repoId) const = 0;
       
  virtual CORBA::Object_ptr newObjRef(const char* mostDerivedTypeId,
                                      IOP::TaggedProfileList* profiles,
                                      omniIdentity* id,
                                      omniLocalIdentity* lid) = 0;Rope *r,
};
\end{cxxlisting}

As described in chapter~\ref{ch_intf}, the functions allow the ORB
runtime to perform type checking. The function \op{newObjRef} creates
a proxy object for A based on its input arguments. The return value is
a pointer to the class {\tt \_proxy\_A} which is automatically
re-casted into a {\tt CORBA::Object\_ptr}.  {\tt \_proxy\_A}
implements the proxy object for A:

{\small
\begin{verbatim}
class _proxy_A :  public virtual A {
public:

  _proxy_A (Rope *r,
            CORBA::Octet *key,
            size_t keysize,IOP::TaggedProfileList *profiles,
            CORBA::Boolean release);
  virtual ~_proxy_A();

  // plus other internal functions.

};
\end{verbatim}
}

The stub of A guarantees that exactly {\bf one} instance of
{\tt A\_proxyObjectFactory} is instantiated when an application is
executed. The constructor of {\tt A\_proxyObjectFactory}, via its
base class {\tt proxyObjectFactory} links the instance into the ORB's
proxy factory list. 

Newly instantiated proxy object factories are always entered at the front
of the ORB's proxy factory list. Moreover, when the ORB searches for a
match on the type, it always stops at the first match. In other words, when
additional instances of {\tt A\_proxyObjectFactory} or derived classes of
it are created, the last instantiation will override earlier instantiations
to be the proxy factory selected to create proxy objects of A. This
property can be used by an application to install its
own proxy object factories.

\subsection{An Example}

Using the {\tt Echo} example in chapter~\ref{ch_basic} as the basis, one
can tell the ORB to use a modified proxy object class to create proxy
objects. The steps involved are as follows:

\subsubsection{Define a new proxy class}

We define a new proxy class to cache the result of the last
invocation of {\tt echoString}.

{\small
\begin{verbatim}
class _new_proxy_Echo : public virtual _proxy_Echo {
public:
  _new_proxy_Echo (Rope *r,
                  CORBA::Octet *key,
                  size_t keysize,IOP::TaggedProfileList *profiles,
                  CORBA::Boolean release) 
         : _proxy_Echo(r,key,keysize,profiles,release),
           omniObject(Echo_IntfRepoID,r,key,keysize,profiles,release) 
   {
     // You have to look at the _proxy_Echo class and copy from its
     // ctor all the explicit ctor calls to its base member.
   }
   virtual ~_new_proxy_Echo() {}


   virtual char* echoString(const char* mesg) {
     //
     // Only calls the remote object if the argument is different from the
     // last invocation.

     omni_mutex_lock sync(lock);
     if ((char*)last_arg) {
       if (strcmp(mesg,(char*)last_arg) == 0) {
          return CORBA::string_dup(last_result);
       }
     }
     char* res = _proxy_Echo::echoString(mesg);
     last_arg = mesg;
     last_result = (const char*) res;
     return res;
   }

private:
  omni_mutex        lock;
  CORBA::String_var last_arg;
  CORBA::String_var last_result;
};
\end{verbatim}
}

\subsubsection{Define a new proxy factory class}

Next, we define a new proxy factory class to instantiate {\tt
\_new\_proxy\_Echo} as proxy objects for {\tt Echo}.

{\small
\begin{verbatim}
class _new_Echo_proxyObjectFactory : public virtual Echo_proxyObjectFactory
{
public:
   _new_Echo_proxyObjectFactory () {}
   virtual ~_new_Echo_proxyObjectFactory() {}

   // Only have to override newProxyObject
   virtual CORBA::Object_ptr newProxyObject(Rope *r,
                                            CORBA::Octet *key,
                                            size_t keysize,
                                            IOP::TaggedProfileList *profiles,
                                            CORBA::Boolean release) {
      _new_proxy_Echo *p = new _new_proxy_Echo(r,key,keysize,profiles,release);
      return p;
   }
};
\end{verbatim}
}

Finally, we have to instantiate a single instance of the new proxy factory
in the application code.

{\small
\begin{verbatim}
int main(int argc, char** argv)
{
   // Other initialisation steps

   _new_Echo_proxyObjectFactory* f =  new _new_Echo_proxyObjectFactory;

   // Use the new operator to instantiate the proxy factory and never
   // call the delete operator on this instance.

   // From this point onwards, _new_proxy_Echo will be used to create
   // proxy objects for Echo.

}
\end{verbatim}
}

\subsection{Further Considerations}

Notice that the ORB may call {\tt newProxyObject} multiple times to create
proxy objects for the same remote object. In other words, the ORB does not
guarantee that only one proxy object is created for each remote
object. For applications that require this guarantee, it is necessary to
check within {\tt newProxyObject} whether a proxy object has already been
created for the current request. If the argument {\tt Rope* r} points to
the same structure and the content of the sequence {\tt CORBA::Octet* key} is
the same, then an existing proxy object can be returned to satisfy the
current request. Do not forget to call {\tt CORBA::duplicate()} before
returning the object reference.

{\tt newProxyObject} may be called concurrently by different threads within
the ORB. Needless to say, the function must be thread-safe.
