\documentstyle{article}
\title{\Large\sf RIDL\\ \small\sf Remote Invocation Description Language}
\author{Johan Ovlinger \\ \small Based on work by \\ Crista Lopes}

\setlength{\textwidth}{6.5 in}
\setlength{\oddsidemargin}{0.0 in}
\setlength{\evensidemargin}{0.0 in}
\setlength{\textheight}{9.0 in}
\setlength{\topmargin}{-0.5 in}


\begin{document}
\maketitle

\def\ridl{{\sf RIDL}}

\section{Intro}

\ridl\ is demjava's aspect language for remote invocation. 
Basically, it is a wrapper around java's RMI.
This in itself is reason enough to use it; it allows the user to access remote objects and operations in a transparent manner. 
Furthermore, it allows the user to specify how arguments and results are to be passed; by copy (full or partial) or by reference. 

\ridl\ offers nothing that cannot be achieved using RMI, but the same can be said about assembly langauge. 
\ridl's main selling point is that it separates out the remote aspect of an application to a separate specification; the behavioral part of the application is the same\footnote{Object instantiation is slightly different, but a little bit. It's still better than RMI.} for both a remote or local application. 
RMI requires a significant reworking of the application when moving to a remote setting. 

\subsection{A small example}

I always find it easier to learn a new concept with a simple example to illustrate. 
So here, even before I've defined the terms necessary to describe it, is a small local application, written in the std demjava behavior style. 

\begin{small}
\noindent
\begin{tabular}{ll}
\hline 
\multicolumn{2}{c}{\tt THE BEHAVIOR}  \\
\hline \\
\begin{minipage}{2.8in}
\begin{verbatim}
Counter {
 (@
  private IntHolder counter;
  @)
  public void reset(IntHolder i ) (@
    System.err.println("reset "+i.toString());
    counter = i;
  @)
  public IntHolder get_next() (@
    System.err.println("++"+counter.get_val());
    counter.set_val(counter.get_val()+1);
    return  new IntHolder(counter.get_val());
  @)
}
IntHolder { 
  public String toString() (@ 
   return "IntHolder "+get_val(); 
  @)
}
\end{verbatim}
\end{minipage}
&
\begin{minipage}{3in}
\begin{verbatim}
User {
  public static void main(String[] args) (@
    // ifndef RIDL
    Counter c1 = new Counter(); 
    // else
    /*
    String host1 = args[0];
    int port    = Integer.parseInt(args[1]);
    Counter c1 = (Counter) RIDL_Runtime.RIDL_Naming.
                     remotenew("Counter",host1,port);
    */
    // endif
    c1.reset(new IntHolder(10));
    for (int i =0;i<10;i++) {
      IntHolder i1 = c1.get_next();
      System.err.println(host1+" "+i1.get_val());
    }
  @)
}

\end{verbatim}
\end{minipage}
\end{tabular}

The application is a really simple one; a counter is created. 
It is incremented a number of times. Wow. 
The version shown is a simple vanilla java program. 

Now our evil boss comes in and says that all design criteria have changed! 
Now the counter object should reside be on another machine. 
All our work is for naught! 
Ha ha ha!

As the heroes of this little fable, we of course get the last laugh. 
Armed with our magical \ridl er capabilities, we quickly cobble up a \ridl\ description file, and make a few minor changes to the application (shown in the {\tt ifndef} comments), and our counter works on remote machines too.

\begin{tabular}{l|l}
\hline 
{\tt THE CD FILE } & {\tt THE RIDL FILE } \\
\hline \\

\begin{minipage}{3in}
\begin{verbatim}
*noparse*
User = .
*public* Counter = .
IntHolder = <val> int.
\end{verbatim}
\end{minipage}
 
&

\begin{minipage}{3in}
\begin{verbatim}
portal Counter { 
  public void reset(IntHolder i)
    i: copy ;
  public IntHolder get_next()
    return: gref;
}
portal IntHolder {
  public int get_val();
  public void set_val(int val);
}
\end{verbatim}
\end{minipage}
\end{tabular}
\end{small}


\subsection{Explanation}

The secret to our magical abilities is the \ridl er. 
It reads our specification and modifies the behavior and structural aspects (specified by {\tt *.beh} and {\tt *.cd} files, resp.).
Exactly how this is done not specified here. 
Crista Lopes's thesis covers these details. 

The program we wrote in response to the boss's requirements does the following:
 a {\tt User} object resides locally. It creates a remote instance of the {\tt Counter} on some other machine {\tt host1}. 
That machine must be running a \ridl\ naming service, which is a thin wrapper around RMI's naming service. 
\ridl's naming service creates an instance of {\tt Counter}, and returns a remote reference (a so called {\tt gref}) to {\tt User}.

{\tt User} now resets the counter and gets the 10 next numbers. 
The \ridl\ specification specifies that {\tt reset} should pass its initial valu e by copy (for illustrative purposes only).
Also, {\tt get\_next} passes its result as a {\tt gref}. 

