\documentclass{article}
\usepackage{times,moreverb}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This document uses some non-standard commands from the html.sty
% package of latex2html. These are the htmlonly and latexonly
% environments, and the htmladdnormallink command. You can simply
% remove the htmlonly stuff and the \begin{latexonly},
% \end{latexonly} commands. For htmladdnormallink you can replace
% the command with its first argument (the second is the url).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{html,verbatimfiles}



\title{DRM Programming Tutorial}
\author{M\'ark Jelasity}
\date{}

\renewcommand{\verbatimtabsize}{3}

\begin{document}
\maketitle

\begin{htmlonly}
\tableofcontents
\end{htmlonly}

\section{What is this tutorial about?}

It is about writing applications which are based on the 
\htmladdnormallink{DRM API}{api/index.html}.
The DRM (distributed resource machine) is an environment for special
multiagent applications.
A DRM is a pure fully distributed peer-to-peer network of nodes
which use epidemic protocols to communicate with each other.
A DRM offers functionality supporting agents and {\em collectives} (see
Section~\ref{sec:coll}).

This tutorial is useful for those who wish to use the DRM directly
and not through higher level libraries, or those who use higher level
libraries but want to access lower level functionality as well.

Section~\ref{sec:hello} guides the user to running the famous ``Hello world!''
application.
This will give a basic idea of how a DRM application looks like and how does it
feel to run something on a DRM.
Section~\ref{sec:api} gives the reader an overview of the functionality
the applications can use.
The remaining sections discuss examples in detail.
The example in Section~\ref{sec:coll} is relatively more complex,
in fact it illustrates a potentially promising approach to writing
real and complex applications.

\section{What is this tutorial not about?}

This tutorial is a practical guide to the API documentation.
That is, it is {\em not} a class documentation {\em nor} an introduction
to the low level functioning of the DRM.
It does not contain other specifications either, like details on
configuration, tools, security, and technical details on starting experiments.
These things can be accessed in the class documentation, and
in the documents linked to the
\htmladdnormallink{overview page}{api/index.html}.
of the class documentation
in directory {\tt doc/api}\footnote{%
From now on we will assume that the reader installed the DRM properly.}.
There will be many references to that documentation throughout this document.
The html version of this document contains links to it as well.

\section{Running the first application}
\label{sec:hello}

\subsection{Setting up a local DRM}
\label{sec:drm1}

To run an application it is necessary to have a running DRM (distributed
resource machine).
A DRM is made up of a set of nodes, which are connected to each other.
The DRM does not rely on a server, the nodes communicate with each other
directly.

The idea is that there is a ``big DRM'' out there on the Internet which
unites all participating nodes.
When developing applications, it is a good idea however to set up a local DRM
and run the applications there.
The reason is that if the applications have bugs for example, it is much
harder to take action once the application is out on the big DRM.

Accordingly, we will set up a local DRM for trying out the example
applications explained in this document.
In the simplest case one can start a DRM which consists of only one node.
This is done by running the application {\tt drmnode}.
(In fact this starts the class {\tt drm.server.TestGUINode} with proper
security and classpath settings.)

It sounds simple enough.
However, already at this point we have to make a comment.
To start a DRM of one node it is necessary to make sure that no other nodes
connect to our single node.
If our computer is not on the network, it will not happen.
However, if our computer is connected to the Internet and from the same
computer a node was part of the big DRM before, there is some chance that
the big DRM remembers us and connects our node again.
To make absolutely sure that we are alone, we can use the property
``group'' which identifies the DRM.
The group of the big DRM is called ``default''. 
Any different name will prevent connection.
The group name can be configured, see the
\htmladdnormallink{configuration guide}{api/drm/server/doc-files/config.html}
in the class documentation.
The command line approach would look like this:
\begin{verbatim}
drmnode group=myUniqueGroupName
\end{verbatim}

Building of DRMs of more than one node is described in
Section~\ref{sec:mobil_drm}.

\subsection{Running an application}

The technical specification of starting experiments (jobs)
is described in the  
\htmladdnormallink{experiment starting specification}
{api/drm/server/doc-files/stexp.html} in the class documentation.
From now on we will assume that the experiment is in a jar file and not in
a directory, noting that
a directory can be more flexible when developing an application,
but the agents started from a directory and not a jar are not realy mobile
(see the 
\htmladdnormallink{experiment starting specification}
{api/drm/server/doc-files/stexp.html}).
To recompile the examples you have to include the jar {\tt drm.jar} in the
classpath.
This file can be found in the DRM installation directory, under
the directory {\tt lib/}.

To run the ``Hello world!'' application it is enough to have a DRM
of one node.
Start the node as described above.
Select the File/Run menu.
In this dialog you have to type {\tt examples/1.jar} and hit enter.
In fact you have to give an absolute pathname to {\tt 1.jar} or a relative one
from the directory the node was started in.

You should see an agent appearing in the agent list and
the text ``Hello world!'' on the screen.
After a couple of seconds the agent disappears.
Note that our agent writes to the standard output so you can see its
message only if you start the application from a console (shell).
(For example, in Windows starting drmnode by clicking its icon
will start the node,
you can start the experiment too but you will not see the message.)

\subsection{Security}

By default applications have sandbox rights, they are not allowed to write
to the disk or to initiate network connections for example.
Our simple example in {\tt 1.jar} did not need this but
we normally want our own experiments to
be allowed to write on our own local disk.
The solution is that 
it is possible to give an experiment application rights in the node
it was started in.
To achieve this, the jar file which contains the experiment must be
under the directory from which the node was started at the time of launching.
Note that this does not imply that this experiment will have application
rights anywhere else.

\subsection{The application from the inside}

The technical specification of classes to be included in an experiment
can be found in the  
\htmladdnormallink{experiment starting specification}
{api/drm/server/doc-files/stexp.html} in the class documentation.
Our job contains two classes.
The contents of the jar that contains the job looks like this:
\begin{verbatim}
hwjob/HelloWorld.class
Launch.class
\end{verbatim}
Here the class {\tt Launch} is the standard class that launches the job.
It functions like the {\tt main} method in C or Java applications.
The launcher normally launches agents.
The other class is the agent that actually performs the job.

The source code of {\tt Launch} is in Section~\ref{launch1}.
It implements the standard constructor and the Runnable interface, these are
required in each Launcher class.
The run method constructs an agent and uses the {\tt launch} method of
the node to launch it.
Launch type {\tt ``DIRECT''} means that the agent is launched to the node
address given in the third parameter which is null in our case which
means the agent is put to the node on which {\tt launch} was called.
For more information on launching you can refer to the class documentation
of \htmladdnormallink{{\tt drm.core.Node}}{api/drm/core/Node.html} and
\htmladdnormallink{{\tt drm.agentbase.IBase}}{api/drm/agentbase/IBase.html}
which is an interface implemented by {\tt Node}.

The source code of the agent is in Section~\ref{agent1}.
The source code speaks for itself, especially combined with the class
documentation of 
\htmladdnormallink{{\tt drm.agents.Agent}}{api/drm/agents/Agent.html}.
The only requirement is that an agent must implement the interface
\htmladdnormallink{{\tt drm.agentbase.IAgent}}{api/drm/agentbase/IAgent.html}.
The class \htmladdnormallink{{\tt drm.agents.Agent}}{api/drm/agents/Agent.html}
is a convenience class that makes writing agents much easier as most methods
have a default implementation.
In our case we implemented only the {\tt run} method, which simply
writes the message on the standard output.
There is one important thing to note: to stop running, and agent must
explicitly call {\tt suicide()} (line 21) which will result in removing the
agent from the environment.
Without calling this method, the agent stays alive, although it becomes
passive.
Staying alive means that it can still receive and handle messages for
example (see Section~\ref{sec:comm}).


\section{The API: an overview}
\label{sec:api}

Now that we have seen an example that actually works, it will be easier
to give a general overview of the API that is available to the developers.
Even though the basic design concepts of a job are not yet clear, this overview will help the reader navigate the 
\htmladdnormallink{class documentation}{api/index.html}
and understand the examples of the remaining sections better.
The following sections describe the different parts of the API
w.r.t.\ functionality and users.

\subsection{The interface
\htmladdnormallink{{\tt drm.agentbase.IBase}}{api/drm/agentbase/IBase.html}}
\label{sec:IBase}

\subsubsection{Functionality}

\begin{itemize}
\item Agent administration, like adding, deleting, dispatching agents, etc.
\item Information about the state of the node.
\item Message sending.
\end{itemize}

\subsubsection{Users}

\begin{itemize}
\item The launcher class, since the {\tt Node} object passed to its
constructor implements this interface.
\item The agents, after the agentbase calls their method {\tt setBase}.
This always happens when the agent is put into a base, before its
{\tt run} method is started.
\end{itemize}


\subsection{The interface
\htmladdnormallink{{\tt drm.core.IDRM}}{api/drm/core/IDRM.html}}
\label{sec:IDRM}

\subsubsection{Functionality}

Providing information about other nodes that are part of the same DRM.

\subsubsection{Users}

The agents, after the agentbase calls their method {\tt setBase}.
This always happens when the agent is put into a base, before its
{\tt run} method is started.
Extending classes of {\tt Agent} can reach it through {\tt getDRM}.

\subsection{Public and protected interface of 
\htmladdnormallink{{\tt drm.agents.Agent}}{api/drm/agents/Agent.html}}

\subsubsection{Functionality}

\begin{itemize}
\item Signs the state of the agent via the flag {\tt shouldLive}
 that must be used by extending classes
 to properly shut down any threads when this flag becomes false.
\item It provides a couple of convenience functions that simplify sending
 messages via simpler interfaces.
\item It defines methods for debugging suitable for redefinition in extending
 classes.
\item Access to the hosting environment is provided through the field
 {\tt base} and through the function {\tt getDRM()}.
\end{itemize}

\subsubsection{Users}

Agents that extend {\tt Agent}. 

\subsection{Public and protected interface of
\htmladdnormallink{{\tt drm.agents.ContributorAgent}}
{api/drm/agents/ContributorAgent.html}}

\subsubsection{Functionality}

\begin{itemize}
\item Extends {\tt Agent} by adding the functionality of being able to
participate in a {\em collective}.
In particular, it implements the interfaces
\htmladdnormallink{{\tt drm.core.Observer}}{api/drm/core/Observer.html}
and
\htmladdnormallink{{\tt drm.core.Contributor}}{api/drm/core/Contributor.html}.
Section~\ref{sec:coll} discusses collectives in more detail.
The collective can be accessed through the field {\tt collective}.
\item Implements the concept of {\em root island} in jobs.
That is, jobs will
have a root island which will serve as a bootstrap device for hooking
up new agents to the job collective.
This concept will be illustrated in Section~\ref{sec:coll}.
\end{itemize}

\subsubsection{Users}

Agents that extend {\tt ContributorAgent}.

\section{Mobility}
\label{sec:mobil}

We will illustrate mobility through an application which consists of one
agent which jumps between different nodes while counting the number of jumps.

\subsection{Setting up the DRM}
\label{sec:mobil_drm}

In the case of the first example it was sufficient to have a DRM of one node.
To illustrate jumping, we need a DRM of at least two nodes.
This can be achieved quite easily: you have to start two nodes and you have
to connect them.
Starting two nodes involves starting the application {\tt drmnode} two times.
This results in two independent (i.e.\ not connected)
DRMs each consisting of one node.

Connecting the nodes can be done using the dialog ``edit/add to node list''.
Open this dialog in the node started as {\em second} and in the simplest case
type {\tt localhost} (or the name of your computer).
If you started the nodes from a console, you should see log messages indicating
that the two nodes started to communicate.
An alternative way is to start the second node with the command line
parameter {\tt node=localhost}.

There is an important thing to keep in mind however.
If you installed the DRM software properly, you have a node which is started
up automatically and is running in the background, most likely as part of
the big DRM.
In that case if you simply type {\tt localhost} in the dialog window, this
node will be added which we do not want now as we are building a local
DRM.
You can even get an error message if the node you started is in
a different group than the default node in the background.

To solve this problem we need some insight into how port assignments
work.
The default port is 10101, and if this is taken, the next free port is
used which is 10102, etc.
However the node also remembers which port was configured at starting time
thus it is possible that you have a node which uses 10102 but knows that
it was configured to use 10101.
Simply typing {\tt localhost} means you have chosen the port which was
originally configured.
This is why you had to use the {\em second} node to connect the two nodes
on the same machine, because of course it does not make sense to add yourself
to the node list.
This feature makes more sense when you connect nodes on different computers.

To control the ports explicitly you can specify a port at startup time
It is done as follows:
\begin{verbatim}
drmnode group=myUniqueGroupName port=12345
\end{verbatim}
The default port is 10101, so you might want to set a different one
to avoid unwanted connections.
When starting the second node, you must use exactly the same command line.
The node will detect that the given port is not free and will automatically
use the next one, 12346 in this case.
Typing {\tt localhost} in this second node will asume the port
12345 as described above.

You can also specify the port explicitly in the dialog by using the syntax
as in {\tt localhost:10102} for example.

Using the procedure described above you can build a DRM of any size.
The nodes do not have to be on the same computer.
As a node it is possible to use not only the node started by {\tt drmnode}
by default, you can apply the {\tt --nogui} option which
results in starting a node without a window.
(This in fact means running the class {\tt drm.server.NakedNode}.)
This application understands the same command line arguments and
configuration files, only it does not have a graphical interface (in fact any
interface...) so it is suitable to be run in the background.
Be careful because {\tt drmnode --nogui} tries to connect to the big
DRM by default using default nodes.
To prevent this, you can use a different group name
(see Section~\ref{sec:drm1}).

\subsection{The application from the inside}

The jumper application is in {\tt examples/2.jar}.
It is advisable to set up a local DRM of two nodes with a graphical interface
started from to different consoles,
and start this application on any of the nodes.
The agent starts jumping immediately and writes messages to the consoles
as well.

The launcher class (Section~\ref{launch2}) is almost identical to that of
the first example.
The code of the agent is in Section~\ref{agent2}.
The agent uses the {\tt IDRM} interface (Section~\ref{sec:IDRM}) to get
information about the other nodes in the DRM.
Its actions are determined by this information, and a serializable field
that counts the jumps (line 12).
The value of this field is preserved according the java object serialization
principles when the agent is traveling to another node.

\section{Communication}
\label{sec:comm}

This little application involves an agent which itself launches another
agent, sends it a message and prints the answer.
It illustrates message sending and the fact that agents can create and launch
agents as well through the {\tt IBase} interface they access
(Section~\ref{sec:IBase}).

The application works on a single node or on a DRM with many nodes as well.
Start the file {\tt examples/3.jar} from a node.

The launcher class has the same simple structure again (Section~\ref{launch3}).
The agent is in Section~\ref{agent3}.
The agent started first has the full name
{\tt Talker.test-<time>.1} as determined by the launcher and the agent.
The agent started by the first agent has the same name except that it ends in
2 and not 1.
The test in line~20 checks if the running agent is the first or the second.
The second agent is passive, i.e.\ its run function exits immediately.
It only waits for messages.
The first agent attempts to launch the second agent.

Observe the usage of the interface
\htmladdnormallink{{\tt drm.agentbase.IRequest}}
{api/drm/agentbase/IRequest.html}.
Every functionality that is related to communication is asynchronous.
This is because the system is supposed to work under very poor conditions
as well.
The methods that implement these functionalities return
an {\tt IRequest} object.
If you want to make sure an operation was successful, you have to wait
until it is finished and check its status, like this agent does.

Asynchronous operations often return some information too which is
always documented in the API documentation of the corresponding method.
In the case of launch, you can ask for the address of the launched agent
if the launch was successful and the launch type is {\tt ``RANDOM''}
(line 31).
In the case of message sending, you can ask for the reply (line 39).

The agent overrides the default implementation of {\tt handleMessage}.
This method is called by the node if the agent receives a message.
The task of this method is to handle the message, i.e.\ do something and/or
reply.
It does not matter if the agent is passive or active (i.e.\ its run method
is still running) when it receives a message.

Line 48 has to be always the first line of every handleMessage method
that overrides the same method of the super class.
The reason is that the super class may also want to handle some messages
which might be of crucial importance to the functioning of the DRM.
It is also important to return false if the message could not be handled
to allow correct message propagation and error handling.
This implementation handles messages of type ``test'' and always replies
with the string ``Fine thanks.'' independently of the content of the message.

\section{Collectives and more}
\label{sec:coll}

After getting familiar with the agent functionality like mobility and
messages, we now discuss the powerful concept of {\em collectives}, and
an application template that fits well into this framework.
The application will be an optimizer which searches for the maximum of
a one dimensional real valued function.
Note that this is an illustration only, what matters is the way the
application is put together.

\subsection{Collectives}

A collective is a set of entities (agents, humans etc) who work
together to achieve a goal.
The main concept of a collective is the {\em contribution repository}.
Members of a collective who are {\em observers} can read this repository
and {\em contributors} can write it.
The philosophy behind this model is that the goal of the collective is solved
by the participants via generating contributions using the contributions
of the others.
These new contributions then help the others to generate contributions, and
so on.
During this process the state of the collective should converge to the goal.

The collective contains a command database as well, which can be written by
members who are {\em controllers}.
The members of the collective should perform the commands in the database.

A job can be a collective.
The class
\htmladdnormallink{{\tt drm.agents.ContributorAgent}}
{api/drm/agents/ContributorAgent.html} extends
{\tt Agent} with the functionality of participating in a collective.
That is, if an application wants to be a collective, it can use
agents that extend {\tt ContributorAgent}.
The interface is very simple.
To fulfill the role of a contributor, the agent has to override the method
{\tt getContribution} which must return the most recent contribution
of the agent when called by the collective.
To query the contribution repository, the agent can use the public
interface of the field {\tt collective} which is of type
\htmladdnormallink{{\tt drm.core.Collective}}
{api/drm/core/Collective.html}.

To actually build the collective, {\tt ContributorAgent} uses a default
and reliable agent, the {\em root} agent.
The role of this agent is that when new agents have to be added to the
collective, the information which is necessary for this operation is
fetched from this agent.
(Note that other, more robust implementations of building a collective
are possible as well, and can be expected in the future.)
The root has no further role, only if it is given a further role by the
application developer.
In our example the root saves the contributions of the rest of the agents
to disk during the running of the job.

\subsection{The Files}

The listing of {\tt examples/4.jar} looks like this:
\begin{verbatim}
Launcher.class
config.properties
drmhc/HillClimber.class
drmhc/Algorithm.class
\end{verbatim}
The difference from the previous examples is the presence of a
configuration file in the root directory,
and a helper class in package {\tt drmhc}.
Classes of the experiment can load the configuration file as a system resource,
as we will see later, which offers a possibility to configure experiments.

\subsection{The Launcher}

This application has a more sophisticated launcher (Section~\ref{launch4}).
It is more sophisticated because (apart from defining a separate method
for launching) it does three things more:

\begin{itemize}
\item Error checking: using the request handler it makes the asynchronous
launch operation look synchronous to the run method.
In general it is not a good practice because the launcher might hang but
it illustrates how to use request handlers.
\item Root agent: It launches a root agent separately and then passes
its address to all the new agents.
This is the proper way to start up a collective using a root agent.
\item Configuration file: It loads the configuration file (line 66) from
the classpath as a system resource (see Section~\ref{props4}).
\end{itemize}

\subsection{The Agent}

The run method of the agent performs a stochastic hillclimber search on the
function {\tt drmhc.Algorithm.eval()} (see Section~\ref{class4}).
{\tt drmhc.Algorithm.mutate()} is used as a search operator.
The agent is mobile, i.e.\ it can be relocated while running, because all
serializable fields of the agent will keep their values.
The algorithm can be configured using the configuration file (line 49)
(see Section~\ref{props4}).
When finished, the agent exits, except if it is the root which is supposed
to collect results (line 69) so it stays alive going passive.

In method {\tt getContribution} the agent returns the best known solution.
This is the value that is going to be written to the contribution repository
time to time.
Note that the class type of the contribution (in other words the data model
of the application) is fully application dependent.

The agent could check the field {\tt collective} for contributions of others.
However, there is another possibility.
The collective calls {\tt collectiveUpdated} when new information
arrives (line 92).
Our agent uses this notification to exploit the new contributions.
This is the point when the (hopefully) positive effect of learning from
others manifests itself.

The root agent tries to save this information as well.
The idea is that the root agent is running on the computer of the experimenter
so it should be possible.
Agents that run on remote nodes which are normally configured to support
the sandbox security model will not be able to write anything to the disk.
The filename used to save the contributions is configurable, see
Section~\ref{props4}.

Note that this is a toy example only to illustrate the basic idea.
More clever launching and logging could have been implemented easily as well,
our intention was to keep things as simple as possible.

\appendix

%===================================================================

\begin{htmlonly}
\section{Launch}
\label{launch1}
\verbatimlisting{examples/1/Launch.java}
\section{hwjob.HelloWorld}
\label{agent1}
\verbatimlisting{examples/1/hwjob/HelloWorld.java}
\section{Launch}
\label{launch2}
\verbatimlisting{examples/2/Launch.java}
\section{jumperjob.Jumper}
\label{agent2}
\verbatimlisting{examples/2/jumperjob/Jumper.java}
\section{Launch}
\label{launch3}
\verbatimlisting{examples/3/Launch.java}
\section{talkjob.Talker}
\label{agent3}
\verbatimlisting{examples/3/talkjob/Talker.java}
\section{Launch}
\label{launch4}
\verbatimlisting{examples/4/Launch.java}
\section{drmhc.HillClimber}
\label{agent4}
\verbatimlisting{examples/4/drmhc/HillClimber.java}
\section{drmhc.Algorithm}
\label{class4}
\verbatimlisting{examples/4/drmhc/Algorithm.java}
\section{config.properties}
\label{props4}
\verbatimlisting{examples/4/doc-files/config.properties}
\end{htmlonly}

%===================================================================

\begin{latexonly}
\pagebreak
\section{Launch}
\label{launch1}
%\verbatimtabinput[4]{../examples/1/Launch.java}
\listinginput{1}{examples/1/Launch.java}
\pagebreak
\section{hwjob.HelloWorld}
\label{agent1}
\listinginput{1}{examples/1/hwjob/HelloWorld.java}
\pagebreak
\section{Launch}
\label{launch2}
\listinginput{1}{examples/2/Launch.java}
\pagebreak
\section{jumperjob.Jumper}
\label{agent2}
\listinginput{1}{examples/2/jumperjob/Jumper.java}
\pagebreak
\section{Launch}
\label{launch3}
\listinginput{1}{examples/3/Launch.java}
\pagebreak
\section{talkjob.Talker}
\label{agent3}
\listinginput{1}{examples/3/talkjob/Talker.java}
\pagebreak
\section{Launch}
\label{launch4}
\listinginput{1}{examples/4/Launch.java}
\pagebreak
\section{drmhc.HillClimber}
\label{agent4}
\listinginput{1}{examples/4/drmhc/HillClimber.java}
\pagebreak
\section{drmhc.Algorithm}
\label{class4}
\listinginput{1}{examples/4/drmhc/Algorithm.java}
\pagebreak
\section{config.properties}
\label{props4}
\listinginput{1}{examples/4/doc-files/config.properties}
\end{latexonly}

\end{document}

