%
% MIWCO documentation
%
% Copyright 2001,2003 Jaakko Kangasharju
%

\documentclass[12pt,a4paper,draft]{article}

\usepackage{a4}
\usepackage{vmargin}
\usepackage[all]{xy}
\usepackage[dvips]{graphics}

\setpapersize{A4}
\setmargrb{2.5cm}{2cm}{2.5cm}{2cm}

\newcommand{\MICO}{\textsc{Mico}}
\newcommand{\MIWCO}{\textsc{Miwco}}
\newcommand{\intro}[1]{\textit{#1}}

\title{\MIWCO\ --- Wireless CORBA extensions for \MICO}
\author{Jaakko Kangasharju \\ University of Helsinki}
\begin{document}

\maketitle

\section{What Is MIWCO?}

\MIWCO{} is a collection of extensions for \MICO{} to add support for
Wireless Access and Terminal Mobility as specified by OMG's Telecom
Domain Task Force (current document number formal/2004-04-02).  It
includes enhancements to the \MICO{} core library to support CORBA
clients and servers on mobile terminals, and separate programs to
handle call forwarding and location services.  All additions to the
\MICO{} core are activated only for programs requesting them.

\subsection{Wireless Access and Terminal Mobility}

The recommended source for information on the wireless architecture is
the aforementioned OMG specification.  But here is a short overview
for those who do not want to wade through it.

The mobile terminal connects through a GIOP tunnel to the fixed
network.  The endpoints of this tunnel are called Terminal Bridge (on
the terminal side) and Access Bridge (on the network side).  All GIOP
communication between objects on the terminal and the network goes
through this tunnel.  The bridges communicate using the GIOP Tunneling
Protocol, which has messages for establishing and releasing the
tunnel, opening and closing GIOP connections through the tunnel and
forwarding in case the terminal moves while invocations are in
progress.

Each terminal has a Home Location Agent in their home network.  The
Home Location Agent is responsible for tracking its terminals as they
move from Access Bridge to another.  In addition, the Home Location
Agent uses location forwarding to redirect invocations intended for
objects on terminals to their proper addresses.

On the terminal, all clients' invocations are rerouted to the Terminal
Bridge, which uses the GIOP Tunneling Protocol for opening a GIOP
connection and then sending the invocation through this connection.
The servers on the terminal need to create Mobile IORs for their
objects.  This IOR is special in that the addresses in various
profiles are not the addresses of the terminal but rather those of the
Home Location Agent or of the terminal's current Access Bridge.  The
Access Bridge acts as a proxy object, using the GIOP Tunneling
Protocol to handle the invocation.

There are also provisions for tracking the terminal's movements.  Each
time the terminal moves, a Mobility Event is generated by all bridges
participating in the move.  Interested parties may attach themselves
to the Notification Channel which receives these events.

\section{Using MIWCO}

\MIWCO{} contains several programs and adds some command line options
to both compilation and running of \MICO{}.

\subsection{New Configuration Options}

The modifications made to the \MICO{} core will always be compiled in,
but they are not used unless proper command line options are given to
the running program.  However, the \texttt{configure} script has
additional options to enable the various applications.  The code for
these applications is located in the \texttt{coss/wireless}
subdirectory.  The new options are:

\begin{description}
\item[\texttt{--enable-wireless-home}] 
  ~\newline
  This enables building the Home Location Agent.
\item[\texttt{--enable-wireless-terminal}] 
  ~\newline
  This enables building the Terminal Bridge.
\item[\texttt{--enable-wireless-access}] 
  ~\newline
  This enables building the Access Bridge.
\item[\texttt{--enable-wireless}] 
  ~\newline
  This turns on all the above options.  The programs may be enabled
  separately since, apart from testing purposes, there really is no
  reason for running them all on the same machine.
\end{description}

Since \MIWCO{} applications use both the Naming Service and the Event
Service, these are also built if any of the above options is given to
\texttt{configure}.  Theoretically, when building only the Home
Location Agent, the Event Service is not necessary but this is
currently not taken into account.

\subsection{Starting the Home Location Agent}

Running the Home Location Agent is not necessary since \MIWCO{}
supports ``homeless terminals'' mentioned in the specification.  But
the references of objects on a homeless terminal are valid only while
the identified Access Bridge has an association with the terminal so
running the Home Location Agent is recommended if possible.

The Home Location Agent is implemented by the program \texttt{hla}.
It takes a special command line option \texttt{-WATMTerminalPrefix},
whose argument will be used as a prefix for all terminals managed by
that HLA.  The specification recommends that the HLA's IP address is
used (in URL-encoded form, so 127.0.0.1 is given as
\texttt{\%7f\%00\%00\%01}; notice that any hex digits in the range
a--f need to be given in lowercase).  The names of the managed
terminals are given, one on each line, in the file given with the
\texttt{-WATMTerminalFile} command line option, \texttt{\$HOME/.hlarc}
by default.

The program will try to add its object reference to the local Naming
Service under the name \texttt{MobilitySupport/HomeLocationAgent}.  If
the HLA is given \texttt{MobilitySupport} as its \texttt{-POAImplName}
option, this will also be its object key.

\subsection{Starting and using the Access Bridge}

The program name for the Access Bridge is \texttt{ab}.  It accepts
the following command line options:

\begin{description}
\item[\texttt{-WATMGIOPAddr}] 
  ~\newline
  This is the Access Bridge's GIOP address visible on the network
  side.  It replaces the \texttt{-ORBIIOPAddr} option as a method for
  setting this address, so \texttt{-ORBIIOPAddr} must not be specified
  for the Access Bridge.  Multiple GIOP addresses may be given but at
  least one is mandatory.
\item[\texttt{-WATMGTPAddr}] 
  ~\newline
  This is the address where the Access Bridge waits for GTP
  connections from Terminal Bridges.  Multiple GTP addresses may be
  specified but at least one is mandatory.
\item[\texttt{-WATMBridgeName}]
  ~\newline
  This is the name for the Access Bridge, which it uses for its Object
  Id.  If the Naming Service is available, the Access Bridge will also
  add its reference with this name under the context
  \texttt{MobilitySupport}.  This option is not mandatory; if omitted,
  the default \texttt{AccessBridge} is used as the Access Bridge's
  name.
\end{description}

The addresses given for the \texttt{-WATMGTPAddr} and
\texttt{-WATMGIOPAddr} options are in the standard MICO format.  For
example, when using TCP over the wireless link, the GTP address
will be of the form `inet:\textit{host}:\textit{port}' where
\textit{host} is the computer's DNS name or IP address and
\textit{port} is the port that the Access Bridge listens on.  For the
GIOP address any protocol supported by \MICO{} can be used.

In addition, the program \texttt{nadmin} can be used for having the
Access Bridge perform certain tasks.  It requires that the Access
Bridge's object reference is found at the Naming Service.  The only
command line argument it takes is the Access Bridge's name under the
naming context \texttt{MobilitySupport}; if no command line argument
is given, it uses the default \texttt{AccessBridge}.

The \texttt{nadmin} program has a simple menu interface.  Some
operations require input from the user.  In these cases, terminal
identifiers are always given in URL-encoded forms, where certain
characters are replaced by \% followed by the character's ASCII code.
Access Bridge means an object reference suitable for the
\texttt{object\_to\_string} operation; a \texttt{file} or
\texttt{corbaname} URL is probably the easiest.

\subsection{Starting and using the Terminal Bridge}

The Terminal Bridge program is named \texttt{tb}.  As an extension to
the specification, \MIWCO{} implements an interface called
\texttt{TerminalBridge} in the module \texttt{MobileTerminal}.  This
interface is used for controlling the GTP connection and for
registering objects on the terminal.  The program \texttt{tb} accepts
the following command line options:

\begin{description}
\item[\texttt{-ORBTerminalId}] 
  ~\newline
  This is the terminal identifier of the Terminal Bridge's terminal.
  This option is mandatory.
\item[\texttt{-WATMGIOPAddr}] 
  ~\newline
  This is the Terminal Bridge's GIOP address visible to other CORBA
  applications on the terminal.  Like the Access Bridge, the Terminal
  Bridge is also a CORBA object so do not use \texttt{-ORBIIOPAddr} to
  set the network address.  Multiple GIOP addresses may be specified
  but at least one is mandatory.
\item[\texttt{-WATMGTPAddr}] 
  ~\newline
  This is the GTP address of the initial Access Bridge.  This option
  is not mandatory but if it is omitted, the Terminal Bridge's
  \texttt{connect()} operation must be used to connect the terminal to
  an Access Bridge.
\item[\texttt{-WATMBridgeName}] 
  ~\newline
  This is the name for the Terminal Bridge, which it uses for its
  Object Id.  If the Naming Service is available, the Terminal Bridge
  will also add its reference with this name under the context
  \texttt{Mobi\-lity\-Sup\-port}.  This option is not mandatory; if
  omitted, the default \texttt{TerminalBridge} is used as the Terminal
  Bridge's name.
\end{description}

The arguments for the two address options are given in the same format
as for the Access Bridge (see above).

If the terminal is not homeless, the Terminal Bridge also requires the
object reference of its Home Location Agent.  This is handled with
\texttt{resolve\_initial\_references}, for which the reference can be
set with \texttt{-ORBInitRef HomeLocationAgent=<IOR-string>}.

The GTP connection can be somewhat controlled with the \texttt{tadmin}
program.  This program has a menu of available actions and it uses the
\texttt{TerminalBridge} interface to control the Terminal Bridge.  The
addresses this program requests are given in normal \MICO{} format.
The program tries to get the Terminal Bridge's object reference first
with \texttt{resolve\_initial\_references} using the object identifier
\texttt{MobileTerminalBridge}.  If this fails, it looks for the name
given on the command line (\texttt{TerminalBridge} by default) in the
Naming Service under the context \texttt{MobilitySupport}.

\subsection{Running CORBA applications on a mobile terminal}

First of all, the Terminal Bridge on the mobile terminal must be
running.  The applications require the following additional command
line options.  These options are the same for all applications running
on the mobile terminal so they should preferably be set in a
system-wide configuration file (but not before starting the Terminal
Bridge since giving it the latter option may mess up something).

\begin{description}
\item[\texttt{-ORBTerminalId}] 
  ~\newline
  This is the terminal identifier of the mobile terminal.
\item[\texttt{-ORBMTBAddr}] 
  ~\newline
  This is the GIOP address of the Terminal Bridge, which is specified
  for the \texttt{tb} program with the \texttt{-WATMGIOPAddr} option.
  All GIOP messages are redirected to this address.
\end{description}

In addition, all servers need to know the object reference of the
Terminal Bridge.  Like with the \texttt{tadmin} program, this is
fetched as an initial reference with identifier
\texttt{MobileTerminalBridge}.  If the terminal is homeless, the GTP
connection must be established before starting any servers.

The servers on the terminal need to be known to the Terminal Bridge so
that it can open connections to them.  Because of this, servers on the
terminal register themselves at the Terminal Bridge when starting up.
This registration is done by object key since it is possible that
there is no more information available to the Terminal Bridge.  This
means that any two servers on the terminal need to have different
object keys.  The best way to ensure this might be to give different
\texttt{-POAImplName} options on startup to persistent servers, as
this allows using the same server executable multiple times.

\subsection{Optional Features}
\label{sec:opt}

\MIWCO{} applications are built to use certain features if they are
available, but they are not essential.

The Home Location Agent and both Bridges attempt to add their object
references to the Naming Service.  If the Naming Service is running,
they create a naming context \texttt{MobilitySupport} under the root
context, and add their references under this context.  The Home
Location Agent uses the name \texttt{HomeLocationAgent} and the
Bridges uses whatever name they were given on the command line (these
default to \texttt{AccessBridge} and \texttt{TerminalBridge}).  Using
the Naming Service for the Access Bridge is required if using the
\texttt{nadmin} program.

Both Bridges use an Event Channel for supplying Mobility Events.  They
look for the Event Channel in the Naming Service under a name
appropriate to the Bridge (either \texttt{TerminalChannel} or
\texttt{NetworkChannel} in the \texttt{MobilitySupport} context).  If
this channel is not found, they attempt to create it with the Event
Channel Factory, which they look for in the Naming Service under the
name \texttt{EventChannelFactory} (this is the \MICO{} default).  This
is not compliant behaviour, since the specification requires
Notification Channels, but Notification Service can later be plugged
in without any modifications to \MIWCO{} programs.

Finally, when using the \texttt{nadmin} program for forcing handoff,
there is a possibility of recording this handoff with a
\texttt{HandoffCallback} object.  The program \texttt{callback} is the
server for this object and it prints its object reference into a file
called \texttt{hoff.ref} in its working directory.  The
\texttt{nadmin} program looks for this file in its own working
directory and, if it finds the file, reports this object reference as
a handoff callback target.  The \texttt{callback} program only logs
the time and status of the handoff into its log file.


\section{An Example of Using MIWCO}
\label{sec:example}

Since the full infrastructure for a Wireless CORBA system is somewhat
large, it might be useful to run through an example of setting up a
\MIWCO{} application.  This example will cover all the central
programs in the \MIWCO{} distribution, so in a realistic setting some
parts may be left out (e.g. users running CORBA applications on a
mobile terminal are typically not the ones setting up a Home Location
Agent).

The examples use private IP addresses and arbitrary port numbers.  The
addresses should naturally be replaced (it is not necessary to replace
127.0.0.1) and port numbers may be changed to anything, since there
are no standardized ports for any of these applications.

\subsection{Configuration File}

The first thing to do is to set up some common command line options.
These are placed in a file, preferably one option per line.  The file
name by default is \texttt{.micorc} in the user's home directory, but
this is configurable with the \texttt{-ORBConfFile} command line
option.  If you intend to run other \MICO{} applications on the same
machines, you might want to give these options directly on the command
line for all applications instead of making them site-wide.

Since Wireless CORBA is designed for GIOP version 1.2 in mind, the
applications need to be told to use that instead of \MICO{}'s default
1.0.  This is not strictly necessary since \MIWCO{} does support
legacy applications that only use lower versions, but using 1.2
throughout is much cleaner.  This is achieved with the options

\small
\begin{verbatim}
  -ORBGIOPVersion 1.2
  -ORBIIOPVersion 1.2
\end{verbatim}
\normalsize

\MIWCO{} applications will also use the Naming Service if that is
available.  In this example, the Naming Service will serve only the
localhost interface, so that the same IOR for it can be used
everywhere.  The option used is

\small
\begin{verbatim}
  -ORBInitRef NameService=corbaloc::1.2@127.0.0.1:12001/NameService
\end{verbatim}
\normalsize

Also, if you wish to debug, or assist in debugging, \MIWCO{}, you
should configure \MIWCO{} with \texttt{--enable-debug
  --disable-optimize} and add the option

\small
\begin{verbatim}
  -ORBDebug All
\end{verbatim}
\normalsize

This will cause lots of output to be printed by every application.  Of
interest are mostly the message dumps.

\subsection{Auxiliary Services}

The \MIWCO{} applications will use other CORBA services if they are
available.  All of them will insert their object reference into the
Naming Service, and the Bridges will create an Event Channel from the
Event Service.  These services will therefore be started to be
complete.

The Naming Service needs to be started so that the previously-given
object reference is valid.  The command line to achieve this is

\small
\begin{verbatim}
  nsd -ORBIIOPAddr inet:localhost:12001
\end{verbatim}
\normalsize

This command is executed on the machines that run the Home Location
Agent, the Access Bridge, or the Terminal Bridge.

Since the Event Service adds its reference to the Naming Service and
the Bridges get its reference from there, the port number here is
completely arbitrary.  The command to start the Event Service is

\small
\begin{verbatim}
  eventd -ORBIIOPAddr inet:127.0.0.1:27565
\end{verbatim}
\normalsize

This command is run on the machines running either Bridge.  In a
real-world scenario both services would actually listen to an address
visible to the outside, since the benefits of using the Event Service
are practically nullified by running it on localhost.

\subsection{The Home Location Agent}

The Home Location Agent in the example will be set to run on a machine
with IP address 172.16.240.74 (remember, this is not a real address
and would not be routed to in reality).  The command to run the Home
Location Agent is (this is broken on two lines for typographical
reasons; it should be on a single line)

\small
\begin{verbatim}
  hla -ORBIIOPAddr inet:172.16.240.74:27360 -POAImplName
    MobilitySupport -WATMTerminalPrefix %ac%10%e0%4a
\end{verbatim}
\normalsize

Here the \texttt{-POAImplName} option is used because it is (or was;
this may have been relaxed) required for persistent object by \MICO{}.
The \texttt{-WATMTerminalPrefix} is not strictly mandatory but should
be used.  It is intended to be an IP address encoded as four
hexadecimal characters and will be used to get unique terminal
identifiers (see the Wireless CORBA specification, section 4.4).

In addition, the user's home directory needs to contain a file
\texttt{.hlarc} with contents being a single line saying
\texttt{terminal}.  If debug output is turned on, the Home Location
Agent should print a line \texttt{Adding terminal
  \%04\%ac\%10\%e0\%4a\%08terminal} (some of the \%-escaped characters
may be printed as the actual unescaped characters).

On startup the Home Location Agent will write its object reference to
a file called \texttt{home.ref} in its working directory.  This file
needs to be copied to the machine running the corresponding Terminal
Bridge.

\subsection{The Access Bridge}

This example has only one Access Bridge, since there is nothing new in
starting multiple Access Bridges.  This Access Bridge will run on the
machine 192.168.18.232.  The command line for the Access Bridge is

\small
\begin{verbatim}
  ab -WATMGIOPAddr inet:192.168.18.232:41513 -WATMGTPAddr
    inet:192.168.18.232:21100 -WATMBridgeName KwaiBridge -POAImplName
    MobilitySupport -ORBNoIIOPServer >ab.ref
\end{verbatim}
\normalsize

The Access Bridge will output its object reference to standard
output.  Here it is redirected to the file \texttt{ab.ref}.

Here the \texttt{-POAImplName} option is for convenience as with the
Home Location Agent.  The \texttt{-ORBNoIIOPServer} option ensures
that \MICO{} does not start an IIOP server accidentally, since the
Access Bridge uses a custom server for IIOP.

The important options are of course the two address options.  There
really isn't much to say about them, though, except to make a note of
the \texttt{-WATMGTPAddr}, since that needs to be given to the
Terminal Bridge.

The \texttt{-WATMBridgeName} option is used to construct the Access
Bridge's object key and its name in the Naming Service.  An Access
Bridge will overwrite the reference its name has in the Naming
Service, so these names need to be unique among the Access Bridges
using the same Naming Service.

\subsection{The Terminal Bridge}

First of all, the machine running the Terminal Bridge (i.e. terminal)
needs the Home Location Agent's object reference.  So the line

\small
\begin{verbatim}
  -ORBInitRef HomeLocationAgent=<IOR>
\end{verbatim}
\normalsize

is entered into the configuration file, where \texttt{<IOR>} is
replaced with the contents of the \texttt{home.ref} file copied from
the Home Location Agent.

The terminal's IP address in the example will be 172.17.73.35.  This
is meaningless, though, since no one will be contacting the terminal
from the outside.  The command line for the Terminal Bridge is

\small
\begin{verbatim}
  tb -WATMGIOPAddr inet:172.17.73.35:12003 -WATMGTPAddr
    inet:192.168.18.232:21100 -POAImplName MobilitySupport
    -ORBTerminalId %04%ac%10%e0%4a%08terminal -ORBNoIIOPServer >tb.ref
\end{verbatim}

Here the \texttt{-POAImplName} and \texttt{-ORBNoIIOPServer} options
are in similar roles as for the Access Bridge.  The
\texttt{-WATMBridgeName} option may also be used, but its utility in
this case is questionable.  Similarly, the object reference is saved
in a file (this file will be used later).

The \texttt{-ORBTerminalId} argument is formed by taking the IP
address version number \texttt{\%04}, the Home Location Agent's
\texttt{-WATMTerminalPrefix} argument, the terminal's name's length
\texttt{\%08}, and the terminal's name \texttt{terminal} from the
\texttt{.hlarc} file on the Home Location Agent.

The \texttt{-WATMGIOPAddr} option of the Terminal Bridge specifies the
IIOP address used by client applications on the terminal for
redirection; there is no reason why it could not be on the localhost
interface.  The \texttt{-WATMGTPAddr} option specifies the Access
Bridge to contact on startup, and is the address of the Access Bridge
started on the previous step.  If no \texttt{-WATMGTPAddr} option is
given, the Terminal Bridge will not connect to a fixed network; this
connection must be established later with the \texttt{tadmin} tool.

To prepare the terminal for CORBA applications, the configuration file
needs to be modified slightly.  This is best done by copying it under
a new name (below referred to as \texttt{.miwcoapprc} in the user's
home directory) and
adding the lines

\small
\begin{verbatim}
  -ORBTerminalId %04%ac%10%e0%4a%08terminal
  -ORBMTBAddr inet:172.17.73.35:12003
  -ORBInitRef MobileTerminalBridge=<IOR>
\end{verbatim}
\normalsize

These options are not placed in the global configuration file, since
their presence might cause problems when starting the Terminal Bridge.
The terminal identifier is given here to be available to all
applications.  The \texttt{-ORBMTBAddr} uses the same address that was
given as the Terminal Bridge's \texttt{-WATMGIOPAddr} option.
Finally, the \texttt{<IOR>} is replaced with the contents of the file
\texttt{tb.ref} output by the Terminal Bridge.

\subsection{Applications}

The applications used in this example are from the
\texttt{demo/services/wireless/dublin} directory of the \MIWCO{}
distribution.
The server has a single operation, \texttt{date}, that will wait for
the number of seconds indicated by its argument and then return the
current time in ISO 8601 format.  The client invokes this operation
once with the time given as the first command line argument (0 by
default).

Any Wireless CORBA applications running on the terminal will need to
have the option \verb+-ORBConfFile ~/.miwcoapprc+ given on the command
line, so that they pick up the terminal configuration file and know
that they are on the mobile terminal.

The machine on the fixed network will have IP address 172.30.22.56.
Starting the server on the network side requires only the command

\small
\begin{verbatim}
  server -POAImplName Demo -ORBIIOPAddr inet:172.30.22.56:3103
\end{verbatim}

The server will output its object reference into a file called
\texttt{demo.ior}.  This file needs to be copied onto the terminal
into the client's working directory under the name \texttt{demo.ref}.
Starting the terminal server is almost the same, except the IP address
is changed to the terminal's address.  The same object reference
copying needs to be done onto the networked client.

Now the networked client can be simply started with e.g.
\texttt{client 10}.  On the terminal side, it may be necessary to add
the option \texttt{-ORBNoIIOPServer}, but this should be first tried
without it.

\subsection{Beyond the Example}

This example was written to help set up a working \MIWCO{}
configuration.  Next step would be to set up multiple Access Bridges
and have the terminal do handoffs between them.  This can be done with
the \texttt{nadmin} and \texttt{tadmin} programs, whose usage
instructions are given in the previous section.

To set up a minimalistic system exercising all of \MIWCO{}'s features,
there are scripts in the \texttt{demo/services/wireless/frame}
directory for starting all the components, and a scriptable program
controlling the system.  The example here complements nicely the
\texttt{README} file in that directory aimed at more advanced users.


\section{Implementation of MIWCO}
\label{sec:impl}

The implementation divides into several parts.  Most of the new code
is in the form of new programs in the new \texttt{coss/wireless}
subdirectory, but some changes have been made to the \MICO{} core
library.

\subsection{Modifications to the MICO Core}
\label{sec:core}

The major modifications are concentrated on the ORB and the POA.  In
addition, the IOR profiles and their associated addresses are extended
to support the unusual semantics of Mobile IORs.  Other minor
modifications have also been made.

The ORB is made the central repository of mobility-related information
on mobile terminals.  The ORB stores whether it is on a mobile
terminal, and if so, also stores the terminal identifier.  During
initialisation these values will be set based on the command line
arguments.  The IIOP proxy created during initialisation will be set
to redirect all data to the Terminal Bridge.

IIOP profiles are extended with an additional operation,
\texttt{prepare\_mobile}.  This marks the profile as being mobile so
its address will be later replaced with the HLA's (or the current
AB's) address and it will be registered with the Terminal Bridge.

The new file \texttt{watm.cc} defines the Mobile Terminal Profile and
the Home Location Component, which are a part of a complete Mobile
IOR.

The POA's object key generation is extended to create and recognise
Mobile Object Keys for objects on a mobile terminal.  This is needed
only to support GIOP 1.0 and 1.1 clients and may be removed if this
support is not desired.

Some minor modifications have been made to \MICO{}'s GIOP 1.2 support,
which was found slightly incomplete.  In particular, support for
addressing modes other than \texttt{KeyAddr} was improved to a useful
state.

\subsection{Home Location Agent}
\label{sec:hla}

The Home Location Agent consists of two objects: one implements the
location forwarding capabilities and the other implements the IDL
interface.  The latter is a regular CORBA object.

The location forwarder \texttt{HomeLocationService} is implemented as
an Object Adapter, i.e. a class inheriting from
\texttt{CORBA::ObjectAdapter}.  It registers itself as handling
objects that either have a Mobile Terminal profile or contain a Mobile
Object Key.  Naturally, in both these cases, the identified terminal
also has to belong to the Home Location Agent.  The code that does
location forwarding is quite messy, since it has to do the following
things:
\begin{enumerate}
\item handle key addressing by interpreting a Mobile Object Key
\item return \texttt{NEEDS\_ADDRESSING\_MODE} requesting IOR to GIOP
  1.2 clients
\item generate a new Mobile IOR in case of key addressing
\item replace IIOP addresses in received IORs
\end{enumerate}
It does all this to both be backward compatible and prepare for future
when Mobile Object Keys can be phased out.

\subsection{GTP Protocol Engine}
\label{sec:gtp}

The GTP protocol engine is heavily inspired by \MICO{}'s GIOP protocol
engine.  The class division and responsibilities are:
\begin{description}
\item[Context]
  ~\newline
  The \texttt{GTPInContext} and \texttt{GTPOutContext} classes contain
  information regarding the current message that needs to be shared
  with all processing entities.
\item[Codec]
  ~\newline
  The \texttt{GTPCodec} class understands the GTP syntax and has
  operations to marshal and unmarshal messages.
\item[Conn]
  ~\newline
  The \texttt{GTPConn} class encapsulates all information about a
  particular GTP connection.  This is almost exactly the same as
  \texttt{MICO::GIOPConn}; the only difference is that
  \texttt{GTPConn} does not need to assemble fragmented messages.
\item[Proxy]
  ~\newline
  The \texttt{GTPProxy} class collects the data and operations that
  are common to both its subclasses \texttt{GTPTerminal} and
  \texttt{GTPNetwork} that implement the GTP protocol handling on the
  terminal and network side.

  The connections are managed by attaching a unique identifier to each
  connection and collecting all needed information in various maps
  indexed by this identifier.  This is done on both sides, since
  connection information needs to be preserved for forwarding even
  after the connection is closed.
\end{description}

New tunneling protocols can be added the same way that new transports
are added to \MICO{}.  A tunneling protocol needs to specify an
address format and a reliable adaptation layer.  The address format is
implemented by subclassing \texttt{CORBA::Address} and
\texttt{CORBA::AddressParser} and the adaptation layer by subclassing
\texttt{CORBA::Transport} and \texttt{CORBA::TransportServer}.  The
new transport needs to provide the reliability and ordered delivery
guarantees that are assumed by both GTP and GIOP.  In addition, the
new address format needs to be recognised by methods in the
\texttt{GTPAddress} class (in \texttt{proxy.cc}) and the
\texttt{AccessBridge\_impl} constructor (in
\texttt{AccessBridge\_impl.cc}).

\subsection{Bridges}
\label{sec:br}

The implementation of the Terminal Bridge and the Access Bridge is
fundamentally the same.  Figure~\ref{fig:br} gives two views of the
structure.  In the process-level structure, CORBA objects are
symbolised by circles.  In the object-level structure, an interaction
between classes is shown by having them touch each other.  A circular
arc symbolises a network listening point.

\begin{figure}[htb]
  \centering
  \begin{tabular}{c@{\hspace{1cm}}c}
    \scalebox{1.5}{
    \begin{xy}
      (5,10)*+[F]\txt\tiny{Terminal\\Bridge}="tb1"
      ;0*+[o]+[F]{}="o11"**@{-}?>*@{>}
      ,(10,0)*+[o]+[F]{}="o12"**@{-}?<*@{<}
      ;"tb1"."o11"."o12"*++[F-]\frm{}="t1"
      ,"t1"+D*+!U\txt\scriptsize{Terminal 1}
      ;(25,10)*+[F]\txt\tiny{Terminal\\Bridge}="tb2"
      ;(20,0)*+[o]+[F]{}="o21"**@{-}?<*@{<}
      ,(30,0)*+[o]+[F]{}="o22"**@{-}?>*@{>}
      ;"tb2"."o21"."o22"*++[F-]\frm{}="t2"
      ,"t2"+D*+!U\txt\scriptsize{Terminal 2}
      ;(15,25)*++[F]\txt\tiny{Access\\Bridge}="ab"
      ;"tb1"**@{.}?<*@{<},"tb2"**@{.}?<*@{<}
      ,"ab";(0,22)*+[o]+[F]{}="o1"**@{-}?<*@{<}
      ,(0,28)*+[o]+[F]{}="o2"**@{-}?>*@{>}
      ;(-3,18);(33,18)**@{=}?>*!RD+!/_.5ex/\txt\scriptsize{Internet}
    \end{xy}}
    &
    \scalebox{1.5}{
      \begin{xy}
        (0,5)*+[F]\txt<4.5em>\tiny{GTPTerminal}="t"
        ;"t"+LD*+!LU[F]\txt\tiny{Glue}="tg"
        ;"tg"+LD*+!LU[F]\txt<4.5em>\tiny{TerminalBridge}="tb"
        ,!DC*!U\cir<3pt>{u_d}
        ;"t"+RU*+!LU[F]\composite{\txt\tiny{C\\O\\R\\B\\A}
          *!<-0.5em,0em>\txt\tiny{T\\B}}="ta"
        ;(0,15)*+[F]\txt<4.5em>\tiny{GTPNetwork}="n"
        ,!DC*!U\cir<3pt>{u_d}
        ;"n"+LU*+!LD[F]\txt\tiny{Glue}="ng"
        ;"ng"+LU*+!LD[F]\txt<4.5em>\tiny{AccessBridge}="ab"
        ,!UC*!D\cir<3pt>{d_u}
        ;"ab"+RU*+!LU[F]\composite{\txt\tiny{C\\O\\R\\B\\A}
          *!<-0.5em,0em>\txt\tiny{A\\B}}="cab"
      \end{xy}
    }
    \\
    \small Process-level structure & \small Object-level structure
  \end{tabular}
  \caption{Structure of Bridges}
  \label{fig:br}
\end{figure}

The Bridges are divided into two parts.  The GTP handling part, called
proxy in the system, was explained in section~\ref{sec:gtp}.  The
other part, called bridge, handles GIOP messages.  The GIOP handler is
much simpler than the GTP handler, since all it has to do is pass
through GIOP data.

The parts of each Bridge communicate only through the Glue interface.
This is a minimal callback interface, whose operation is modelled
after GTP's Open-Invoke-Close cycle.  The two parts register
themselves as callbacks in the other.

\end{document}