\section{Reference manual}

Enough handholding. Here are the details.

\subsection{Gref or Copy}

An object can be either local or remote. 
\ridl\ deals with remote method invokation- or more accurately, invoking methods (and passing arguments and results) on remote objects.
Given a remote object to invoke methods on, we can either pass arguments to that method by copy or as a remote reference.

When something is passed by copy, a copy is made and reinstantiated on the remote machine. 
Java calls this serialization. 
\ridl\ allows the user to specify which part of the object needs to be copied (for some operations, perhaps we know that some part of the object will not be needed). 

A gref is a remote reference. 
The main object resides on the remote machine, and only a proxy object exists locally. 
The proxy object forwards all method calls to the remote object. 

The tradeoff is that passing an object by copy can be slow, but once passed, invoking methods is fast. Some objects require themselves to be unique (either they are too big to copy profusely, or they have semantic reasons to be unique). 

Grefs are fast to pass, but method invocation can be slow.
Primitive values cannot be passed by gref. 

\subsection{Portals}

A \ridl\ specification file is a sequence of portals.

A class needs a portal if it is to be passed as an argument to a remote object's method, or if it is to be a remote object itself. 

\begin{verbatim}
Portal = "portal" ClassName [PortalBody]. }
PortalBody = "{" MethodList "}".
\end{verbatim}

In addition to just having a portal, a class can also have a portalbody. 
The portal body specifies which methods can be called on a remote (gref) object. 
The signature of each method that is to be callable needs to be listed in the portal body.

Optionally, we can specify how an argument or result is passed. 
The options are remote reference {\tt gref}, full copy {\tt copy}, or partial copy {\tt copy:} {\em traversal-name}. 
Passing by gref, the object stays on the machine it currently resides on, and a pointer to it is passed. 
This is akin to java {\tt remote} objects.
The partial copy created is exactly the subobject reachable via the given traversal.
A full copy is what java serialization offers. 
The default passing discipline is by full copy.

\fbox{
\begin{minipage}{6in}
{\bf pitfall:}
Note that if we have an object that {\em is} a copy (full or partial) of some other object, we can pass it as a gref.
However, we cannot pass a gref object as a copy unless the traversal method's signature is included in the class's portal.
We can never one by full copy. 

{\bf bug:} 
A method signature must be listed in the portal for the class where it is defined.
 If a method is inherited from a superclass, we must put the method spec on the portal for the class it is inherited from (which is perhaps not what we wanted- perhaps we don't want instances of the superclass to be remotable). 
Alternately we can create a method w/ that name and signature in this class, and have it delegate to super. 
Since the method now {\em is} defined locally, we can have a method portal. The bug is that this isn't done automatically.

{\bf bug:}
Calling non-remote methods on a remote objects will fail silently.
One unfortunate side-effect of weaving together many aspects is that it is almost impossible to statically destermine which methods will be visible on a given class. 
Thus, the \ridl er is unable to generate code to disable calling of non-remote methods (ie the methods on a class with a portal that do not have a method spec). 
\end{minipage}	
}

\subsection{Instatiation}

One of the more annoying aspects about using RMI is that object instatiation is very roundabout. 
To alleviate this, \ridl\ offers an object instantiation service. 

To use it, the \ridl\ naming server must be started on a remote machine.
It needs to see in its {\tt CLASSPATH} all the classes it is to be able to instantiate, and needs to be passed a port number to listen to. 
F.ex to start the naming server on port 1234, you could issue the command:

\mbox{{\tt > java RIDL\_Runtime.RIDL\_Naming 1234}}

The class {\tt RIDL\_Runtime.RIDL\_Naming} is included in {\tt demjava.jar}. 

To then use this server (supposedly running on host {\tt bar}) to instatitate an instance of class {\sf Foo}, one would say

\mbox{\tt Foo afoo = RIDL\_Runtime.RIDL\_Naming.remotenew("Foo","bar",1234); }

This was illustrated in the earlier example. {\tt afoo} is a gref (as it doesn't make sense to instantiate an object on a remote machine and return the result by copy), so {\sf Foo} needs to have a portal specification for this to work.

\subsubsection{Naming}

\ridl\ also supports an RMI-like naming service (which is hinted at by the name {\tt RIDL\_Naming}). 
To create an object on a remote machine and bind it to the name {\tt ``erik''} ({\bf NB:} this operation returns void):

\mbox{\tt RIDL\_Runtime.RIDL\_Naming.remotenew("Foo","bar",1234,"erik"); }

We can now look up {\tt ``erik''} in that registry by saying:

\mbox{\tt Foo afoo = RIDL\_Runtime.RIDL\_Naming.lookup("bar",1234,"erik"); }

\section{Turning it on}

\ridl\ is enabled by adding a {\tt RIDLFILES} entry to the project file of your application.
For example, if you have your portals in two files {\tt foo.ridl} and {\tt bar.ridl} you would add the line \mbox{\tt RIDLFILES = foo.ridl bar.ridl} to your project file.


\end{document}